forked from mirrors/gstreamer-rs
b273c4e8bf
Rerunning it on existing files doesn't perform all whitespace cleanup when nodes are not modified.
55118 lines
2.6 MiB
55118 lines
2.6 MiB
<?xml version="1.0"?>
|
|
<!-- This file was automatically generated from C sources - DO NOT EDIT!
|
|
To affect the contents of this file, edit the original C definitions,
|
|
and/or use gtk-doc annotations. -->
|
|
<repository xmlns="http://www.gtk.org/introspection/core/1.0" xmlns:c="http://www.gtk.org/introspection/c/1.0" xmlns:glib="http://www.gtk.org/introspection/glib/1.0" version="1.2">
|
|
<package name="glib-2.0"/>
|
|
<c:include name="glib.h"/>
|
|
<namespace name="GLib" version="2.0" shared-library="libgobject-2.0.so.0,libglib-2.0.so.0" c:identifier-prefixes="G" c:symbol-prefixes="g,glib">
|
|
<alias name="DateDay" c:type="GDateDay">
|
|
<doc xml:space="preserve">Integer representing a day of the month; between 1 and 31.
|
|
#G_DATE_BAD_DAY represents an invalid day of the month.</doc>
|
|
<type name="guint8" c:type="guint8"/>
|
|
</alias>
|
|
<alias name="DateYear" c:type="GDateYear">
|
|
<doc xml:space="preserve">Integer representing a year; #G_DATE_BAD_YEAR is the invalid
|
|
value. The year must be 1 or higher; negative (BC) years are not
|
|
allowed. The year is represented with four digits.</doc>
|
|
<type name="guint16" c:type="guint16"/>
|
|
</alias>
|
|
<alias name="MainContextPusher" c:type="GMainContextPusher">
|
|
<doc xml:space="preserve">Opaque type. See g_main_context_pusher_new() for details.</doc>
|
|
<type name="none" c:type="void"/>
|
|
</alias>
|
|
<alias name="MutexLocker" c:type="GMutexLocker">
|
|
<doc xml:space="preserve">Opaque type. See g_mutex_locker_new() for details.</doc>
|
|
<type name="none" c:type="void"/>
|
|
</alias>
|
|
<alias name="Pid" c:type="GPid">
|
|
<doc xml:space="preserve">A type which is used to hold a process identification.
|
|
|
|
On UNIX, processes are identified by a process id (an integer),
|
|
while Windows uses process handles (which are pointers).
|
|
|
|
GPid is used in GLib only for descendant processes spawned with
|
|
the g_spawn functions.</doc>
|
|
<type name="gint" c:type="int"/>
|
|
</alias>
|
|
<alias name="Quark" c:type="GQuark">
|
|
<doc xml:space="preserve">A GQuark is a non-zero integer which uniquely identifies a
|
|
particular string. A GQuark value of zero is associated to %NULL.</doc>
|
|
<type name="guint32" c:type="guint32"/>
|
|
</alias>
|
|
<alias name="RWLockReaderLocker" c:type="GRWLockReaderLocker">
|
|
<doc xml:space="preserve">Opaque type. See g_rw_lock_reader_locker_new() for details.</doc>
|
|
<type name="none" c:type="void"/>
|
|
</alias>
|
|
<alias name="RWLockWriterLocker" c:type="GRWLockWriterLocker">
|
|
<doc xml:space="preserve">Opaque type. See g_rw_lock_writer_locker_new() for details.</doc>
|
|
<type name="none" c:type="void"/>
|
|
</alias>
|
|
<alias name="RecMutexLocker" c:type="GRecMutexLocker">
|
|
<doc xml:space="preserve">Opaque type. See g_rec_mutex_locker_new() for details.</doc>
|
|
<type name="none" c:type="void"/>
|
|
</alias>
|
|
<alias name="RefString" c:type="GRefString">
|
|
<doc xml:space="preserve">A typedef for a reference-counted string. A pointer to a #GRefString can be
|
|
treated like a standard `char*` array by all code, but can additionally have
|
|
`g_ref_string_*()` methods called on it. `g_ref_string_*()` methods cannot be
|
|
called on `char*` arrays not allocated using g_ref_string_new().
|
|
|
|
If using #GRefString with autocleanups, g_autoptr() must be used rather than
|
|
g_autofree(), so that the reference counting metadata is also freed.</doc>
|
|
<type name="gchar" c:type="char"/>
|
|
</alias>
|
|
<alias name="Strv" c:type="GStrv">
|
|
<doc xml:space="preserve">A typedef alias for gchar**. This is mostly useful when used together with
|
|
g_auto().</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</alias>
|
|
<alias name="Time" c:type="GTime" deprecated="1" deprecated-version="2.62">
|
|
<doc xml:space="preserve">Simply a replacement for `time_t`. It has been deprecated
|
|
since it is not equivalent to `time_t` on 64-bit platforms
|
|
with a 64-bit `time_t`. Unrelated to #GTimer.
|
|
|
|
Note that #GTime is defined to always be a 32-bit integer,
|
|
unlike `time_t` which may be 64-bit on some systems. Therefore,
|
|
#GTime will overflow in the year 2038, and you cannot use the
|
|
address of a #GTime variable as argument to the UNIX time()
|
|
function.
|
|
|
|
Instead, do the following:
|
|
|[<!-- language="C" -->
|
|
time_t ttime;
|
|
GTime gtime;
|
|
|
|
time (&ttime);
|
|
gtime = (GTime)ttime;
|
|
]|</doc>
|
|
<doc-deprecated xml:space="preserve">This is not [Y2038-safe](https://en.wikipedia.org/wiki/Year_2038_problem).
|
|
Use #GDateTime or #time_t instead.</doc-deprecated>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</alias>
|
|
<alias name="TimeSpan" c:type="GTimeSpan">
|
|
<doc xml:space="preserve">A value representing an interval of time, in microseconds.</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</alias>
|
|
<alias name="Type" c:type="GType">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</alias>
|
|
<function-macro name="ALIGNOF" c:identifier="G_ALIGNOF" version="2.60" introspectable="0">
|
|
<doc xml:space="preserve">Return the minimal alignment required by the platform ABI for values of the given
|
|
type. The address of a variable or struct member of the given type must always be
|
|
a multiple of this alignment. For example, most platforms require int variables
|
|
to be aligned at a 4-byte boundary, so `G_ALIGNOF (int)` is 4 on most platforms.
|
|
|
|
Note this is not necessarily the same as the value returned by GCC’s
|
|
`__alignof__` operator, which returns the preferred alignment for a type.
|
|
The preferred alignment may be a stricter alignment than the minimal
|
|
alignment.</doc>
|
|
<parameters>
|
|
<parameter name="type">
|
|
<doc xml:space="preserve">a type-name</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="ANALYZER_ANALYZING" value="1" c:type="G_ANALYZER_ANALYZING">
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<function-macro name="APPROX_VALUE" c:identifier="G_APPROX_VALUE" version="2.58" introspectable="0">
|
|
<doc xml:space="preserve">Evaluates to a truth value if the absolute difference between @a and @b is
|
|
smaller than @epsilon, and to a false value otherwise.
|
|
|
|
For example,
|
|
- `G_APPROX_VALUE (5, 6, 2)` evaluates to true
|
|
- `G_APPROX_VALUE (3.14, 3.15, 0.001)` evaluates to false
|
|
- `G_APPROX_VALUE (n, 0.f, FLT_EPSILON)` evaluates to true if `n` is within
|
|
the single precision floating point epsilon from zero</doc>
|
|
<parameters>
|
|
<parameter name="a">
|
|
<doc xml:space="preserve">a numeric value</doc>
|
|
</parameter>
|
|
<parameter name="b">
|
|
<doc xml:space="preserve">a numeric value</doc>
|
|
</parameter>
|
|
<parameter name="epsilon">
|
|
<doc xml:space="preserve">a numeric value that expresses the tolerance between @a and @b</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="ASCII_DTOSTR_BUF_SIZE" value="39" c:type="G_ASCII_DTOSTR_BUF_SIZE">
|
|
<doc xml:space="preserve">A good size for a buffer to be passed into g_ascii_dtostr().
|
|
It is guaranteed to be enough for all output of that function
|
|
on systems with 64bit IEEE-compatible doubles.
|
|
|
|
The typical usage would be something like:
|
|
|[<!-- language="C" -->
|
|
char buf[G_ASCII_DTOSTR_BUF_SIZE];
|
|
|
|
fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
|
|
]|</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<function-macro name="ATEXIT" c:identifier="g_ATEXIT" introspectable="0">
|
|
<parameters>
|
|
<parameter name="proc">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<record name="Array" c:type="GArray" glib:type-name="GArray" glib:get-type="g_array_get_type" c:symbol-prefix="array">
|
|
<doc xml:space="preserve">Contains the public fields of a GArray.</doc>
|
|
<field name="data" writable="1">
|
|
<doc xml:space="preserve">a pointer to the element data. The data may be moved as
|
|
elements are added to the #GArray.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</field>
|
|
<field name="len" writable="1">
|
|
<doc xml:space="preserve">the number of elements in the #GArray not including the
|
|
possible terminating zero element.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<function name="append_vals" c:identifier="g_array_append_vals" introspectable="0">
|
|
<doc xml:space="preserve">Adds @len elements onto the end of the array.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to the elements to append to the end of the array</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of elements to append</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="binary_search" c:identifier="g_array_binary_search" version="2.62" introspectable="0">
|
|
<doc xml:space="preserve">Checks whether @target exists in @array by performing a binary
|
|
search based on the given comparison function @compare_func which
|
|
get pointers to items as arguments. If the element is found, %TRUE
|
|
is returned and the element’s index is returned in @out_match_index
|
|
(if non-%NULL). Otherwise, %FALSE is returned and @out_match_index
|
|
is undefined. If @target exists multiple times in @array, the index
|
|
of the first instance is returned. This search is using a binary
|
|
search, so the @array must absolutely be sorted to return a correct
|
|
result (if not, the function may produce false-negative).
|
|
|
|
This example defines a comparison function and search an element in a #GArray:
|
|
|[<!-- language="C" -->
|
|
static gint*
|
|
cmpint (gconstpointer a, gconstpointer b)
|
|
{
|
|
const gint *_a = a;
|
|
const gint *_b = b;
|
|
|
|
return *_a - *_b;
|
|
}
|
|
...
|
|
gint i = 424242;
|
|
guint matched_index;
|
|
gboolean result = g_array_binary_search (garray, &i, cmpint, &matched_index);
|
|
...
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @target is one of the elements of @array, %FALSE otherwise.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GArray.</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="target" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a pointer to the item to look up.</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="compare_func" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GCompareFunc used to locate @target.</doc>
|
|
<type name="CompareFunc" c:type="GCompareFunc"/>
|
|
</parameter>
|
|
<parameter name="out_match_index" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location
|
|
for the index of the element, if found.</doc>
|
|
<type name="guint" c:type="guint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="copy" c:identifier="g_array_copy" version="2.62" introspectable="0">
|
|
<doc xml:space="preserve">Create a shallow copy of a #GArray. If the array elements consist of
|
|
pointers to data, the pointers are copied but the actual data is not.</doc>
|
|
<return-value transfer-ownership="container">
|
|
<doc xml:space="preserve">A copy of @array.</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GArray.</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="free" c:identifier="g_array_free" introspectable="0">
|
|
<doc xml:space="preserve">Frees the memory allocated for the #GArray. If @free_segment is
|
|
%TRUE it frees the memory block holding the elements as well. Pass
|
|
%FALSE if you want to free the #GArray wrapper but preserve the
|
|
underlying array for use elsewhere. If the reference count of
|
|
@array is greater than one, the #GArray wrapper is preserved but
|
|
the size of @array will be set to zero.
|
|
|
|
If array contents point to dynamically-allocated memory, they should
|
|
be freed separately if @free_seg is %TRUE and no @clear_func
|
|
function has been set for @array.
|
|
|
|
This function is not thread-safe. If using a #GArray from multiple
|
|
threads, use only the atomic g_array_ref() and g_array_unref()
|
|
functions.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the element data if @free_segment is %FALSE, otherwise
|
|
%NULL. The element data should be freed using g_free().</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="free_segment" transfer-ownership="none">
|
|
<doc xml:space="preserve">if %TRUE the actual element data is freed as well</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="get_element_size" c:identifier="g_array_get_element_size" version="2.22" introspectable="0">
|
|
<doc xml:space="preserve">Gets the size of the elements in @array.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">Size of each element, in bytes</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="insert_vals" c:identifier="g_array_insert_vals" introspectable="0">
|
|
<doc xml:space="preserve">Inserts @len elements into a #GArray at the given index.
|
|
|
|
If @index_ is greater than the array’s current length, the array is expanded.
|
|
The elements between the old end of the array and the newly inserted elements
|
|
will be initialised to zero if the array was configured to clear elements;
|
|
otherwise their values will be undefined.
|
|
|
|
If @index_ is less than the array’s current length, new entries will be
|
|
inserted into the array, and the existing entries above @index_ will be moved
|
|
upwards.
|
|
|
|
@data may be %NULL if (and only if) @len is zero. If @len is zero, this
|
|
function is a no-op.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="index_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index to place the elements at</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a pointer to the elements to insert</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of elements to insert</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="new" c:identifier="g_array_new" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GArray with a reference count of 1.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="zero_terminated" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the array should have an extra element at
|
|
the end which is set to 0</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
<parameter name="clear_" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if #GArray elements should be automatically cleared
|
|
to 0 when they are allocated</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
<parameter name="element_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of each element in bytes</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="prepend_vals" c:identifier="g_array_prepend_vals" introspectable="0">
|
|
<doc xml:space="preserve">Adds @len elements onto the start of the array.
|
|
|
|
@data may be %NULL if (and only if) @len is zero. If @len is zero, this
|
|
function is a no-op.
|
|
|
|
This operation is slower than g_array_append_vals() since the
|
|
existing elements in the array have to be moved to make space for
|
|
the new elements.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a pointer to the elements to prepend to the start of the array</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of elements to prepend, which may be zero</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ref" c:identifier="g_array_ref" version="2.22" introspectable="0">
|
|
<doc xml:space="preserve">Atomically increments the reference count of @array by one.
|
|
This function is thread-safe and may be called from any thread.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">The passed in #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_index" c:identifier="g_array_remove_index" introspectable="0">
|
|
<doc xml:space="preserve">Removes the element at the given index from a #GArray. The following
|
|
elements are moved down one place.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="index_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the element to remove</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_index_fast" c:identifier="g_array_remove_index_fast" introspectable="0">
|
|
<doc xml:space="preserve">Removes the element at the given index from a #GArray. The last
|
|
element in the array is used to fill in the space, so this function
|
|
does not preserve the order of the #GArray. But it is faster than
|
|
g_array_remove_index().</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a @GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="index_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the element to remove</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_range" c:identifier="g_array_remove_range" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Removes the given number of elements starting at the given index
|
|
from a #GArray. The following elements are moved to close the gap.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a @GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="index_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the first element to remove</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of elements to remove</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="set_clear_func" c:identifier="g_array_set_clear_func" version="2.32" introspectable="0">
|
|
<doc xml:space="preserve">Sets a function to clear an element of @array.
|
|
|
|
The @clear_func will be called when an element in the array
|
|
data segment is removed and when the array is freed and data
|
|
segment is deallocated as well. @clear_func will be passed a
|
|
pointer to the element to clear, rather than the element itself.
|
|
|
|
Note that in contrast with other uses of #GDestroyNotify
|
|
functions, @clear_func is expected to clear the contents of
|
|
the array element it is given, but not free the element itself.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="clear_func" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">a function to clear an element of @array</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="set_size" c:identifier="g_array_set_size" introspectable="0">
|
|
<doc xml:space="preserve">Sets the size of the array, expanding it if necessary. If the array
|
|
was created with @clear_ set to %TRUE, the new elements are set to 0.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the new size of the #GArray</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sized_new" c:identifier="g_array_sized_new" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GArray with @reserved_size elements preallocated and
|
|
a reference count of 1. This avoids frequent reallocation, if you
|
|
are going to add many elements to the array. Note however that the
|
|
size of the array is still 0.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="zero_terminated" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the array should have an extra element at
|
|
the end with all bits cleared</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
<parameter name="clear_" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if all bits in the array should be cleared to 0 on
|
|
allocation</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
<parameter name="element_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">size of each element in the array</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="reserved_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of elements preallocated</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sort" c:identifier="g_array_sort" introspectable="0">
|
|
<doc xml:space="preserve">Sorts a #GArray using @compare_func which should be a qsort()-style
|
|
comparison function (returns less than zero for first arg is less
|
|
than second arg, zero for equal, greater zero if first arg is
|
|
greater than second arg).
|
|
|
|
This is guaranteed to be a stable sort since version 2.32.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="compare_func" transfer-ownership="none">
|
|
<doc xml:space="preserve">comparison function</doc>
|
|
<type name="CompareFunc" c:type="GCompareFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sort_with_data" c:identifier="g_array_sort_with_data" introspectable="0">
|
|
<doc xml:space="preserve">Like g_array_sort(), but the comparison function receives an extra
|
|
user data argument.
|
|
|
|
This is guaranteed to be a stable sort since version 2.32.
|
|
|
|
There used to be a comment here about making the sort stable by
|
|
using the addresses of the elements in the comparison function.
|
|
This did not actually work, so any such code should be removed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="compare_func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">comparison function</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @compare_func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="steal" c:identifier="g_array_steal" version="2.64" introspectable="0">
|
|
<doc xml:space="preserve">Frees the data in the array and resets the size to zero, while
|
|
the underlying array is preserved for use elsewhere and returned
|
|
to the caller.
|
|
|
|
If the array was created with the @zero_terminate property
|
|
set to %TRUE, the returned data is zero terminated too.
|
|
|
|
If array elements contain dynamically-allocated memory,
|
|
the array elements should also be freed by the caller.
|
|
|
|
A short example of use:
|
|
|[<!-- language="C" -->
|
|
...
|
|
gpointer data;
|
|
gsize data_len;
|
|
data = g_array_steal (some_array, &data_len);
|
|
...
|
|
]|</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the element data, which should be
|
|
freed using g_free().</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GArray.</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="len" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">pointer to retrieve the number of
|
|
elements of the original array</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unref" c:identifier="g_array_unref" version="2.22" introspectable="0">
|
|
<doc xml:space="preserve">Atomically decrements the reference count of @array by one. If the
|
|
reference count drops to 0, all memory allocated by the array is
|
|
released. This function is thread-safe and may be called from any
|
|
thread.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GArray</doc>
|
|
<array name="GLib.Array" c:type="GArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<bitfield name="AsciiType" c:type="GAsciiType">
|
|
<member name="alnum" value="1" c:identifier="G_ASCII_ALNUM">
|
|
</member>
|
|
<member name="alpha" value="2" c:identifier="G_ASCII_ALPHA">
|
|
</member>
|
|
<member name="cntrl" value="4" c:identifier="G_ASCII_CNTRL">
|
|
</member>
|
|
<member name="digit" value="8" c:identifier="G_ASCII_DIGIT">
|
|
</member>
|
|
<member name="graph" value="16" c:identifier="G_ASCII_GRAPH">
|
|
</member>
|
|
<member name="lower" value="32" c:identifier="G_ASCII_LOWER">
|
|
</member>
|
|
<member name="print" value="64" c:identifier="G_ASCII_PRINT">
|
|
</member>
|
|
<member name="punct" value="128" c:identifier="G_ASCII_PUNCT">
|
|
</member>
|
|
<member name="space" value="256" c:identifier="G_ASCII_SPACE">
|
|
</member>
|
|
<member name="upper" value="512" c:identifier="G_ASCII_UPPER">
|
|
</member>
|
|
<member name="xdigit" value="1024" c:identifier="G_ASCII_XDIGIT">
|
|
</member>
|
|
</bitfield>
|
|
<record name="AsyncQueue" c:type="GAsyncQueue" disguised="1">
|
|
<doc xml:space="preserve">The GAsyncQueue struct is an opaque data structure which represents
|
|
an asynchronous queue. It should only be accessed through the
|
|
g_async_queue_* functions.</doc>
|
|
<method name="length" c:identifier="g_async_queue_length">
|
|
<doc xml:space="preserve">Returns the length of the queue.
|
|
|
|
Actually this function returns the number of data items in
|
|
the queue minus the number of waiting threads, so a negative
|
|
value means waiting threads, and a positive value means available
|
|
entries in the @queue. A return value of 0 could mean n entries
|
|
in the queue and n threads waiting. This can happen due to locking
|
|
of the queue or due to scheduling.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the @queue</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue.</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="length_unlocked" c:identifier="g_async_queue_length_unlocked">
|
|
<doc xml:space="preserve">Returns the length of the queue.
|
|
|
|
Actually this function returns the number of data items in
|
|
the queue minus the number of waiting threads, so a negative
|
|
value means waiting threads, and a positive value means available
|
|
entries in the @queue. A return value of 0 could mean n entries
|
|
in the queue and n threads waiting. This can happen due to locking
|
|
of the queue or due to scheduling.
|
|
|
|
This function must be called while holding the @queue's lock.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the @queue.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="lock" c:identifier="g_async_queue_lock">
|
|
<doc xml:space="preserve">Acquires the @queue's lock. If another thread is already
|
|
holding the lock, this call will block until the lock
|
|
becomes available.
|
|
|
|
Call g_async_queue_unlock() to drop the lock again.
|
|
|
|
While holding the lock, you can only call the
|
|
g_async_queue_*_unlocked() functions on @queue. Otherwise,
|
|
deadlock may occur.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="pop" c:identifier="g_async_queue_pop">
|
|
<doc xml:space="preserve">Pops data from the @queue. If @queue is empty, this function
|
|
blocks until data becomes available.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">data from the queue</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="pop_unlocked" c:identifier="g_async_queue_pop_unlocked">
|
|
<doc xml:space="preserve">Pops data from the @queue. If @queue is empty, this function
|
|
blocks until data becomes available.
|
|
|
|
This function must be called while holding the @queue's lock.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">data from the queue.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="push" c:identifier="g_async_queue_push">
|
|
<doc xml:space="preserve">Pushes the @data into the @queue. @data must not be %NULL.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">@data to push into the @queue</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="push_front" c:identifier="g_async_queue_push_front" version="2.46">
|
|
<doc xml:space="preserve">Pushes the @item into the @queue. @item must not be %NULL.
|
|
In contrast to g_async_queue_push(), this function
|
|
pushes the new item ahead of the items already in the queue,
|
|
so that it will be the next one to be popped off the queue.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="item" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to push into the @queue</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="push_front_unlocked" c:identifier="g_async_queue_push_front_unlocked" version="2.46">
|
|
<doc xml:space="preserve">Pushes the @item into the @queue. @item must not be %NULL.
|
|
In contrast to g_async_queue_push_unlocked(), this function
|
|
pushes the new item ahead of the items already in the queue,
|
|
so that it will be the next one to be popped off the queue.
|
|
|
|
This function must be called while holding the @queue's lock.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="item" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to push into the @queue</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="push_sorted" c:identifier="g_async_queue_push_sorted" version="2.10" introspectable="0">
|
|
<doc xml:space="preserve">Inserts @data into @queue using @func to determine the new
|
|
position.
|
|
|
|
This function requires that the @queue is sorted before pushing on
|
|
new elements, see g_async_queue_sort().
|
|
|
|
This function will lock @queue before it sorts the queue and unlock
|
|
it when it is finished.
|
|
|
|
For an example of @func see g_async_queue_sort().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the @data to push into the @queue</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the #GCompareDataFunc is used to sort @queue</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @func.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="push_sorted_unlocked" c:identifier="g_async_queue_push_sorted_unlocked" version="2.10" introspectable="0">
|
|
<doc xml:space="preserve">Inserts @data into @queue using @func to determine the new
|
|
position.
|
|
|
|
The sort function @func is passed two elements of the @queue.
|
|
It should return 0 if they are equal, a negative value if the
|
|
first element should be higher in the @queue or a positive value
|
|
if the first element should be lower in the @queue than the second
|
|
element.
|
|
|
|
This function requires that the @queue is sorted before pushing on
|
|
new elements, see g_async_queue_sort().
|
|
|
|
This function must be called while holding the @queue's lock.
|
|
|
|
For an example of @func see g_async_queue_sort().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the @data to push into the @queue</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the #GCompareDataFunc is used to sort @queue</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @func.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="push_unlocked" c:identifier="g_async_queue_push_unlocked">
|
|
<doc xml:space="preserve">Pushes the @data into the @queue. @data must not be %NULL.
|
|
|
|
This function must be called while holding the @queue's lock.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">@data to push into the @queue</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_async_queue_ref" introspectable="0">
|
|
<doc xml:space="preserve">Increases the reference count of the asynchronous @queue by 1.
|
|
You do not need to hold the lock to call this function.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the @queue that was passed in (since 2.6)</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref_unlocked" c:identifier="g_async_queue_ref_unlocked" deprecated="1" deprecated-version="2.8">
|
|
<doc xml:space="preserve">Increases the reference count of the asynchronous @queue by 1.</doc>
|
|
<doc-deprecated xml:space="preserve">Reference counting is done atomically.
|
|
so g_async_queue_ref() can be used regardless of the @queue's
|
|
lock.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="remove" c:identifier="g_async_queue_remove" version="2.46">
|
|
<doc xml:space="preserve">Remove an item from the queue.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the item was removed</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="item" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to remove from the @queue</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="remove_unlocked" c:identifier="g_async_queue_remove_unlocked" version="2.46">
|
|
<doc xml:space="preserve">Remove an item from the queue.
|
|
|
|
This function must be called while holding the @queue's lock.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the item was removed</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="item" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to remove from the @queue</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="sort" c:identifier="g_async_queue_sort" version="2.10" introspectable="0">
|
|
<doc xml:space="preserve">Sorts @queue using @func.
|
|
|
|
The sort function @func is passed two elements of the @queue.
|
|
It should return 0 if they are equal, a negative value if the
|
|
first element should be higher in the @queue or a positive value
|
|
if the first element should be lower in the @queue than the second
|
|
element.
|
|
|
|
This function will lock @queue before it sorts the queue and unlock
|
|
it when it is finished.
|
|
|
|
If you were sorting a list of priority numbers to make sure the
|
|
lowest priority would be at the top of the queue, you could use:
|
|
|[<!-- language="C" -->
|
|
gint32 id1;
|
|
gint32 id2;
|
|
|
|
id1 = GPOINTER_TO_INT (element1);
|
|
id2 = GPOINTER_TO_INT (element2);
|
|
|
|
return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1);
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="1">
|
|
<doc xml:space="preserve">the #GCompareDataFunc is used to sort @queue</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="sort_unlocked" c:identifier="g_async_queue_sort_unlocked" version="2.10" introspectable="0">
|
|
<doc xml:space="preserve">Sorts @queue using @func.
|
|
|
|
The sort function @func is passed two elements of the @queue.
|
|
It should return 0 if they are equal, a negative value if the
|
|
first element should be higher in the @queue or a positive value
|
|
if the first element should be lower in the @queue than the second
|
|
element.
|
|
|
|
This function must be called while holding the @queue's lock.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="1">
|
|
<doc xml:space="preserve">the #GCompareDataFunc is used to sort @queue</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="timed_pop" c:identifier="g_async_queue_timed_pop" deprecated="1">
|
|
<doc xml:space="preserve">Pops data from the @queue. If the queue is empty, blocks until
|
|
@end_time or until data becomes available.
|
|
|
|
If no data is received before @end_time, %NULL is returned.
|
|
|
|
To easily calculate @end_time, a combination of g_get_real_time()
|
|
and g_time_val_add() can be used.</doc>
|
|
<doc-deprecated xml:space="preserve">use g_async_queue_timeout_pop().</doc-deprecated>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">data from the queue or %NULL, when no data is
|
|
received before @end_time.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="end_time" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeVal, determining the final time</doc>
|
|
<type name="TimeVal" c:type="GTimeVal*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="timed_pop_unlocked" c:identifier="g_async_queue_timed_pop_unlocked" deprecated="1">
|
|
<doc xml:space="preserve">Pops data from the @queue. If the queue is empty, blocks until
|
|
@end_time or until data becomes available.
|
|
|
|
If no data is received before @end_time, %NULL is returned.
|
|
|
|
To easily calculate @end_time, a combination of g_get_real_time()
|
|
and g_time_val_add() can be used.
|
|
|
|
This function must be called while holding the @queue's lock.</doc>
|
|
<doc-deprecated xml:space="preserve">use g_async_queue_timeout_pop_unlocked().</doc-deprecated>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">data from the queue or %NULL, when no data is
|
|
received before @end_time.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="end_time" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeVal, determining the final time</doc>
|
|
<type name="TimeVal" c:type="GTimeVal*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="timeout_pop" c:identifier="g_async_queue_timeout_pop">
|
|
<doc xml:space="preserve">Pops data from the @queue. If the queue is empty, blocks for
|
|
@timeout microseconds, or until data becomes available.
|
|
|
|
If no data is received before the timeout, %NULL is returned.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">data from the queue or %NULL, when no data is
|
|
received before the timeout.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="timeout" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of microseconds to wait</doc>
|
|
<type name="guint64" c:type="guint64"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="timeout_pop_unlocked" c:identifier="g_async_queue_timeout_pop_unlocked">
|
|
<doc xml:space="preserve">Pops data from the @queue. If the queue is empty, blocks for
|
|
@timeout microseconds, or until data becomes available.
|
|
|
|
If no data is received before the timeout, %NULL is returned.
|
|
|
|
This function must be called while holding the @queue's lock.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">data from the queue or %NULL, when no data is
|
|
received before the timeout.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="timeout" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of microseconds to wait</doc>
|
|
<type name="guint64" c:type="guint64"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="try_pop" c:identifier="g_async_queue_try_pop">
|
|
<doc xml:space="preserve">Tries to pop data from the @queue. If no data is available,
|
|
%NULL is returned.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">data from the queue or %NULL, when no data is
|
|
available immediately.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="try_pop_unlocked" c:identifier="g_async_queue_try_pop_unlocked">
|
|
<doc xml:space="preserve">Tries to pop data from the @queue. If no data is available,
|
|
%NULL is returned.
|
|
|
|
This function must be called while holding the @queue's lock.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">data from the queue or %NULL, when no data is
|
|
available immediately.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unlock" c:identifier="g_async_queue_unlock">
|
|
<doc xml:space="preserve">Releases the queue's lock.
|
|
|
|
Calling this function when you have not acquired
|
|
the with g_async_queue_lock() leads to undefined
|
|
behaviour.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_async_queue_unref">
|
|
<doc xml:space="preserve">Decreases the reference count of the asynchronous @queue by 1.
|
|
|
|
If the reference count went to 0, the @queue will be destroyed
|
|
and the memory allocated will be freed. So you are not allowed
|
|
to use the @queue afterwards, as it might have disappeared.
|
|
You do not need to hold the lock to call this function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue.</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref_and_unlock" c:identifier="g_async_queue_unref_and_unlock" deprecated="1" deprecated-version="2.8">
|
|
<doc xml:space="preserve">Decreases the reference count of the asynchronous @queue by 1
|
|
and releases the lock. This function must be called while holding
|
|
the @queue's lock. If the reference count went to 0, the @queue
|
|
will be destroyed and the memory allocated will be freed.</doc>
|
|
<doc-deprecated xml:space="preserve">Reference counting is done atomically.
|
|
so g_async_queue_unref() can be used regardless of the @queue's
|
|
lock.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GAsyncQueue</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="new" c:identifier="g_async_queue_new" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new asynchronous queue.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a new #GAsyncQueue. Free with g_async_queue_unref()</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="new_full" c:identifier="g_async_queue_new_full" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new asynchronous queue and sets up a destroy notify
|
|
function that is used to free any remaining queue items when
|
|
the queue is destroyed after the final unref.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a new #GAsyncQueue. Free with g_async_queue_unref()</doc>
|
|
<type name="AsyncQueue" c:type="GAsyncQueue*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="item_free_func" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">function to free queue elements</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<constant name="BIG_ENDIAN" value="4321" c:type="G_BIG_ENDIAN">
|
|
<doc xml:space="preserve">Specifies one of the possible types of byte order.
|
|
See #G_BYTE_ORDER.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<record name="BookmarkFile" c:type="GBookmarkFile" disguised="1">
|
|
<doc xml:space="preserve">The `GBookmarkFile` structure contains only
|
|
private data and should not be directly accessed.</doc>
|
|
<method name="add_application" c:identifier="g_bookmark_file_add_application" version="2.12">
|
|
<doc xml:space="preserve">Adds the application with @name and @exec to the list of
|
|
applications that have registered a bookmark for @uri into
|
|
@bookmark.
|
|
|
|
Every bookmark inside a #GBookmarkFile must have at least an
|
|
application registered. Each application must provide a name, a
|
|
command line useful for launching the bookmark, the number of times
|
|
the bookmark has been registered by the application and the last
|
|
time the application registered this bookmark.
|
|
|
|
If @name is %NULL, the name of the application will be the
|
|
same returned by g_get_application_name(); if @exec is %NULL, the
|
|
command line will be a composition of the program name as
|
|
returned by g_get_prgname() and the "\%u" modifier, which will be
|
|
expanded to the bookmark's URI.
|
|
|
|
This function will automatically take care of updating the
|
|
registrations count and timestamping in case an application
|
|
with the same @name had already registered a bookmark for
|
|
@uri inside @bookmark.
|
|
|
|
If no bookmark for @uri is found, one is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="name" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the name of the application registering the bookmark
|
|
or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="exec" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">command line to be used to launch the bookmark or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_group" c:identifier="g_bookmark_file_add_group" version="2.12">
|
|
<doc xml:space="preserve">Adds @group to the list of groups to which the bookmark for @uri
|
|
belongs to.
|
|
|
|
If no bookmark for @uri is found then it is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="group" transfer-ownership="none">
|
|
<doc xml:space="preserve">the group name to be added</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free" c:identifier="g_bookmark_file_free" version="2.12">
|
|
<doc xml:space="preserve">Frees a #GBookmarkFile.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_added" c:identifier="g_bookmark_file_get_added" version="2.12" deprecated="1" deprecated-version="2.66" throws="1">
|
|
<doc xml:space="preserve">Gets the time the bookmark for @uri was added to @bookmark
|
|
|
|
In the event the URI cannot be found, -1 is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_bookmark_file_get_added_date_time() instead, as
|
|
`time_t` is deprecated due to the year 2038 problem.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a timestamp</doc>
|
|
<type name="glong" c:type="time_t"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_added_date_time" c:identifier="g_bookmark_file_get_added_date_time" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Gets the time the bookmark for @uri was added to @bookmark
|
|
|
|
In the event the URI cannot be found, %NULL is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_app_info" c:identifier="g_bookmark_file_get_app_info" version="2.12" deprecated="1" deprecated-version="2.66" throws="1">
|
|
<doc xml:space="preserve">Gets the registration information of @app_name for the bookmark for
|
|
@uri. See g_bookmark_file_set_application_info() for more information about
|
|
the returned data.
|
|
|
|
The string returned in @app_exec must be freed.
|
|
|
|
In the event the URI cannot be found, %FALSE is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
|
|
event that no application with name @app_name has registered a bookmark
|
|
for @uri, %FALSE is returned and error is set to
|
|
#G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting
|
|
the command line fails, an error of the #G_SHELL_ERROR domain is
|
|
set and %FALSE is returned.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_bookmark_file_get_application_info() instead, as
|
|
`time_t` is deprecated due to the year 2038 problem.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on success.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="name" transfer-ownership="none">
|
|
<doc xml:space="preserve">an application's name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="exec" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the command line of the application, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="count" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the registration count, or %NULL</doc>
|
|
<type name="guint" c:type="guint*"/>
|
|
</parameter>
|
|
<parameter name="stamp" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the last registration time, or %NULL</doc>
|
|
<type name="glong" c:type="time_t*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_application_info" c:identifier="g_bookmark_file_get_application_info" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Gets the registration information of @app_name for the bookmark for
|
|
@uri. See g_bookmark_file_set_application_info() for more information about
|
|
the returned data.
|
|
|
|
The string returned in @app_exec must be freed.
|
|
|
|
In the event the URI cannot be found, %FALSE is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
|
|
event that no application with name @app_name has registered a bookmark
|
|
for @uri, %FALSE is returned and error is set to
|
|
#G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting
|
|
the command line fails, an error of the #G_SHELL_ERROR domain is
|
|
set and %FALSE is returned.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on success.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="name" transfer-ownership="none">
|
|
<doc xml:space="preserve">an application's name</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="exec" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the command line of the application, or %NULL</doc>
|
|
<type name="utf8" c:type="char**"/>
|
|
</parameter>
|
|
<parameter name="count" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the registration count, or %NULL</doc>
|
|
<type name="guint" c:type="unsigned int*"/>
|
|
</parameter>
|
|
<parameter name="stamp" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the last registration time, or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_applications" c:identifier="g_bookmark_file_get_applications" version="2.12" throws="1">
|
|
<doc xml:space="preserve">Retrieves the names of the applications that have registered the
|
|
bookmark for @uri.
|
|
|
|
In the event the URI cannot be found, %NULL is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated %NULL-terminated array of strings.
|
|
Use g_strfreev() to free it.</doc>
|
|
<array length="1" zero-terminated="0" c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location of the length of the returned list, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_description" c:identifier="g_bookmark_file_get_description" version="2.12" throws="1">
|
|
<doc xml:space="preserve">Retrieves the description of the bookmark for @uri.
|
|
|
|
In the event the URI cannot be found, %NULL is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string or %NULL if the specified
|
|
URI cannot be found.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_groups" c:identifier="g_bookmark_file_get_groups" version="2.12" throws="1">
|
|
<doc xml:space="preserve">Retrieves the list of group names of the bookmark for @uri.
|
|
|
|
In the event the URI cannot be found, %NULL is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
|
|
|
|
The returned array is %NULL terminated, so @length may optionally
|
|
be %NULL.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated %NULL-terminated array of group names.
|
|
Use g_strfreev() to free it.</doc>
|
|
<array length="1" zero-terminated="0" c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the length of the returned string, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_icon" c:identifier="g_bookmark_file_get_icon" version="2.12" throws="1">
|
|
<doc xml:space="preserve">Gets the icon of the bookmark for @uri.
|
|
|
|
In the event the URI cannot be found, %FALSE is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the icon for the bookmark for the URI was found.
|
|
You should free the returned strings.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="href" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the icon's location or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="mime_type" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the icon's MIME type or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_is_private" c:identifier="g_bookmark_file_get_is_private" version="2.12" throws="1">
|
|
<doc xml:space="preserve">Gets whether the private flag of the bookmark for @uri is set.
|
|
|
|
In the event the URI cannot be found, %FALSE is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
|
|
event that the private flag cannot be found, %FALSE is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the private flag is set, %FALSE otherwise.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_mime_type" c:identifier="g_bookmark_file_get_mime_type" version="2.12" throws="1">
|
|
<doc xml:space="preserve">Retrieves the MIME type of the resource pointed by @uri.
|
|
|
|
In the event the URI cannot be found, %NULL is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the
|
|
event that the MIME type cannot be found, %NULL is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string or %NULL if the specified
|
|
URI cannot be found.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_modified" c:identifier="g_bookmark_file_get_modified" version="2.12" deprecated="1" deprecated-version="2.66" throws="1">
|
|
<doc xml:space="preserve">Gets the time when the bookmark for @uri was last modified.
|
|
|
|
In the event the URI cannot be found, -1 is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_bookmark_file_get_modified_date_time() instead, as
|
|
`time_t` is deprecated due to the year 2038 problem.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a timestamp</doc>
|
|
<type name="glong" c:type="time_t"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_modified_date_time" c:identifier="g_bookmark_file_get_modified_date_time" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Gets the time when the bookmark for @uri was last modified.
|
|
|
|
In the event the URI cannot be found, %NULL is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_size" c:identifier="g_bookmark_file_get_size" version="2.12">
|
|
<doc xml:space="preserve">Gets the number of bookmarks inside @bookmark.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bookmarks</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_title" c:identifier="g_bookmark_file_get_title" version="2.12" throws="1">
|
|
<doc xml:space="preserve">Returns the title of the bookmark for @uri.
|
|
|
|
If @uri is %NULL, the title of @bookmark is returned.
|
|
|
|
In the event the URI cannot be found, %NULL is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string or %NULL if the specified
|
|
URI cannot be found.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a valid URI or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_uris" c:identifier="g_bookmark_file_get_uris" version="2.12">
|
|
<doc xml:space="preserve">Returns all URIs of the bookmarks in the bookmark file @bookmark.
|
|
The array of returned URIs will be %NULL-terminated, so @length may
|
|
optionally be %NULL.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated %NULL-terminated array of strings.
|
|
Use g_strfreev() to free it.</doc>
|
|
<array length="0" zero-terminated="0" c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the number of returned URIs, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_visited" c:identifier="g_bookmark_file_get_visited" version="2.12" deprecated="1" deprecated-version="2.66" throws="1">
|
|
<doc xml:space="preserve">Gets the time the bookmark for @uri was last visited.
|
|
|
|
In the event the URI cannot be found, -1 is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_bookmark_file_get_visited_date_time() instead, as
|
|
`time_t` is deprecated due to the year 2038 problem.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a timestamp.</doc>
|
|
<type name="glong" c:type="time_t"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_visited_date_time" c:identifier="g_bookmark_file_get_visited_date_time" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Gets the time the bookmark for @uri was last visited.
|
|
|
|
In the event the URI cannot be found, %NULL is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="has_application" c:identifier="g_bookmark_file_has_application" version="2.12" throws="1">
|
|
<doc xml:space="preserve">Checks whether the bookmark for @uri inside @bookmark has been
|
|
registered by application @name.
|
|
|
|
In the event the URI cannot be found, %FALSE is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the application @name was found</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="name" transfer-ownership="none">
|
|
<doc xml:space="preserve">the name of the application</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="has_group" c:identifier="g_bookmark_file_has_group" version="2.12" throws="1">
|
|
<doc xml:space="preserve">Checks whether @group appears in the list of groups to which
|
|
the bookmark for @uri belongs to.
|
|
|
|
In the event the URI cannot be found, %FALSE is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @group was found.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="group" transfer-ownership="none">
|
|
<doc xml:space="preserve">the group name to be searched</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="has_item" c:identifier="g_bookmark_file_has_item" version="2.12">
|
|
<doc xml:space="preserve">Looks whether the desktop bookmark has an item with its URI set to @uri.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @uri is inside @bookmark, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="load_from_data" c:identifier="g_bookmark_file_load_from_data" version="2.12" throws="1">
|
|
<doc xml:space="preserve">Loads a bookmark file from memory into an empty #GBookmarkFile
|
|
structure. If the object cannot be created then @error is set to a
|
|
#GBookmarkFileError.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a desktop bookmark could be loaded.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">an empty #GBookmarkFile struct</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none">
|
|
<doc xml:space="preserve">desktop bookmarks
|
|
loaded in memory</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @data in bytes</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="load_from_data_dirs" c:identifier="g_bookmark_file_load_from_data_dirs" version="2.12" throws="1">
|
|
<doc xml:space="preserve">This function looks for a desktop bookmark file named @file in the
|
|
paths returned from g_get_user_data_dir() and g_get_system_data_dirs(),
|
|
loads the file into @bookmark and returns the file's full path in
|
|
@full_path. If the file could not be loaded then @error is
|
|
set to either a #GFileError or #GBookmarkFileError.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a key file could be loaded, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a relative path to a filename to open and parse</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="full_path" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for a string
|
|
containing the full path of the file, or %NULL</doc>
|
|
<type name="filename" c:type="gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="load_from_file" c:identifier="g_bookmark_file_load_from_file" version="2.12" throws="1">
|
|
<doc xml:space="preserve">Loads a desktop bookmark file into an empty #GBookmarkFile structure.
|
|
If the file could not be loaded then @error is set to either a #GFileError
|
|
or #GBookmarkFileError.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a desktop bookmark file could be loaded</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">an empty #GBookmarkFile struct</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="filename" transfer-ownership="none">
|
|
<doc xml:space="preserve">the path of a filename to load, in the
|
|
GLib file name encoding</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="move_item" c:identifier="g_bookmark_file_move_item" version="2.12" throws="1">
|
|
<doc xml:space="preserve">Changes the URI of a bookmark item from @old_uri to @new_uri. Any
|
|
existing bookmark for @new_uri will be overwritten. If @new_uri is
|
|
%NULL, then the bookmark is removed.
|
|
|
|
In the event the URI cannot be found, %FALSE is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the URI was successfully changed</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="old_uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="new_uri" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a valid URI, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="remove_application" c:identifier="g_bookmark_file_remove_application" version="2.12" throws="1">
|
|
<doc xml:space="preserve">Removes application registered with @name from the list of applications
|
|
that have registered a bookmark for @uri inside @bookmark.
|
|
|
|
In the event the URI cannot be found, %FALSE is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
|
|
In the event that no application with name @app_name has registered
|
|
a bookmark for @uri, %FALSE is returned and error is set to
|
|
#G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the application was successfully removed.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="name" transfer-ownership="none">
|
|
<doc xml:space="preserve">the name of the application</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="remove_group" c:identifier="g_bookmark_file_remove_group" version="2.12" throws="1">
|
|
<doc xml:space="preserve">Removes @group from the list of groups to which the bookmark
|
|
for @uri belongs to.
|
|
|
|
In the event the URI cannot be found, %FALSE is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
|
|
In the event no group was defined, %FALSE is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @group was successfully removed.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="group" transfer-ownership="none">
|
|
<doc xml:space="preserve">the group name to be removed</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="remove_item" c:identifier="g_bookmark_file_remove_item" version="2.12" throws="1">
|
|
<doc xml:space="preserve">Removes the bookmark for @uri from the bookmark file @bookmark.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the bookmark was removed successfully.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_added" c:identifier="g_bookmark_file_set_added" version="2.12" deprecated="1" deprecated-version="2.66">
|
|
<doc xml:space="preserve">Sets the time the bookmark for @uri was added into @bookmark.
|
|
|
|
If no bookmark for @uri is found then it is created.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_bookmark_file_set_added_date_time() instead, as
|
|
`time_t` is deprecated due to the year 2038 problem.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="added" transfer-ownership="none">
|
|
<doc xml:space="preserve">a timestamp or -1 to use the current time</doc>
|
|
<type name="glong" c:type="time_t"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_added_date_time" c:identifier="g_bookmark_file_set_added_date_time" version="2.66">
|
|
<doc xml:space="preserve">Sets the time the bookmark for @uri was added into @bookmark.
|
|
|
|
If no bookmark for @uri is found then it is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="added" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_app_info" c:identifier="g_bookmark_file_set_app_info" version="2.12" deprecated="1" deprecated-version="2.66" throws="1">
|
|
<doc xml:space="preserve">Sets the meta-data of application @name inside the list of
|
|
applications that have registered a bookmark for @uri inside
|
|
@bookmark.
|
|
|
|
You should rarely use this function; use g_bookmark_file_add_application()
|
|
and g_bookmark_file_remove_application() instead.
|
|
|
|
@name can be any UTF-8 encoded string used to identify an
|
|
application.
|
|
@exec can have one of these two modifiers: "\%f", which will
|
|
be expanded as the local file name retrieved from the bookmark's
|
|
URI; "\%u", which will be expanded as the bookmark's URI.
|
|
The expansion is done automatically when retrieving the stored
|
|
command line using the g_bookmark_file_get_application_info() function.
|
|
@count is the number of times the application has registered the
|
|
bookmark; if is < 0, the current registration count will be increased
|
|
by one, if is 0, the application with @name will be removed from
|
|
the list of registered applications.
|
|
@stamp is the Unix time of the last registration; if it is -1, the
|
|
current time will be used.
|
|
|
|
If you try to remove an application by setting its registration count to
|
|
zero, and no bookmark for @uri is found, %FALSE is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; similarly,
|
|
in the event that no application @name has registered a bookmark
|
|
for @uri, %FALSE is returned and error is set to
|
|
#G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark
|
|
for @uri is found, one is created.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_bookmark_file_set_application_info() instead, as
|
|
`time_t` is deprecated due to the year 2038 problem.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the application's meta-data was successfully
|
|
changed.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="name" transfer-ownership="none">
|
|
<doc xml:space="preserve">an application's name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="exec" transfer-ownership="none">
|
|
<doc xml:space="preserve">an application's command line</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="count" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of registrations done for this application</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="stamp" transfer-ownership="none">
|
|
<doc xml:space="preserve">the time of the last registration for this application</doc>
|
|
<type name="glong" c:type="time_t"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_application_info" c:identifier="g_bookmark_file_set_application_info" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Sets the meta-data of application @name inside the list of
|
|
applications that have registered a bookmark for @uri inside
|
|
@bookmark.
|
|
|
|
You should rarely use this function; use g_bookmark_file_add_application()
|
|
and g_bookmark_file_remove_application() instead.
|
|
|
|
@name can be any UTF-8 encoded string used to identify an
|
|
application.
|
|
@exec can have one of these two modifiers: "\%f", which will
|
|
be expanded as the local file name retrieved from the bookmark's
|
|
URI; "\%u", which will be expanded as the bookmark's URI.
|
|
The expansion is done automatically when retrieving the stored
|
|
command line using the g_bookmark_file_get_application_info() function.
|
|
@count is the number of times the application has registered the
|
|
bookmark; if is < 0, the current registration count will be increased
|
|
by one, if is 0, the application with @name will be removed from
|
|
the list of registered applications.
|
|
@stamp is the Unix time of the last registration.
|
|
|
|
If you try to remove an application by setting its registration count to
|
|
zero, and no bookmark for @uri is found, %FALSE is returned and
|
|
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; similarly,
|
|
in the event that no application @name has registered a bookmark
|
|
for @uri, %FALSE is returned and error is set to
|
|
#G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark
|
|
for @uri is found, one is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the application's meta-data was successfully
|
|
changed.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="name" transfer-ownership="none">
|
|
<doc xml:space="preserve">an application's name</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="exec" transfer-ownership="none">
|
|
<doc xml:space="preserve">an application's command line</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="count" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of registrations done for this application</doc>
|
|
<type name="gint" c:type="int"/>
|
|
</parameter>
|
|
<parameter name="stamp" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the time of the last registration for this application,
|
|
which may be %NULL if @count is 0</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_description" c:identifier="g_bookmark_file_set_description" version="2.12">
|
|
<doc xml:space="preserve">Sets @description as the description of the bookmark for @uri.
|
|
|
|
If @uri is %NULL, the description of @bookmark is set.
|
|
|
|
If a bookmark for @uri cannot be found then it is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a valid URI or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="description" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_groups" c:identifier="g_bookmark_file_set_groups" version="2.12">
|
|
<doc xml:space="preserve">Sets a list of group names for the item with URI @uri. Each previously
|
|
set group name list is removed.
|
|
|
|
If @uri cannot be found then an item for it is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">an item's URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="groups" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">an array of
|
|
group names, or %NULL to remove all groups</doc>
|
|
<array length="2" zero-terminated="0" c:type="const gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of group name values in @groups</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_icon" c:identifier="g_bookmark_file_set_icon" version="2.12">
|
|
<doc xml:space="preserve">Sets the icon for the bookmark for @uri. If @href is %NULL, unsets
|
|
the currently set icon. @href can either be a full URL for the icon
|
|
file or the icon name following the Icon Naming specification.
|
|
|
|
If no bookmark for @uri is found one is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="href" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the URI of the icon for the bookmark, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="mime_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">the MIME type of the icon for the bookmark</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_is_private" c:identifier="g_bookmark_file_set_is_private" version="2.12">
|
|
<doc xml:space="preserve">Sets the private flag of the bookmark for @uri.
|
|
|
|
If a bookmark for @uri cannot be found then it is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="is_private" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the bookmark should be marked as private</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_mime_type" c:identifier="g_bookmark_file_set_mime_type" version="2.12">
|
|
<doc xml:space="preserve">Sets @mime_type as the MIME type of the bookmark for @uri.
|
|
|
|
If a bookmark for @uri cannot be found then it is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="mime_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a MIME type</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_modified" c:identifier="g_bookmark_file_set_modified" version="2.12" deprecated="1" deprecated-version="2.66">
|
|
<doc xml:space="preserve">Sets the last time the bookmark for @uri was last modified.
|
|
|
|
If no bookmark for @uri is found then it is created.
|
|
|
|
The "modified" time should only be set when the bookmark's meta-data
|
|
was actually changed. Every function of #GBookmarkFile that
|
|
modifies a bookmark also changes the modification time, except for
|
|
g_bookmark_file_set_visited_date_time().</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_bookmark_file_set_modified_date_time() instead, as
|
|
`time_t` is deprecated due to the year 2038 problem.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="modified" transfer-ownership="none">
|
|
<doc xml:space="preserve">a timestamp or -1 to use the current time</doc>
|
|
<type name="glong" c:type="time_t"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_modified_date_time" c:identifier="g_bookmark_file_set_modified_date_time" version="2.66">
|
|
<doc xml:space="preserve">Sets the last time the bookmark for @uri was last modified.
|
|
|
|
If no bookmark for @uri is found then it is created.
|
|
|
|
The "modified" time should only be set when the bookmark's meta-data
|
|
was actually changed. Every function of #GBookmarkFile that
|
|
modifies a bookmark also changes the modification time, except for
|
|
g_bookmark_file_set_visited_date_time().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="modified" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_title" c:identifier="g_bookmark_file_set_title" version="2.12">
|
|
<doc xml:space="preserve">Sets @title as the title of the bookmark for @uri inside the
|
|
bookmark file @bookmark.
|
|
|
|
If @uri is %NULL, the title of @bookmark is set.
|
|
|
|
If a bookmark for @uri cannot be found then it is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a valid URI or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="title" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_visited" c:identifier="g_bookmark_file_set_visited" version="2.12" deprecated="1" deprecated-version="2.66">
|
|
<doc xml:space="preserve">Sets the time the bookmark for @uri was last visited.
|
|
|
|
If no bookmark for @uri is found then it is created.
|
|
|
|
The "visited" time should only be set if the bookmark was launched,
|
|
either using the command line retrieved by g_bookmark_file_get_application_info()
|
|
or by the default application for the bookmark's MIME type, retrieved
|
|
using g_bookmark_file_get_mime_type(). Changing the "visited" time
|
|
does not affect the "modified" time.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_bookmark_file_set_visited_date_time() instead, as
|
|
`time_t` is deprecated due to the year 2038 problem.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="visited" transfer-ownership="none">
|
|
<doc xml:space="preserve">a timestamp or -1 to use the current time</doc>
|
|
<type name="glong" c:type="time_t"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_visited_date_time" c:identifier="g_bookmark_file_set_visited_date_time" version="2.66">
|
|
<doc xml:space="preserve">Sets the time the bookmark for @uri was last visited.
|
|
|
|
If no bookmark for @uri is found then it is created.
|
|
|
|
The "visited" time should only be set if the bookmark was launched,
|
|
either using the command line retrieved by g_bookmark_file_get_application_info()
|
|
or by the default application for the bookmark's MIME type, retrieved
|
|
using g_bookmark_file_get_mime_type(). Changing the "visited" time
|
|
does not affect the "modified" time.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="visited" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="to_data" c:identifier="g_bookmark_file_to_data" version="2.12" throws="1">
|
|
<doc xml:space="preserve">This function outputs @bookmark as a string.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">
|
|
a newly allocated string holding the contents of the #GBookmarkFile</doc>
|
|
<array length="0" zero-terminated="0" c:type="gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the length of the returned string, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="to_file" c:identifier="g_bookmark_file_to_file" version="2.12" throws="1">
|
|
<doc xml:space="preserve">This function outputs @bookmark into a file. The write process is
|
|
guaranteed to be atomic by using g_file_set_contents() internally.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the file was successfully written.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bookmark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="filename" transfer-ownership="none">
|
|
<doc xml:space="preserve">path of the output file</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="error_quark" c:identifier="g_bookmark_file_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="new" c:identifier="g_bookmark_file_new" version="2.12" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new empty #GBookmarkFile object.
|
|
|
|
Use g_bookmark_file_load_from_file(), g_bookmark_file_load_from_data()
|
|
or g_bookmark_file_load_from_data_dirs() to read an existing bookmark
|
|
file.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">an empty #GBookmarkFile</doc>
|
|
<type name="BookmarkFile" c:type="GBookmarkFile*"/>
|
|
</return-value>
|
|
</function>
|
|
</record>
|
|
<enumeration name="BookmarkFileError" c:type="GBookmarkFileError" glib:error-domain="g-bookmark-file-error-quark">
|
|
<doc xml:space="preserve">Error codes returned by bookmark file parsing.</doc>
|
|
<member name="invalid_uri" value="0" c:identifier="G_BOOKMARK_FILE_ERROR_INVALID_URI">
|
|
<doc xml:space="preserve">URI was ill-formed</doc>
|
|
</member>
|
|
<member name="invalid_value" value="1" c:identifier="G_BOOKMARK_FILE_ERROR_INVALID_VALUE">
|
|
<doc xml:space="preserve">a requested field was not found</doc>
|
|
</member>
|
|
<member name="app_not_registered" value="2" c:identifier="G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED">
|
|
<doc xml:space="preserve">a requested application did
|
|
not register a bookmark</doc>
|
|
</member>
|
|
<member name="uri_not_found" value="3" c:identifier="G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND">
|
|
<doc xml:space="preserve">a requested URI was not found</doc>
|
|
</member>
|
|
<member name="read" value="4" c:identifier="G_BOOKMARK_FILE_ERROR_READ">
|
|
<doc xml:space="preserve">document was ill formed</doc>
|
|
</member>
|
|
<member name="unknown_encoding" value="5" c:identifier="G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING">
|
|
<doc xml:space="preserve">the text being parsed was
|
|
in an unknown encoding</doc>
|
|
</member>
|
|
<member name="write" value="6" c:identifier="G_BOOKMARK_FILE_ERROR_WRITE">
|
|
<doc xml:space="preserve">an error occurred while writing</doc>
|
|
</member>
|
|
<member name="file_not_found" value="7" c:identifier="G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND">
|
|
<doc xml:space="preserve">requested file was not found</doc>
|
|
</member>
|
|
</enumeration>
|
|
<record name="ByteArray" c:type="GByteArray" glib:type-name="GByteArray" glib:get-type="g_byte_array_get_type" c:symbol-prefix="byte_array">
|
|
<doc xml:space="preserve">Contains the public fields of a GByteArray.</doc>
|
|
<field name="data" writable="1">
|
|
<doc xml:space="preserve">a pointer to the element data. The data may be moved as
|
|
elements are added to the #GByteArray</doc>
|
|
<type name="guint8" c:type="guint8*"/>
|
|
</field>
|
|
<field name="len" writable="1">
|
|
<doc xml:space="preserve">the number of elements in the #GByteArray</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<function name="append" c:identifier="g_byte_array_append" introspectable="0">
|
|
<doc xml:space="preserve">Adds the given bytes to the end of the #GByteArray.
|
|
The array will grow in size automatically if necessary.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none">
|
|
<doc xml:space="preserve">the byte data to be added</doc>
|
|
<type name="guint8" c:type="const guint8*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes to add</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="free" c:identifier="g_byte_array_free">
|
|
<doc xml:space="preserve">Frees the memory allocated by the #GByteArray. If @free_segment is
|
|
%TRUE it frees the actual byte data. If the reference count of
|
|
@array is greater than one, the #GByteArray wrapper is preserved but
|
|
the size of @array will be set to zero.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the element data if @free_segment is %FALSE, otherwise
|
|
%NULL. The element data should be freed using g_free().</doc>
|
|
<type name="guint8" c:type="guint8*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="free_segment" transfer-ownership="none">
|
|
<doc xml:space="preserve">if %TRUE the actual byte data is freed as well</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="free_to_bytes" c:identifier="g_byte_array_free_to_bytes" version="2.32">
|
|
<doc xml:space="preserve">Transfers the data from the #GByteArray into a new immutable #GBytes.
|
|
|
|
The #GByteArray is freed unless the reference count of @array is greater
|
|
than one, the #GByteArray wrapper is preserved but the size of @array
|
|
will be set to zero.
|
|
|
|
This is identical to using g_bytes_new_take() and g_byte_array_free()
|
|
together.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new immutable #GBytes representing same
|
|
byte data that was in the array</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="full">
|
|
<doc xml:space="preserve">a #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="new" c:identifier="g_byte_array_new">
|
|
<doc xml:space="preserve">Creates a new #GByteArray with a reference count of 1.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the new #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
</function>
|
|
<function name="new_take" c:identifier="g_byte_array_new_take" version="2.32">
|
|
<doc xml:space="preserve">Create byte array containing the data. The data will be owned by the array
|
|
and will be freed with g_free(), i.e. it could be allocated using g_strdup().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="data" transfer-ownership="full">
|
|
<doc xml:space="preserve">byte data for the array</doc>
|
|
<array length="1" zero-terminated="0" c:type="guint8*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @data</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="prepend" c:identifier="g_byte_array_prepend" introspectable="0">
|
|
<doc xml:space="preserve">Adds the given data to the start of the #GByteArray.
|
|
The array will grow in size automatically if necessary.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none">
|
|
<doc xml:space="preserve">the byte data to be added</doc>
|
|
<type name="guint8" c:type="const guint8*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes to add</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ref" c:identifier="g_byte_array_ref" version="2.22" introspectable="0">
|
|
<doc xml:space="preserve">Atomically increments the reference count of @array by one.
|
|
This function is thread-safe and may be called from any thread.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">The passed in #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_index" c:identifier="g_byte_array_remove_index" introspectable="0">
|
|
<doc xml:space="preserve">Removes the byte at the given index from a #GByteArray.
|
|
The following bytes are moved down one place.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="index_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the byte to remove</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_index_fast" c:identifier="g_byte_array_remove_index_fast" introspectable="0">
|
|
<doc xml:space="preserve">Removes the byte at the given index from a #GByteArray. The last
|
|
element in the array is used to fill in the space, so this function
|
|
does not preserve the order of the #GByteArray. But it is faster
|
|
than g_byte_array_remove_index().</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="index_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the byte to remove</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_range" c:identifier="g_byte_array_remove_range" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Removes the given number of bytes starting at the given index from a
|
|
#GByteArray. The following elements are moved to close the gap.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a @GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="index_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the first byte to remove</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes to remove</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="set_size" c:identifier="g_byte_array_set_size" introspectable="0">
|
|
<doc xml:space="preserve">Sets the size of the #GByteArray, expanding it if necessary.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the new size of the #GByteArray</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sized_new" c:identifier="g_byte_array_sized_new" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GByteArray with @reserved_size bytes preallocated.
|
|
This avoids frequent reallocation, if you are going to add many
|
|
bytes to the array. Note however that the size of the array is still
|
|
0.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="reserved_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of bytes preallocated</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sort" c:identifier="g_byte_array_sort" introspectable="0">
|
|
<doc xml:space="preserve">Sorts a byte array, using @compare_func which should be a
|
|
qsort()-style comparison function (returns less than zero for first
|
|
arg is less than second arg, zero for equal, greater than zero if
|
|
first arg is greater than second arg).
|
|
|
|
If two array elements compare equal, their order in the sorted array
|
|
is undefined. If you want equal elements to keep their order (i.e.
|
|
you want a stable sort) you can write a comparison function that,
|
|
if two elements would otherwise compare equal, compares them by
|
|
their addresses.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="compare_func" transfer-ownership="none">
|
|
<doc xml:space="preserve">comparison function</doc>
|
|
<type name="CompareFunc" c:type="GCompareFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sort_with_data" c:identifier="g_byte_array_sort_with_data" introspectable="0">
|
|
<doc xml:space="preserve">Like g_byte_array_sort(), but the comparison function takes an extra
|
|
user data argument.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="compare_func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">comparison function</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @compare_func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="steal" c:identifier="g_byte_array_steal" version="2.64">
|
|
<doc xml:space="preserve">Frees the data in the array and resets the size to zero, while
|
|
the underlying array is preserved for use elsewhere and returned
|
|
to the caller.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the element data, which should be
|
|
freed using g_free().</doc>
|
|
<type name="guint8" c:type="guint8*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GByteArray.</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="len" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">pointer to retrieve the number of
|
|
elements of the original array</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unref" c:identifier="g_byte_array_unref" version="2.22">
|
|
<doc xml:space="preserve">Atomically decrements the reference count of @array by one. If the
|
|
reference count drops to 0, all memory allocated by the array is
|
|
released. This function is thread-safe and may be called from any
|
|
thread.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<record name="Bytes" c:type="GBytes" version="2.32" glib:type-name="GBytes" glib:get-type="g_bytes_get_type" c:symbol-prefix="bytes">
|
|
<doc xml:space="preserve">A simple refcounted data type representing an immutable sequence of zero or
|
|
more bytes from an unspecified origin.
|
|
|
|
The purpose of a #GBytes is to keep the memory region that it holds
|
|
alive for as long as anyone holds a reference to the bytes. When
|
|
the last reference count is dropped, the memory is released. Multiple
|
|
unrelated callers can use byte data in the #GBytes without coordinating
|
|
their activities, resting assured that the byte data will not change or
|
|
move while they hold a reference.
|
|
|
|
A #GBytes can come from many different origins that may have
|
|
different procedures for freeing the memory region. Examples are
|
|
memory from g_malloc(), from memory slices, from a #GMappedFile or
|
|
memory from other allocators.
|
|
|
|
#GBytes work well as keys in #GHashTable. Use g_bytes_equal() and
|
|
g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full().
|
|
#GBytes can also be used as keys in a #GTree by passing the g_bytes_compare()
|
|
function to g_tree_new().
|
|
|
|
The data pointed to by this bytes must not be modified. For a mutable
|
|
array of bytes see #GByteArray. Use g_bytes_unref_to_array() to create a
|
|
mutable array for a #GBytes sequence. To create an immutable #GBytes from
|
|
a mutable #GByteArray, use the g_byte_array_free_to_bytes() function.</doc>
|
|
<constructor name="new" c:identifier="g_bytes_new" version="2.32">
|
|
<doc xml:space="preserve">Creates a new #GBytes from @data.
|
|
|
|
@data is copied. If @size is 0, @data may be %NULL.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GBytes</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">
|
|
the data to be used for the bytes</doc>
|
|
<array length="1" zero-terminated="0" c:type="gconstpointer">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of @data</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_static" c:identifier="g_bytes_new_static" version="2.32" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GBytes from static data.
|
|
|
|
@data must be static (ie: never modified or freed). It may be %NULL if @size
|
|
is 0.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GBytes</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="data" transfer-ownership="full" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">
|
|
the data to be used for the bytes</doc>
|
|
<array length="1" zero-terminated="0" c:type="gconstpointer">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of @data</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_take" c:identifier="g_bytes_new_take" version="2.32">
|
|
<doc xml:space="preserve">Creates a new #GBytes from @data.
|
|
|
|
After this call, @data belongs to the bytes and may no longer be
|
|
modified by the caller. g_free() will be called on @data when the
|
|
bytes is no longer in use. Because of this @data must have been created by
|
|
a call to g_malloc(), g_malloc0() or g_realloc() or by one of the many
|
|
functions that wrap these calls (such as g_new(), g_strdup(), etc).
|
|
|
|
For creating #GBytes with memory from other allocators, see
|
|
g_bytes_new_with_free_func().
|
|
|
|
@data may be %NULL if @size is 0.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GBytes</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="data" transfer-ownership="full" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">
|
|
the data to be used for the bytes</doc>
|
|
<array length="1" zero-terminated="0" c:type="gpointer">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of @data</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_with_free_func" c:identifier="g_bytes_new_with_free_func" version="2.32" introspectable="0">
|
|
<doc xml:space="preserve">Creates a #GBytes from @data.
|
|
|
|
When the last reference is dropped, @free_func will be called with the
|
|
@user_data argument.
|
|
|
|
@data must not be modified after this call is made until @free_func has
|
|
been called to indicate that the bytes is no longer in use.
|
|
|
|
@data may be %NULL if @size is 0.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GBytes</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">
|
|
the data to be used for the bytes</doc>
|
|
<array length="1" zero-terminated="0" c:type="gconstpointer">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of @data</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="free_func" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">the function to call to release the data</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @free_func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<method name="compare" c:identifier="g_bytes_compare" version="2.32">
|
|
<doc xml:space="preserve">Compares the two #GBytes values.
|
|
|
|
This function can be used to sort GBytes instances in lexicographical order.
|
|
|
|
If @bytes1 and @bytes2 have different length but the shorter one is a
|
|
prefix of the longer one then the shorter one is considered to be less than
|
|
the longer one. Otherwise the first byte where both differ is used for
|
|
comparison. If @bytes1 has a smaller value at that position it is
|
|
considered less, otherwise greater than @bytes2.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a negative value if @bytes1 is less than @bytes2, a positive value
|
|
if @bytes1 is greater than @bytes2, and zero if @bytes1 is equal to
|
|
@bytes2</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bytes1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GBytes</doc>
|
|
<type name="Bytes" c:type="gconstpointer"/>
|
|
</instance-parameter>
|
|
<parameter name="bytes2" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GBytes to compare with @bytes1</doc>
|
|
<type name="Bytes" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="equal" c:identifier="g_bytes_equal" version="2.32">
|
|
<doc xml:space="preserve">Compares the two #GBytes values being pointed to and returns
|
|
%TRUE if they are equal.
|
|
|
|
This function can be passed to g_hash_table_new() as the @key_equal_func
|
|
parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the two keys match.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bytes1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GBytes</doc>
|
|
<type name="Bytes" c:type="gconstpointer"/>
|
|
</instance-parameter>
|
|
<parameter name="bytes2" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GBytes to compare with @bytes1</doc>
|
|
<type name="Bytes" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_data" c:identifier="g_bytes_get_data" version="2.32">
|
|
<doc xml:space="preserve">Get the byte data in the #GBytes. This data should not be modified.
|
|
|
|
This function will always return the same pointer for a given #GBytes.
|
|
|
|
%NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes
|
|
may represent an empty string with @data non-%NULL and @size as 0. %NULL will
|
|
not be returned if @size is non-zero.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">
|
|
a pointer to the byte data, or %NULL</doc>
|
|
<array length="0" zero-terminated="0" c:type="gconstpointer">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBytes</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</instance-parameter>
|
|
<parameter name="size" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to return size of byte data</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_size" c:identifier="g_bytes_get_size" version="2.32">
|
|
<doc xml:space="preserve">Get the size of the byte data in the #GBytes.
|
|
|
|
This function will always return the same value for a given #GBytes.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the size</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBytes</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="hash" c:identifier="g_bytes_hash" version="2.32">
|
|
<doc xml:space="preserve">Creates an integer hash code for the byte data in the #GBytes.
|
|
|
|
This function can be passed to g_hash_table_new() as the @key_hash_func
|
|
parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a hash value corresponding to the key.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GBytes key</doc>
|
|
<type name="Bytes" c:type="gconstpointer"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="new_from_bytes" c:identifier="g_bytes_new_from_bytes" version="2.32">
|
|
<doc xml:space="preserve">Creates a #GBytes which is a subsection of another #GBytes. The @offset +
|
|
@length may not be longer than the size of @bytes.
|
|
|
|
A reference to @bytes will be held by the newly created #GBytes until
|
|
the byte data is no longer needed.
|
|
|
|
Since 2.56, if @offset is 0 and @length matches the size of @bytes, then
|
|
@bytes will be returned with the reference count incremented by 1. If @bytes
|
|
is a slice of another #GBytes, then the resulting #GBytes will reference
|
|
the same #GBytes instead of @bytes. This allows consumers to simplify the
|
|
usage of #GBytes when asynchronously writing to streams.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GBytes</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBytes</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</instance-parameter>
|
|
<parameter name="offset" transfer-ownership="none">
|
|
<doc xml:space="preserve">offset which subsection starts at</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of subsection</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_bytes_ref" version="2.32">
|
|
<doc xml:space="preserve">Increase the reference count on @bytes.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the #GBytes</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBytes</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_bytes_unref" version="2.32">
|
|
<doc xml:space="preserve">Releases a reference on @bytes. This may result in the bytes being
|
|
freed. If @bytes is %NULL, it will return immediately.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bytes" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GBytes</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref_to_array" c:identifier="g_bytes_unref_to_array" version="2.32">
|
|
<doc xml:space="preserve">Unreferences the bytes, and returns a new mutable #GByteArray containing
|
|
the same byte data.
|
|
|
|
As an optimization, the byte data is transferred to the array without copying
|
|
if this was the last reference to bytes and bytes was created with
|
|
g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all
|
|
other cases the data is copied.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new mutable #GByteArray containing the same byte data</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bytes" transfer-ownership="full">
|
|
<doc xml:space="preserve">a #GBytes</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref_to_data" c:identifier="g_bytes_unref_to_data" version="2.32">
|
|
<doc xml:space="preserve">Unreferences the bytes, and returns a pointer the same byte data
|
|
contents.
|
|
|
|
As an optimization, the byte data is returned without copying if this was
|
|
the last reference to bytes and bytes was created with g_bytes_new(),
|
|
g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the
|
|
data is copied.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to the same byte data, which should be
|
|
freed with g_free()</doc>
|
|
<array length="0" zero-terminated="0" c:type="gpointer">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="bytes" transfer-ownership="full">
|
|
<doc xml:space="preserve">a #GBytes</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</instance-parameter>
|
|
<parameter name="size" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">location to place the length of the returned data</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<function-macro name="CHECK_VERSION" c:identifier="GLIB_CHECK_VERSION" introspectable="0">
|
|
<doc xml:space="preserve">Checks the version of the GLib library that is being compiled
|
|
against. See glib_check_version() for a runtime check.</doc>
|
|
<parameters>
|
|
<parameter name="major">
|
|
<doc xml:space="preserve">the major version to check for</doc>
|
|
</parameter>
|
|
<parameter name="minor">
|
|
<doc xml:space="preserve">the minor version to check for</doc>
|
|
</parameter>
|
|
<parameter name="micro">
|
|
<doc xml:space="preserve">the micro version to check for</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="CSET_A_2_Z" value="ABCDEFGHIJKLMNOPQRSTUVWXYZ" c:type="G_CSET_A_2_Z">
|
|
<doc xml:space="preserve">The set of uppercase ASCII alphabet characters.
|
|
Used for specifying valid identifier characters
|
|
in #GScannerConfig.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="CSET_DIGITS" value="0123456789" c:type="G_CSET_DIGITS">
|
|
<doc xml:space="preserve">The set of ASCII digits.
|
|
Used for specifying valid identifier characters
|
|
in #GScannerConfig.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="CSET_a_2_z" value="abcdefghijklmnopqrstuvwxyz" c:type="G_CSET_a_2_z">
|
|
<doc xml:space="preserve">The set of lowercase ASCII alphabet characters.
|
|
Used for specifying valid identifier characters
|
|
in #GScannerConfig.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<record name="Checksum" c:type="GChecksum" version="2.16" glib:type-name="GChecksum" glib:get-type="g_checksum_get_type" c:symbol-prefix="checksum">
|
|
<doc xml:space="preserve">An opaque structure representing a checksumming operation.
|
|
To create a new GChecksum, use g_checksum_new(). To free
|
|
a GChecksum, use g_checksum_free().</doc>
|
|
<constructor name="new" c:identifier="g_checksum_new" version="2.16">
|
|
<doc xml:space="preserve">Creates a new #GChecksum, using the checksum algorithm @checksum_type.
|
|
If the @checksum_type is not known, %NULL is returned.
|
|
A #GChecksum can be used to compute the checksum, or digest, of an
|
|
arbitrary binary blob, using different hashing algorithms.
|
|
|
|
A #GChecksum works by feeding a binary blob through g_checksum_update()
|
|
until there is data to be checked; the digest can then be extracted
|
|
using g_checksum_get_string(), which will return the checksum as a
|
|
hexadecimal string; or g_checksum_get_digest(), which will return a
|
|
vector of raw bytes. Once either g_checksum_get_string() or
|
|
g_checksum_get_digest() have been called on a #GChecksum, the checksum
|
|
will be closed and it won't be possible to call g_checksum_update()
|
|
on it anymore.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the newly created #GChecksum, or %NULL.
|
|
Use g_checksum_free() to free the memory allocated by it.</doc>
|
|
<type name="Checksum" c:type="GChecksum*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="checksum_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">the desired type of checksum</doc>
|
|
<type name="ChecksumType" c:type="GChecksumType"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<method name="copy" c:identifier="g_checksum_copy" version="2.16">
|
|
<doc xml:space="preserve">Copies a #GChecksum. If @checksum has been closed, by calling
|
|
g_checksum_get_string() or g_checksum_get_digest(), the copied
|
|
checksum will be closed as well.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the copy of the passed #GChecksum. Use g_checksum_free()
|
|
when finished using it.</doc>
|
|
<type name="Checksum" c:type="GChecksum*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="checksum" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GChecksum to copy</doc>
|
|
<type name="Checksum" c:type="const GChecksum*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free" c:identifier="g_checksum_free" version="2.16">
|
|
<doc xml:space="preserve">Frees the memory allocated for @checksum.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="checksum" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GChecksum</doc>
|
|
<type name="Checksum" c:type="GChecksum*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_digest" c:identifier="g_checksum_get_digest" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Gets the digest from @checksum as a raw binary vector and places it
|
|
into @buffer. The size of the digest depends on the type of checksum.
|
|
|
|
Once this function has been called, the #GChecksum is closed and can
|
|
no longer be updated with g_checksum_update().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="checksum" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GChecksum</doc>
|
|
<type name="Checksum" c:type="GChecksum*"/>
|
|
</instance-parameter>
|
|
<parameter name="buffer" transfer-ownership="none">
|
|
<doc xml:space="preserve">output buffer</doc>
|
|
<array length="1" zero-terminated="0" c:type="guint8*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="digest_len" direction="inout" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">an inout parameter. The caller initializes it to the size of @buffer.
|
|
After the call it contains the length of the digest.</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_string" c:identifier="g_checksum_get_string" version="2.16">
|
|
<doc xml:space="preserve">Gets the digest as a hexadecimal string.
|
|
|
|
Once this function has been called the #GChecksum can no longer be
|
|
updated with g_checksum_update().
|
|
|
|
The hexadecimal characters will be lower case.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the hexadecimal representation of the checksum. The
|
|
returned string is owned by the checksum and should not be modified
|
|
or freed.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="checksum" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GChecksum</doc>
|
|
<type name="Checksum" c:type="GChecksum*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="reset" c:identifier="g_checksum_reset" version="2.18">
|
|
<doc xml:space="preserve">Resets the state of the @checksum back to its initial state.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="checksum" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GChecksum to reset</doc>
|
|
<type name="Checksum" c:type="GChecksum*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="update" c:identifier="g_checksum_update" version="2.16">
|
|
<doc xml:space="preserve">Feeds @data into an existing #GChecksum. The checksum must still be
|
|
open, that is g_checksum_get_string() or g_checksum_get_digest() must
|
|
not have been called on @checksum.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="checksum" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GChecksum</doc>
|
|
<type name="Checksum" c:type="GChecksum*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none">
|
|
<doc xml:space="preserve">buffer used to compute the checksum</doc>
|
|
<array length="1" zero-terminated="0" c:type="const guchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">size of the buffer, or -1 if it is a null-terminated string.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="type_get_length" c:identifier="g_checksum_type_get_length" version="2.16">
|
|
<doc xml:space="preserve">Gets the length in bytes of digests of type @checksum_type</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the checksum length, or -1 if @checksum_type is
|
|
not supported.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="checksum_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GChecksumType</doc>
|
|
<type name="ChecksumType" c:type="GChecksumType"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<enumeration name="ChecksumType" version="2.16" c:type="GChecksumType">
|
|
<doc xml:space="preserve">The hashing algorithm to be used by #GChecksum when performing the
|
|
digest of some data.
|
|
|
|
Note that the #GChecksumType enumeration may be extended at a later
|
|
date to include new hashing algorithm types.</doc>
|
|
<member name="md5" value="0" c:identifier="G_CHECKSUM_MD5">
|
|
<doc xml:space="preserve">Use the MD5 hashing algorithm</doc>
|
|
</member>
|
|
<member name="sha1" value="1" c:identifier="G_CHECKSUM_SHA1">
|
|
<doc xml:space="preserve">Use the SHA-1 hashing algorithm</doc>
|
|
</member>
|
|
<member name="sha256" value="2" c:identifier="G_CHECKSUM_SHA256">
|
|
<doc xml:space="preserve">Use the SHA-256 hashing algorithm</doc>
|
|
</member>
|
|
<member name="sha512" value="3" c:identifier="G_CHECKSUM_SHA512">
|
|
<doc xml:space="preserve">Use the SHA-512 hashing algorithm (Since: 2.36)</doc>
|
|
</member>
|
|
<member name="sha384" value="4" c:identifier="G_CHECKSUM_SHA384">
|
|
<doc xml:space="preserve">Use the SHA-384 hashing algorithm (Since: 2.51)</doc>
|
|
</member>
|
|
</enumeration>
|
|
<callback name="ChildWatchFunc" c:type="GChildWatchFunc">
|
|
<doc xml:space="preserve">Prototype of a #GChildWatchSource callback, called when a child
|
|
process has exited. To interpret @status, see the documentation
|
|
for g_spawn_check_exit_status().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="pid" transfer-ownership="none">
|
|
<doc xml:space="preserve">the process id of the child process</doc>
|
|
<type name="Pid" c:type="GPid"/>
|
|
</parameter>
|
|
<parameter name="status" transfer-ownership="none">
|
|
<doc xml:space="preserve">Status information about the child process, encoded
|
|
in a platform-specific manner</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2">
|
|
<doc xml:space="preserve">user data passed to g_child_watch_add()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<callback name="ClearHandleFunc" c:type="GClearHandleFunc" version="2.56">
|
|
<doc xml:space="preserve">Specifies the type of function passed to g_clear_handle_id().
|
|
The implementation is expected to free the resource identified
|
|
by @handle_id; for instance, if @handle_id is a #GSource ID,
|
|
g_source_remove() can be used.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="handle_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">the handle ID to clear</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<callback name="CompareDataFunc" c:type="GCompareDataFunc">
|
|
<doc xml:space="preserve">Specifies the type of a comparison function used to compare two
|
|
values. The function should return a negative integer if the first
|
|
value comes before the second, 0 if they are equal, or a positive
|
|
integer if the first value comes after the second.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">negative value if @a < @b; zero if @a = @b; positive
|
|
value if @a > @b</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="a" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a value</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="b" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a value to compare with</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2">
|
|
<doc xml:space="preserve">user data</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<callback name="CompareFunc" c:type="GCompareFunc">
|
|
<doc xml:space="preserve">Specifies the type of a comparison function used to compare two
|
|
values. The function should return a negative integer if the first
|
|
value comes before the second, 0 if they are equal, or a positive
|
|
integer if the first value comes after the second.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">negative value if @a < @b; zero if @a = @b; positive
|
|
value if @a > @b</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="a" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a value</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="b" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a value to compare with</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<record name="Cond" c:type="GCond">
|
|
<doc xml:space="preserve">The #GCond struct is an opaque data structure that represents a
|
|
condition. Threads can block on a #GCond if they find a certain
|
|
condition to be false. If other threads change the state of this
|
|
condition they signal the #GCond, and that causes the waiting
|
|
threads to be woken up.
|
|
|
|
Consider the following example of a shared variable. One or more
|
|
threads can wait for data to be published to the variable and when
|
|
another thread publishes the data, it can signal one of the waiting
|
|
threads to wake up to collect the data.
|
|
|
|
Here is an example for using GCond to block a thread until a condition
|
|
is satisfied:
|
|
|[<!-- language="C" -->
|
|
gpointer current_data = NULL;
|
|
GMutex data_mutex;
|
|
GCond data_cond;
|
|
|
|
void
|
|
push_data (gpointer data)
|
|
{
|
|
g_mutex_lock (&data_mutex);
|
|
current_data = data;
|
|
g_cond_signal (&data_cond);
|
|
g_mutex_unlock (&data_mutex);
|
|
}
|
|
|
|
gpointer
|
|
pop_data (void)
|
|
{
|
|
gpointer data;
|
|
|
|
g_mutex_lock (&data_mutex);
|
|
while (!current_data)
|
|
g_cond_wait (&data_cond, &data_mutex);
|
|
data = current_data;
|
|
current_data = NULL;
|
|
g_mutex_unlock (&data_mutex);
|
|
|
|
return data;
|
|
}
|
|
]|
|
|
Whenever a thread calls pop_data() now, it will wait until
|
|
current_data is non-%NULL, i.e. until some other thread
|
|
has called push_data().
|
|
|
|
The example shows that use of a condition variable must always be
|
|
paired with a mutex. Without the use of a mutex, there would be a
|
|
race between the check of @current_data by the while loop in
|
|
pop_data() and waiting. Specifically, another thread could set
|
|
@current_data after the check, and signal the cond (with nobody
|
|
waiting on it) before the first thread goes to sleep. #GCond is
|
|
specifically useful for its ability to release the mutex and go
|
|
to sleep atomically.
|
|
|
|
It is also important to use the g_cond_wait() and g_cond_wait_until()
|
|
functions only inside a loop which checks for the condition to be
|
|
true. See g_cond_wait() for an explanation of why the condition may
|
|
not be true even after it returns.
|
|
|
|
If a #GCond is allocated in static storage then it can be used
|
|
without initialisation. Otherwise, you should call g_cond_init()
|
|
on it and g_cond_clear() when done.
|
|
|
|
A #GCond should only be accessed via the g_cond_ functions.</doc>
|
|
<field name="p" readable="0" private="1">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="i" readable="0" private="1">
|
|
<array zero-terminated="0" fixed-size="2">
|
|
<type name="guint" c:type="guint"/>
|
|
</array>
|
|
</field>
|
|
<method name="broadcast" c:identifier="g_cond_broadcast">
|
|
<doc xml:space="preserve">If threads are waiting for @cond, all of them are unblocked.
|
|
If no threads are waiting for @cond, this function has no effect.
|
|
It is good practice to lock the same mutex as the waiting threads
|
|
while calling this function, though not required.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="cond" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GCond</doc>
|
|
<type name="Cond" c:type="GCond*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="clear" c:identifier="g_cond_clear" version="2.32">
|
|
<doc xml:space="preserve">Frees the resources allocated to a #GCond with g_cond_init().
|
|
|
|
This function should not be used with a #GCond that has been
|
|
statically allocated.
|
|
|
|
Calling g_cond_clear() for a #GCond on which threads are
|
|
blocking leads to undefined behaviour.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="cond" transfer-ownership="none">
|
|
<doc xml:space="preserve">an initialised #GCond</doc>
|
|
<type name="Cond" c:type="GCond*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="init" c:identifier="g_cond_init" version="2.32">
|
|
<doc xml:space="preserve">Initialises a #GCond so that it can be used.
|
|
|
|
This function is useful to initialise a #GCond that has been
|
|
allocated as part of a larger structure. It is not necessary to
|
|
initialise a #GCond that has been statically allocated.
|
|
|
|
To undo the effect of g_cond_init() when a #GCond is no longer
|
|
needed, use g_cond_clear().
|
|
|
|
Calling g_cond_init() on an already-initialised #GCond leads
|
|
to undefined behaviour.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="cond" transfer-ownership="none">
|
|
<doc xml:space="preserve">an uninitialized #GCond</doc>
|
|
<type name="Cond" c:type="GCond*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="signal" c:identifier="g_cond_signal">
|
|
<doc xml:space="preserve">If threads are waiting for @cond, at least one of them is unblocked.
|
|
If no threads are waiting for @cond, this function has no effect.
|
|
It is good practice to hold the same lock as the waiting thread
|
|
while calling this function, though not required.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="cond" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GCond</doc>
|
|
<type name="Cond" c:type="GCond*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="wait" c:identifier="g_cond_wait">
|
|
<doc xml:space="preserve">Atomically releases @mutex and waits until @cond is signalled.
|
|
When this function returns, @mutex is locked again and owned by the
|
|
calling thread.
|
|
|
|
When using condition variables, it is possible that a spurious wakeup
|
|
may occur (ie: g_cond_wait() returns even though g_cond_signal() was
|
|
not called). It's also possible that a stolen wakeup may occur.
|
|
This is when g_cond_signal() is called, but another thread acquires
|
|
@mutex before this thread and modifies the state of the program in
|
|
such a way that when g_cond_wait() is able to return, the expected
|
|
condition is no longer met.
|
|
|
|
For this reason, g_cond_wait() must always be used in a loop. See
|
|
the documentation for #GCond for a complete example.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="cond" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GCond</doc>
|
|
<type name="Cond" c:type="GCond*"/>
|
|
</instance-parameter>
|
|
<parameter name="mutex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMutex that is currently locked</doc>
|
|
<type name="Mutex" c:type="GMutex*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="wait_until" c:identifier="g_cond_wait_until" version="2.32">
|
|
<doc xml:space="preserve">Waits until either @cond is signalled or @end_time has passed.
|
|
|
|
As with g_cond_wait() it is possible that a spurious or stolen wakeup
|
|
could occur. For that reason, waiting on a condition variable should
|
|
always be in a loop, based on an explicitly-checked predicate.
|
|
|
|
%TRUE is returned if the condition variable was signalled (or in the
|
|
case of a spurious wakeup). %FALSE is returned if @end_time has
|
|
passed.
|
|
|
|
The following code shows how to correctly perform a timed wait on a
|
|
condition variable (extending the example presented in the
|
|
documentation for #GCond):
|
|
|
|
|[<!-- language="C" -->
|
|
gpointer
|
|
pop_data_timed (void)
|
|
{
|
|
gint64 end_time;
|
|
gpointer data;
|
|
|
|
g_mutex_lock (&data_mutex);
|
|
|
|
end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND;
|
|
while (!current_data)
|
|
if (!g_cond_wait_until (&data_cond, &data_mutex, end_time))
|
|
{
|
|
// timeout has passed.
|
|
g_mutex_unlock (&data_mutex);
|
|
return NULL;
|
|
}
|
|
|
|
// there is data for us
|
|
data = current_data;
|
|
current_data = NULL;
|
|
|
|
g_mutex_unlock (&data_mutex);
|
|
|
|
return data;
|
|
}
|
|
]|
|
|
|
|
Notice that the end time is calculated once, before entering the
|
|
loop and reused. This is the motivation behind the use of absolute
|
|
time on this API -- if a relative time of 5 seconds were passed
|
|
directly to the call and a spurious wakeup occurred, the program would
|
|
have to start over waiting again (which would lead to a total wait
|
|
time of more than 5 seconds).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on a signal, %FALSE on a timeout</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="cond" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GCond</doc>
|
|
<type name="Cond" c:type="GCond*"/>
|
|
</instance-parameter>
|
|
<parameter name="mutex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMutex that is currently locked</doc>
|
|
<type name="Mutex" c:type="GMutex*"/>
|
|
</parameter>
|
|
<parameter name="end_time" transfer-ownership="none">
|
|
<doc xml:space="preserve">the monotonic time to wait until</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<enumeration name="ConvertError" c:type="GConvertError" glib:error-domain="g_convert_error">
|
|
<doc xml:space="preserve">Error codes returned by character set conversion routines.</doc>
|
|
<member name="no_conversion" value="0" c:identifier="G_CONVERT_ERROR_NO_CONVERSION">
|
|
<doc xml:space="preserve">Conversion between the requested character
|
|
sets is not supported.</doc>
|
|
</member>
|
|
<member name="illegal_sequence" value="1" c:identifier="G_CONVERT_ERROR_ILLEGAL_SEQUENCE">
|
|
<doc xml:space="preserve">Invalid byte sequence in conversion input;
|
|
or the character sequence could not be represented in the target
|
|
character set.</doc>
|
|
</member>
|
|
<member name="failed" value="2" c:identifier="G_CONVERT_ERROR_FAILED">
|
|
<doc xml:space="preserve">Conversion failed for some reason.</doc>
|
|
</member>
|
|
<member name="partial_input" value="3" c:identifier="G_CONVERT_ERROR_PARTIAL_INPUT">
|
|
<doc xml:space="preserve">Partial character sequence at end of input.</doc>
|
|
</member>
|
|
<member name="bad_uri" value="4" c:identifier="G_CONVERT_ERROR_BAD_URI">
|
|
<doc xml:space="preserve">URI is invalid.</doc>
|
|
</member>
|
|
<member name="not_absolute_path" value="5" c:identifier="G_CONVERT_ERROR_NOT_ABSOLUTE_PATH">
|
|
<doc xml:space="preserve">Pathname is not an absolute path.</doc>
|
|
</member>
|
|
<member name="no_memory" value="6" c:identifier="G_CONVERT_ERROR_NO_MEMORY">
|
|
<doc xml:space="preserve">No memory available. Since: 2.40</doc>
|
|
</member>
|
|
<member name="embedded_nul" value="7" c:identifier="G_CONVERT_ERROR_EMBEDDED_NUL">
|
|
<doc xml:space="preserve">An embedded NUL character is present in
|
|
conversion output where a NUL-terminated string is expected.
|
|
Since: 2.56</doc>
|
|
</member>
|
|
</enumeration>
|
|
<callback name="CopyFunc" c:type="GCopyFunc" version="2.4">
|
|
<doc xml:space="preserve">A function of this signature is used to copy the node data
|
|
when doing a deep-copy of a tree.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">A pointer to the copy</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="src" transfer-ownership="none">
|
|
<doc xml:space="preserve">A pointer to the data which should be copied</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">Additional data</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<constant name="DATALIST_FLAGS_MASK" value="3" c:type="G_DATALIST_FLAGS_MASK">
|
|
<doc xml:space="preserve">A bitmask that restricts the possible flags passed to
|
|
g_datalist_set_flags(). Passing a flags value where
|
|
flags & ~G_DATALIST_FLAGS_MASK != 0 is an error.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="DATE_BAD_DAY" value="0" c:type="G_DATE_BAD_DAY">
|
|
<doc xml:space="preserve">Represents an invalid #GDateDay.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="DATE_BAD_JULIAN" value="0" c:type="G_DATE_BAD_JULIAN">
|
|
<doc xml:space="preserve">Represents an invalid Julian day number.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="DATE_BAD_YEAR" value="0" c:type="G_DATE_BAD_YEAR">
|
|
<doc xml:space="preserve">Represents an invalid year.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<function-macro name="DEFINE_AUTOPTR_CLEANUP_FUNC" c:identifier="G_DEFINE_AUTOPTR_CLEANUP_FUNC" version="2.44" introspectable="0">
|
|
<doc xml:space="preserve">Defines the appropriate cleanup function for a pointer type.
|
|
|
|
The function will not be called if the variable to be cleaned up
|
|
contains %NULL.
|
|
|
|
This will typically be the `_free()` or `_unref()` function for the given
|
|
type.
|
|
|
|
With this definition, it will be possible to use g_autoptr() with
|
|
@TypeName.
|
|
|
|
|[
|
|
G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref)
|
|
]|
|
|
|
|
This macro should be used unconditionally; it is a no-op on compilers
|
|
where cleanup is not supported.</doc>
|
|
<parameters>
|
|
<parameter name="TypeName">
|
|
<doc xml:space="preserve">a type name to define a g_autoptr() cleanup function for</doc>
|
|
</parameter>
|
|
<parameter name="func">
|
|
<doc xml:space="preserve">the cleanup function</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEFINE_AUTO_CLEANUP_CLEAR_FUNC" c:identifier="G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC" version="2.44" introspectable="0">
|
|
<doc xml:space="preserve">Defines the appropriate cleanup function for a type.
|
|
|
|
This will typically be the `_clear()` function for the given type.
|
|
|
|
With this definition, it will be possible to use g_auto() with
|
|
@TypeName.
|
|
|
|
|[
|
|
G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear)
|
|
]|
|
|
|
|
This macro should be used unconditionally; it is a no-op on compilers
|
|
where cleanup is not supported.</doc>
|
|
<parameters>
|
|
<parameter name="TypeName">
|
|
<doc xml:space="preserve">a type name to define a g_auto() cleanup function for</doc>
|
|
</parameter>
|
|
<parameter name="func">
|
|
<doc xml:space="preserve">the clear function</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEFINE_AUTO_CLEANUP_FREE_FUNC" c:identifier="G_DEFINE_AUTO_CLEANUP_FREE_FUNC" version="2.44" introspectable="0">
|
|
<doc xml:space="preserve">Defines the appropriate cleanup function for a type.
|
|
|
|
With this definition, it will be possible to use g_auto() with
|
|
@TypeName.
|
|
|
|
This function will be rarely used. It is used with pointer-based
|
|
typedefs and non-pointer types where the value of the variable
|
|
represents a resource that must be freed. Two examples are #GStrv
|
|
and file descriptors.
|
|
|
|
@none specifies the "none" value for the type in question. It is
|
|
probably something like %NULL or `-1`. If the variable is found to
|
|
contain this value then the free function will not be called.
|
|
|
|
|[
|
|
G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL)
|
|
]|
|
|
|
|
This macro should be used unconditionally; it is a no-op on compilers
|
|
where cleanup is not supported.</doc>
|
|
<parameters>
|
|
<parameter name="TypeName">
|
|
<doc xml:space="preserve">a type name to define a g_auto() cleanup function for</doc>
|
|
</parameter>
|
|
<parameter name="func">
|
|
<doc xml:space="preserve">the free function</doc>
|
|
</parameter>
|
|
<parameter name="none">
|
|
<doc xml:space="preserve">the "none" value for the type</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEFINE_QUARK" c:identifier="G_DEFINE_QUARK" version="2.34" introspectable="0">
|
|
<doc xml:space="preserve">A convenience macro which defines a function returning the
|
|
#GQuark for the name @QN. The function will be named
|
|
@q_n_quark().
|
|
|
|
Note that the quark name will be stringified automatically
|
|
in the macro, so you shouldn't use double quotes.</doc>
|
|
<parameters>
|
|
<parameter name="QN">
|
|
<doc xml:space="preserve">the name to return a #GQuark for</doc>
|
|
</parameter>
|
|
<parameter name="q_n">
|
|
<doc xml:space="preserve">prefix for the function name</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_26_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_26_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_28_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_28_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_30_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_30_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_32_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_32_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_34_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_34_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_36_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_36_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_38_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_38_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_40_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_40_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_42_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_42_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_44_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_44_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_46_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_46_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_48_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_48_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_50_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_50_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_52_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_52_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_54_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_54_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_56_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_56_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_58_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_58_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_60_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_60_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_62_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_62_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_64_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_64_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_ENUMERATOR_IN_2_66_FOR" c:identifier="GLIB_DEPRECATED_ENUMERATOR_IN_2_66_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_FOR" c:identifier="G_DEPRECATED_FOR" version="2.32" introspectable="0">
|
|
<doc xml:space="preserve">This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark
|
|
functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it
|
|
is meant to be portable across different compilers and must be placed
|
|
before the function declaration.
|
|
|
|
|[<!-- language="C" --
|
|
G_DEPRECATED_FOR(my_replacement)
|
|
int my_mistake (void);
|
|
]|</doc>
|
|
<parameters>
|
|
<parameter name="f">
|
|
<doc xml:space="preserve">the name of the function that this function was deprecated for</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_26_FOR" c:identifier="GLIB_DEPRECATED_IN_2_26_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_28_FOR" c:identifier="GLIB_DEPRECATED_IN_2_28_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_30_FOR" c:identifier="GLIB_DEPRECATED_IN_2_30_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_32_FOR" c:identifier="GLIB_DEPRECATED_IN_2_32_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_34_FOR" c:identifier="GLIB_DEPRECATED_IN_2_34_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_36_FOR" c:identifier="GLIB_DEPRECATED_IN_2_36_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_38_FOR" c:identifier="GLIB_DEPRECATED_IN_2_38_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_40_FOR" c:identifier="GLIB_DEPRECATED_IN_2_40_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_42_FOR" c:identifier="GLIB_DEPRECATED_IN_2_42_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_44_FOR" c:identifier="GLIB_DEPRECATED_IN_2_44_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_46_FOR" c:identifier="GLIB_DEPRECATED_IN_2_46_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_48_FOR" c:identifier="GLIB_DEPRECATED_IN_2_48_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_50_FOR" c:identifier="GLIB_DEPRECATED_IN_2_50_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_52_FOR" c:identifier="GLIB_DEPRECATED_IN_2_52_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_54_FOR" c:identifier="GLIB_DEPRECATED_IN_2_54_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_56_FOR" c:identifier="GLIB_DEPRECATED_IN_2_56_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_58_FOR" c:identifier="GLIB_DEPRECATED_IN_2_58_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_60_FOR" c:identifier="GLIB_DEPRECATED_IN_2_60_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_62_FOR" c:identifier="GLIB_DEPRECATED_IN_2_62_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_64_FOR" c:identifier="GLIB_DEPRECATED_IN_2_64_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_IN_2_66_FOR" c:identifier="GLIB_DEPRECATED_IN_2_66_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_FOR" c:identifier="GLIB_DEPRECATED_MACRO_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_26_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_26_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_28_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_28_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_30_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_30_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_32_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_32_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_34_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_34_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_36_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_36_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_38_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_38_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_40_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_40_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_42_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_42_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_44_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_44_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_46_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_46_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_48_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_48_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_50_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_50_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_52_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_52_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_54_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_54_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_56_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_56_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_58_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_58_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_60_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_60_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_62_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_62_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_64_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_64_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_MACRO_IN_2_66_FOR" c:identifier="GLIB_DEPRECATED_MACRO_IN_2_66_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_FOR" c:identifier="GLIB_DEPRECATED_TYPE_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_26_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_26_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_28_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_28_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_30_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_30_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_32_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_32_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_34_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_34_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_36_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_36_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_38_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_38_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_40_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_40_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_42_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_42_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_44_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_44_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_46_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_46_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_48_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_48_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_50_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_50_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_52_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_52_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_54_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_54_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_56_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_56_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_58_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_58_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_60_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_60_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_62_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_62_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_64_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_64_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="DEPRECATED_TYPE_IN_2_66_FOR" c:identifier="GLIB_DEPRECATED_TYPE_IN_2_66_FOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="f">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="DIR_SEPARATOR" value="47" c:type="G_DIR_SEPARATOR">
|
|
<doc xml:space="preserve">The directory separator character.
|
|
This is '/' on UNIX machines and '\' under Windows.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="DIR_SEPARATOR_S" value="/" c:type="G_DIR_SEPARATOR_S">
|
|
<doc xml:space="preserve">The directory separator as a string.
|
|
This is "/" on UNIX machines and "\" under Windows.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<record name="Data" c:type="GData" disguised="1">
|
|
<doc xml:space="preserve">The #GData struct is an opaque data structure to represent a
|
|
[Keyed Data List][glib-Keyed-Data-Lists]. It should only be
|
|
accessed via the following functions.</doc>
|
|
</record>
|
|
<callback name="DataForeachFunc" c:type="GDataForeachFunc">
|
|
<doc xml:space="preserve">Specifies the type of function passed to g_dataset_foreach(). It is
|
|
called with each #GQuark id and associated data element, together
|
|
with the @user_data parameter supplied to g_dataset_foreach().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="key_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GQuark id to identifying the data element.</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data element.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2">
|
|
<doc xml:space="preserve">user data passed to g_dataset_foreach().</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<record name="Date" c:type="GDate" glib:type-name="GDate" glib:get-type="g_date_get_type" c:symbol-prefix="date">
|
|
<doc xml:space="preserve">Represents a day between January 1, Year 1 and a few thousand years in
|
|
the future. None of its members should be accessed directly.
|
|
|
|
If the #GDate-struct is obtained from g_date_new(), it will be safe
|
|
to mutate but invalid and thus not safe for calendrical computations.
|
|
|
|
If it's declared on the stack, it will contain garbage so must be
|
|
initialized with g_date_clear(). g_date_clear() makes the date invalid
|
|
but safe. An invalid date doesn't represent a day, it's "empty." A date
|
|
becomes valid after you set it to a Julian day or you set a day, month,
|
|
and year.</doc>
|
|
<field name="julian_days" writable="1" bits="32">
|
|
<doc xml:space="preserve">the Julian representation of the date</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="julian" writable="1" bits="1">
|
|
<doc xml:space="preserve">this bit is set if @julian_days is valid</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="dmy" writable="1" bits="1">
|
|
<doc xml:space="preserve">this is set if @day, @month and @year are valid</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="day" writable="1" bits="6">
|
|
<doc xml:space="preserve">the day of the day-month-year representation of the date,
|
|
as a number between 1 and 31</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="month" writable="1" bits="4">
|
|
<doc xml:space="preserve">the day of the day-month-year representation of the date,
|
|
as a number between 1 and 12</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="year" writable="1" bits="16">
|
|
<doc xml:space="preserve">the day of the day-month-year representation of the date</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<constructor name="new" c:identifier="g_date_new">
|
|
<doc xml:space="preserve">Allocates a #GDate and initializes
|
|
it to a safe state. The new date will
|
|
be cleared (as if you'd called g_date_clear()) but invalid (it won't
|
|
represent an existing day). Free the return value with g_date_free().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated #GDate</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</return-value>
|
|
</constructor>
|
|
<constructor name="new_dmy" c:identifier="g_date_new_dmy">
|
|
<doc xml:space="preserve">Like g_date_new(), but also sets the value of the date. Assuming the
|
|
day-month-year triplet you pass in represents an existing day, the
|
|
returned date will be valid.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated #GDate initialized with @day, @month, and @year</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="day" transfer-ownership="none">
|
|
<doc xml:space="preserve">day of the month</doc>
|
|
<type name="DateDay" c:type="GDateDay"/>
|
|
</parameter>
|
|
<parameter name="month" transfer-ownership="none">
|
|
<doc xml:space="preserve">month of the year</doc>
|
|
<type name="DateMonth" c:type="GDateMonth"/>
|
|
</parameter>
|
|
<parameter name="year" transfer-ownership="none">
|
|
<doc xml:space="preserve">year</doc>
|
|
<type name="DateYear" c:type="GDateYear"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_julian" c:identifier="g_date_new_julian">
|
|
<doc xml:space="preserve">Like g_date_new(), but also sets the value of the date. Assuming the
|
|
Julian day number you pass in is valid (greater than 0, less than an
|
|
unreasonably large number), the returned date will be valid.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated #GDate initialized with @julian_day</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="julian_day" transfer-ownership="none">
|
|
<doc xml:space="preserve">days since January 1, Year 1</doc>
|
|
<type name="guint32" c:type="guint32"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<method name="add_days" c:identifier="g_date_add_days">
|
|
<doc xml:space="preserve">Increments a date some number of days.
|
|
To move forward by weeks, add weeks*7 days.
|
|
The date must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to increment</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="n_days" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of days to move the date forward</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_months" c:identifier="g_date_add_months">
|
|
<doc xml:space="preserve">Increments a date by some number of months.
|
|
If the day of the month is greater than 28,
|
|
this routine may change the day of the month
|
|
(because the destination month may not have
|
|
the current day in it). The date must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to increment</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="n_months" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of months to move forward</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_years" c:identifier="g_date_add_years">
|
|
<doc xml:space="preserve">Increments a date by some number of years.
|
|
If the date is February 29, and the destination
|
|
year is not a leap year, the date will be changed
|
|
to February 28. The date must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to increment</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="n_years" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of years to move forward</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="clamp" c:identifier="g_date_clamp">
|
|
<doc xml:space="preserve">If @date is prior to @min_date, sets @date equal to @min_date.
|
|
If @date falls after @max_date, sets @date equal to @max_date.
|
|
Otherwise, @date is unchanged.
|
|
Either of @min_date and @max_date may be %NULL.
|
|
All non-%NULL dates must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to clamp</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="min_date" transfer-ownership="none">
|
|
<doc xml:space="preserve">minimum accepted value for @date</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</parameter>
|
|
<parameter name="max_date" transfer-ownership="none">
|
|
<doc xml:space="preserve">maximum accepted value for @date</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="clear" c:identifier="g_date_clear">
|
|
<doc xml:space="preserve">Initializes one or more #GDate structs to a safe but invalid
|
|
state. The cleared dates will not represent an existing date, but will
|
|
not contain garbage. Useful to init a date declared on the stack.
|
|
Validity can be tested with g_date_valid().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">pointer to one or more dates to clear</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="n_dates" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of dates to clear</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="compare" c:identifier="g_date_compare">
|
|
<doc xml:space="preserve">qsort()-style comparison function for dates.
|
|
Both dates must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">0 for equal, less than zero if @lhs is less than @rhs,
|
|
greater than zero if @lhs is greater than @rhs</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="lhs" transfer-ownership="none">
|
|
<doc xml:space="preserve">first date to compare</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="rhs" transfer-ownership="none">
|
|
<doc xml:space="preserve">second date to compare</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="copy" c:identifier="g_date_copy" version="2.56">
|
|
<doc xml:space="preserve">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.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated #GDate initialized from @date</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to copy</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="days_between" c:identifier="g_date_days_between">
|
|
<doc xml:space="preserve">Computes the number of days between two dates.
|
|
If @date2 is prior to @date1, the returned value is negative.
|
|
Both dates must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of days between @date1 and @date2</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date1" transfer-ownership="none">
|
|
<doc xml:space="preserve">the first date</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="date2" transfer-ownership="none">
|
|
<doc xml:space="preserve">the second date</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free" c:identifier="g_date_free">
|
|
<doc xml:space="preserve">Frees a #GDate returned from g_date_new().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to free</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_day" c:identifier="g_date_get_day">
|
|
<doc xml:space="preserve">Returns the day of the month. The date must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">day of the month</doc>
|
|
<type name="DateDay" c:type="GDateDay"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to extract the day of the month from</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_day_of_year" c:identifier="g_date_get_day_of_year">
|
|
<doc xml:space="preserve">Returns the day of the year, where Jan 1 is the first day of the
|
|
year. The date must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">day of the year</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to extract day of year from</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_iso8601_week_of_year" c:identifier="g_date_get_iso8601_week_of_year" version="2.6">
|
|
<doc xml:space="preserve">Returns the week of the year, where weeks are interpreted according
|
|
to ISO 8601.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">ISO 8601 week number of the year.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid #GDate</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_julian" c:identifier="g_date_get_julian">
|
|
<doc xml:space="preserve">Returns the Julian day or "serial number" of the #GDate. The
|
|
Julian day is simply the number of days since January 1, Year 1; i.e.,
|
|
January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2,
|
|
etc. The date must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">Julian day</doc>
|
|
<type name="guint32" c:type="guint32"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to extract the Julian day from</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_monday_week_of_year" c:identifier="g_date_get_monday_week_of_year">
|
|
<doc xml:space="preserve">Returns the week of the year, where weeks are understood to start on
|
|
Monday. If the date is before the first Monday of the year, return 0.
|
|
The date must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">week of the year</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_month" c:identifier="g_date_get_month">
|
|
<doc xml:space="preserve">Returns the month of the year. The date must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">month of the year as a #GDateMonth</doc>
|
|
<type name="DateMonth" c:type="GDateMonth"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to get the month from</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_sunday_week_of_year" c:identifier="g_date_get_sunday_week_of_year">
|
|
<doc xml:space="preserve">Returns the week of the year during which this date falls, if
|
|
weeks are understood to begin on Sunday. The date must be valid.
|
|
Can return 0 if the day is before the first Sunday of the year.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">week number</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_weekday" c:identifier="g_date_get_weekday">
|
|
<doc xml:space="preserve">Returns the day of the week for a #GDate. The date must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">day of the week as a #GDateWeekday.</doc>
|
|
<type name="DateWeekday" c:type="GDateWeekday"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_year" c:identifier="g_date_get_year">
|
|
<doc xml:space="preserve">Returns the year of a #GDate. The date must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">year in which the date falls</doc>
|
|
<type name="DateYear" c:type="GDateYear"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_first_of_month" c:identifier="g_date_is_first_of_month">
|
|
<doc xml:space="preserve">Returns %TRUE if the date is on the first of a month.
|
|
The date must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the date is the first of the month</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to check</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_last_of_month" c:identifier="g_date_is_last_of_month">
|
|
<doc xml:space="preserve">Returns %TRUE if the date is the last day of the month.
|
|
The date must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the date is the last day of the month</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to check</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="order" c:identifier="g_date_order">
|
|
<doc xml:space="preserve">Checks if @date1 is less than or equal to @date2,
|
|
and swap the values if this is not the case.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date1" transfer-ownership="none">
|
|
<doc xml:space="preserve">the first date</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="date2" transfer-ownership="none">
|
|
<doc xml:space="preserve">the second date</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_day" c:identifier="g_date_set_day">
|
|
<doc xml:space="preserve">Sets the day of the month for a #GDate. If the resulting
|
|
day-month-year triplet is invalid, the date will be invalid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="day" transfer-ownership="none">
|
|
<doc xml:space="preserve">day to set</doc>
|
|
<type name="DateDay" c:type="GDateDay"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_dmy" c:identifier="g_date_set_dmy">
|
|
<doc xml:space="preserve">Sets the value of a #GDate from a day, month, and year.
|
|
The day-month-year triplet must be valid; if you aren't
|
|
sure it is, call g_date_valid_dmy() to check before you
|
|
set it.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="day" transfer-ownership="none">
|
|
<doc xml:space="preserve">day</doc>
|
|
<type name="DateDay" c:type="GDateDay"/>
|
|
</parameter>
|
|
<parameter name="month" transfer-ownership="none">
|
|
<doc xml:space="preserve">month</doc>
|
|
<type name="DateMonth" c:type="GDateMonth"/>
|
|
</parameter>
|
|
<parameter name="y" transfer-ownership="none">
|
|
<doc xml:space="preserve">year</doc>
|
|
<type name="DateYear" c:type="GDateYear"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_julian" c:identifier="g_date_set_julian">
|
|
<doc xml:space="preserve">Sets the value of a #GDate from a Julian day number.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="julian_date" transfer-ownership="none">
|
|
<doc xml:space="preserve">Julian day number (days since January 1, Year 1)</doc>
|
|
<type name="guint32" c:type="guint32"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_month" c:identifier="g_date_set_month">
|
|
<doc xml:space="preserve">Sets the month of the year for a #GDate. If the resulting
|
|
day-month-year triplet is invalid, the date will be invalid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="month" transfer-ownership="none">
|
|
<doc xml:space="preserve">month to set</doc>
|
|
<type name="DateMonth" c:type="GDateMonth"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_parse" c:identifier="g_date_set_parse">
|
|
<doc xml:space="preserve">Parses a user-inputted string @str, and try to figure out what date it
|
|
represents, taking the [current locale][setlocale] into account. If the
|
|
string is successfully parsed, the date will be valid after the call.
|
|
Otherwise, it will be invalid. You should check using g_date_valid()
|
|
to see whether the parsing succeeded.
|
|
|
|
This function is not appropriate for file formats and the like; it
|
|
isn't very precise, and its exact behavior varies with the locale.
|
|
It's intended to be a heuristic routine that guesses what the user
|
|
means by a given string (and it does work pretty well in that
|
|
capacity).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to fill in</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">string to parse</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_time" c:identifier="g_date_set_time" deprecated="1" deprecated-version="2.10">
|
|
<doc xml:space="preserve">Sets the value of a date from a #GTime value.
|
|
The time to date conversion is done using the user's current timezone.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_date_set_time_t() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate.</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="time_" transfer-ownership="none">
|
|
<doc xml:space="preserve">#GTime value to set.</doc>
|
|
<type name="Time" c:type="GTime"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_time_t" c:identifier="g_date_set_time_t" version="2.10">
|
|
<doc xml:space="preserve">Sets the value of a date to the date corresponding to a time
|
|
specified as a time_t. The time to date conversion is done using
|
|
the user's current timezone.
|
|
|
|
To set the value of a date to the current day, you could write:
|
|
|[<!-- language="C" -->
|
|
time_t now = time (NULL);
|
|
if (now == (time_t) -1)
|
|
// handle the error
|
|
g_date_set_time_t (date, now);
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="timet" transfer-ownership="none">
|
|
<doc xml:space="preserve">time_t value to set</doc>
|
|
<type name="glong" c:type="time_t"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_time_val" c:identifier="g_date_set_time_val" version="2.10" deprecated="1" deprecated-version="2.62">
|
|
<doc xml:space="preserve">Sets the value of a date from a #GTimeVal value. Note that the
|
|
@tv_usec member is ignored, because #GDate can't make use of the
|
|
additional precision.
|
|
|
|
The time to date conversion is done using the user's current timezone.</doc>
|
|
<doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use g_date_set_time_t()
|
|
instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="timeval" transfer-ownership="none">
|
|
<doc xml:space="preserve">#GTimeVal value to set</doc>
|
|
<type name="TimeVal" c:type="GTimeVal*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_year" c:identifier="g_date_set_year">
|
|
<doc xml:space="preserve">Sets the year for a #GDate. If the resulting day-month-year
|
|
triplet is invalid, the date will be invalid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="year" transfer-ownership="none">
|
|
<doc xml:space="preserve">year to set</doc>
|
|
<type name="DateYear" c:type="GDateYear"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="subtract_days" c:identifier="g_date_subtract_days">
|
|
<doc xml:space="preserve">Moves a date some number of days into the past.
|
|
To move by weeks, just move by weeks*7 days.
|
|
The date must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to decrement</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="n_days" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of days to move</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="subtract_months" c:identifier="g_date_subtract_months">
|
|
<doc xml:space="preserve">Moves a date some number of months into the past.
|
|
If the current day of the month doesn't exist in
|
|
the destination month, the day of the month
|
|
may change. The date must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to decrement</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="n_months" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of months to move</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="subtract_years" c:identifier="g_date_subtract_years">
|
|
<doc xml:space="preserve">Moves a date some number of years into the past.
|
|
If the current day doesn't exist in the destination
|
|
year (i.e. it's February 29 and you move to a non-leap-year)
|
|
then the day is changed to February 29. The date
|
|
must be valid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to decrement</doc>
|
|
<type name="Date" c:type="GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="n_years" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of years to move</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="to_struct_tm" c:identifier="g_date_to_struct_tm">
|
|
<doc xml:space="preserve">Fills in the date-related bits of a struct tm using the @date value.
|
|
Initializes the non-date parts with something safe but meaningless.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to set the struct tm from</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</instance-parameter>
|
|
<parameter name="tm" transfer-ownership="none">
|
|
<doc xml:space="preserve">struct tm to fill</doc>
|
|
<type name="gpointer" c:type="tm*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="valid" c:identifier="g_date_valid">
|
|
<doc xml:space="preserve">Returns %TRUE if the #GDate represents an existing day. The date must not
|
|
contain garbage; it should have been initialized with g_date_clear()
|
|
if it wasn't allocated by one of the g_date_new() variants.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">Whether the date is valid</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDate to check</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="get_days_in_month" c:identifier="g_date_get_days_in_month">
|
|
<doc xml:space="preserve">Returns the number of days in a month, taking leap
|
|
years into account.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">number of days in @month during the @year</doc>
|
|
<type name="guint8" c:type="guint8"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="month" transfer-ownership="none">
|
|
<doc xml:space="preserve">month</doc>
|
|
<type name="DateMonth" c:type="GDateMonth"/>
|
|
</parameter>
|
|
<parameter name="year" transfer-ownership="none">
|
|
<doc xml:space="preserve">year</doc>
|
|
<type name="DateYear" c:type="GDateYear"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="get_monday_weeks_in_year" c:identifier="g_date_get_monday_weeks_in_year">
|
|
<doc xml:space="preserve">Returns the number of weeks in the year, where weeks
|
|
are taken to start on Monday. Will be 52 or 53. The
|
|
date must be valid. (Years always have 52 7-day periods,
|
|
plus 1 or 2 extra days depending on whether it's a leap
|
|
year. This function is basically telling you how many
|
|
Mondays are in the year, i.e. there are 53 Mondays if
|
|
one of the extra days happens to be a Monday.)</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">number of Mondays in the year</doc>
|
|
<type name="guint8" c:type="guint8"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="year" transfer-ownership="none">
|
|
<doc xml:space="preserve">a year</doc>
|
|
<type name="DateYear" c:type="GDateYear"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="get_sunday_weeks_in_year" c:identifier="g_date_get_sunday_weeks_in_year">
|
|
<doc xml:space="preserve">Returns the number of weeks in the year, where weeks
|
|
are taken to start on Sunday. Will be 52 or 53. The
|
|
date must be valid. (Years always have 52 7-day periods,
|
|
plus 1 or 2 extra days depending on whether it's a leap
|
|
year. This function is basically telling you how many
|
|
Sundays are in the year, i.e. there are 53 Sundays if
|
|
one of the extra days happens to be a Sunday.)</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of weeks in @year</doc>
|
|
<type name="guint8" c:type="guint8"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="year" transfer-ownership="none">
|
|
<doc xml:space="preserve">year to count weeks in</doc>
|
|
<type name="DateYear" c:type="GDateYear"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="is_leap_year" c:identifier="g_date_is_leap_year">
|
|
<doc xml:space="preserve">Returns %TRUE if the year is a leap year.
|
|
|
|
For the purposes of this function, leap year is every year
|
|
divisible by 4 unless that year is divisible by 100. If it
|
|
is divisible by 100 it would be a leap year only if that year
|
|
is also divisible by 400.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the year is a leap year</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="year" transfer-ownership="none">
|
|
<doc xml:space="preserve">year to check</doc>
|
|
<type name="DateYear" c:type="GDateYear"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strftime" c:identifier="g_date_strftime">
|
|
<doc xml:space="preserve">Generates a printed representation of the date, in a
|
|
[locale][setlocale]-specific way.
|
|
Works just like the platform's C library strftime() function,
|
|
but only accepts date-related formats; time-related formats
|
|
give undefined results. Date must be valid. Unlike strftime()
|
|
(which uses the locale encoding), works on a UTF-8 format
|
|
string and stores a UTF-8 result.
|
|
|
|
This function does not provide any conversion specifiers in
|
|
addition to those implemented by the platform's C library.
|
|
For example, don't expect that using g_date_strftime() would
|
|
make the \%F provided by the C99 strftime() work on Windows
|
|
where the C library only complies to C89.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">number of characters written to the buffer, or 0 the buffer was too small</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="s" transfer-ownership="none">
|
|
<doc xml:space="preserve">destination buffer</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="slen" transfer-ownership="none">
|
|
<doc xml:space="preserve">buffer size</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">format string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">valid #GDate</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="valid_day" c:identifier="g_date_valid_day">
|
|
<doc xml:space="preserve">Returns %TRUE if the day of the month is valid (a day is valid if it's
|
|
between 1 and 31 inclusive).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the day is valid</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="day" transfer-ownership="none">
|
|
<doc xml:space="preserve">day to check</doc>
|
|
<type name="DateDay" c:type="GDateDay"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="valid_dmy" c:identifier="g_date_valid_dmy">
|
|
<doc xml:space="preserve">Returns %TRUE if the day-month-year triplet forms a valid, existing day
|
|
in the range of days #GDate understands (Year 1 or later, no more than
|
|
a few thousand years in the future).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the date is a valid one</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="day" transfer-ownership="none">
|
|
<doc xml:space="preserve">day</doc>
|
|
<type name="DateDay" c:type="GDateDay"/>
|
|
</parameter>
|
|
<parameter name="month" transfer-ownership="none">
|
|
<doc xml:space="preserve">month</doc>
|
|
<type name="DateMonth" c:type="GDateMonth"/>
|
|
</parameter>
|
|
<parameter name="year" transfer-ownership="none">
|
|
<doc xml:space="preserve">year</doc>
|
|
<type name="DateYear" c:type="GDateYear"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="valid_julian" c:identifier="g_date_valid_julian">
|
|
<doc xml:space="preserve">Returns %TRUE if the Julian day is valid. Anything greater than zero
|
|
is basically a valid Julian, though there is a 32-bit limit.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the Julian day is valid</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="julian_date" transfer-ownership="none">
|
|
<doc xml:space="preserve">Julian day to check</doc>
|
|
<type name="guint32" c:type="guint32"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="valid_month" c:identifier="g_date_valid_month">
|
|
<doc xml:space="preserve">Returns %TRUE if the month value is valid. The 12 #GDateMonth
|
|
enumeration values are the only valid months.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the month is valid</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="month" transfer-ownership="none">
|
|
<doc xml:space="preserve">month</doc>
|
|
<type name="DateMonth" c:type="GDateMonth"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="valid_weekday" c:identifier="g_date_valid_weekday">
|
|
<doc xml:space="preserve">Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration
|
|
values are the only valid weekdays.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the weekday is valid</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="weekday" transfer-ownership="none">
|
|
<doc xml:space="preserve">weekday</doc>
|
|
<type name="DateWeekday" c:type="GDateWeekday"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="valid_year" c:identifier="g_date_valid_year">
|
|
<doc xml:space="preserve">Returns %TRUE if the year is valid. Any year greater than 0 is valid,
|
|
though there is a 16-bit limit to what #GDate will understand.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the year is valid</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="year" transfer-ownership="none">
|
|
<doc xml:space="preserve">year</doc>
|
|
<type name="DateYear" c:type="GDateYear"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<enumeration name="DateDMY" c:type="GDateDMY">
|
|
<doc xml:space="preserve">This enumeration isn't used in the API, but may be useful if you need
|
|
to mark a number as a day, month, or year.</doc>
|
|
<member name="day" value="0" c:identifier="G_DATE_DAY">
|
|
<doc xml:space="preserve">a day</doc>
|
|
</member>
|
|
<member name="month" value="1" c:identifier="G_DATE_MONTH">
|
|
<doc xml:space="preserve">a month</doc>
|
|
</member>
|
|
<member name="year" value="2" c:identifier="G_DATE_YEAR">
|
|
<doc xml:space="preserve">a year</doc>
|
|
</member>
|
|
</enumeration>
|
|
<enumeration name="DateMonth" c:type="GDateMonth">
|
|
<doc xml:space="preserve">Enumeration representing a month; values are #G_DATE_JANUARY,
|
|
#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the invalid value.</doc>
|
|
<member name="bad_month" value="0" c:identifier="G_DATE_BAD_MONTH">
|
|
<doc xml:space="preserve">invalid value</doc>
|
|
</member>
|
|
<member name="january" value="1" c:identifier="G_DATE_JANUARY">
|
|
<doc xml:space="preserve">January</doc>
|
|
</member>
|
|
<member name="february" value="2" c:identifier="G_DATE_FEBRUARY">
|
|
<doc xml:space="preserve">February</doc>
|
|
</member>
|
|
<member name="march" value="3" c:identifier="G_DATE_MARCH">
|
|
<doc xml:space="preserve">March</doc>
|
|
</member>
|
|
<member name="april" value="4" c:identifier="G_DATE_APRIL">
|
|
<doc xml:space="preserve">April</doc>
|
|
</member>
|
|
<member name="may" value="5" c:identifier="G_DATE_MAY">
|
|
<doc xml:space="preserve">May</doc>
|
|
</member>
|
|
<member name="june" value="6" c:identifier="G_DATE_JUNE">
|
|
<doc xml:space="preserve">June</doc>
|
|
</member>
|
|
<member name="july" value="7" c:identifier="G_DATE_JULY">
|
|
<doc xml:space="preserve">July</doc>
|
|
</member>
|
|
<member name="august" value="8" c:identifier="G_DATE_AUGUST">
|
|
<doc xml:space="preserve">August</doc>
|
|
</member>
|
|
<member name="september" value="9" c:identifier="G_DATE_SEPTEMBER">
|
|
<doc xml:space="preserve">September</doc>
|
|
</member>
|
|
<member name="october" value="10" c:identifier="G_DATE_OCTOBER">
|
|
<doc xml:space="preserve">October</doc>
|
|
</member>
|
|
<member name="november" value="11" c:identifier="G_DATE_NOVEMBER">
|
|
<doc xml:space="preserve">November</doc>
|
|
</member>
|
|
<member name="december" value="12" c:identifier="G_DATE_DECEMBER">
|
|
<doc xml:space="preserve">December</doc>
|
|
</member>
|
|
</enumeration>
|
|
<record name="DateTime" c:type="GDateTime" version="2.26" glib:type-name="GDateTime" glib:get-type="g_date_time_get_type" c:symbol-prefix="date_time">
|
|
<doc xml:space="preserve">`GDateTime` is an opaque structure whose members
|
|
cannot be accessed directly.</doc>
|
|
<constructor name="new" c:identifier="g_date_time_new" version="2.26">
|
|
<doc xml:space="preserve">Creates a new #GDateTime corresponding to the given date and time in
|
|
the time zone @tz.
|
|
|
|
The @year must be between 1 and 9999, @month between 1 and 12 and @day
|
|
between 1 and 28, 29, 30 or 31 depending on the month and the year.
|
|
|
|
@hour must be between 0 and 23 and @minute must be between 0 and 59.
|
|
|
|
@seconds must be at least 0.0 and must be strictly less than 60.0.
|
|
It will be rounded down to the nearest microsecond.
|
|
|
|
If the given time is not representable in the given time zone (for
|
|
example, 02:30 on March 14th 2010 in Toronto, due to daylight savings
|
|
time) then the time will be rounded up to the nearest existing time
|
|
(in this case, 03:00). If this matters to you then you should verify
|
|
the return value for containing the same as the numbers you gave.
|
|
|
|
In the case that the given time is ambiguous in the given time zone
|
|
(for example, 01:30 on November 7th 2010 in Toronto, due to daylight
|
|
savings time) then the time falling within standard (ie:
|
|
non-daylight) time is taken.
|
|
|
|
It not considered a programmer error for the values to this function
|
|
to be out of range, but in the case that they are, the function will
|
|
return %NULL.
|
|
|
|
You should release the return value by calling g_date_time_unref()
|
|
when you are done with it.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a new #GDateTime, or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="tz" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeZone</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</parameter>
|
|
<parameter name="year" transfer-ownership="none">
|
|
<doc xml:space="preserve">the year component of the date</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="month" transfer-ownership="none">
|
|
<doc xml:space="preserve">the month component of the date</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="day" transfer-ownership="none">
|
|
<doc xml:space="preserve">the day component of the date</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="hour" transfer-ownership="none">
|
|
<doc xml:space="preserve">the hour component of the date</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="minute" transfer-ownership="none">
|
|
<doc xml:space="preserve">the minute component of the date</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="seconds" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of seconds past the minute</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_from_iso8601" c:identifier="g_date_time_new_from_iso8601" version="2.56">
|
|
<doc xml:space="preserve">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, with
|
|
some extensions from [RFC 3339](https://tools.ietf.org/html/rfc3339) as
|
|
mentioned below.
|
|
|
|
Note that as #GDateTime "is oblivious to leap seconds", leap seconds information
|
|
in an ISO-8601 string will be ignored, so a `23:59:60` time would be parsed as
|
|
`23:59:59`.
|
|
|
|
<sep> is the separator and can be either 'T', 't' or ' '. The latter two
|
|
separators are an extension from
|
|
[RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6).
|
|
|
|
<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.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a new #GDateTime, or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="text" transfer-ownership="none">
|
|
<doc xml:space="preserve">an ISO 8601 formatted time string.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="default_tz" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GTimeZone to use if the text doesn't contain a
|
|
timezone, or %NULL.</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_from_timeval_local" c:identifier="g_date_time_new_from_timeval_local" version="2.26" deprecated="1" deprecated-version="2.62">
|
|
<doc xml:space="preserve">Creates a #GDateTime corresponding to the given #GTimeVal @tv in the
|
|
local time zone.
|
|
|
|
The time contained in a #GTimeVal is always stored in the form of
|
|
seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the
|
|
local time offset.
|
|
|
|
This call can fail (returning %NULL) if @tv represents a time outside
|
|
of the supported range of #GDateTime.
|
|
|
|
You should release the return value by calling g_date_time_unref()
|
|
when you are done with it.</doc>
|
|
<doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use
|
|
g_date_time_new_from_unix_local() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a new #GDateTime, or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="tv" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeVal</doc>
|
|
<type name="TimeVal" c:type="const GTimeVal*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_from_timeval_utc" c:identifier="g_date_time_new_from_timeval_utc" version="2.26" deprecated="1" deprecated-version="2.62">
|
|
<doc xml:space="preserve">Creates a #GDateTime corresponding to the given #GTimeVal @tv in UTC.
|
|
|
|
The time contained in a #GTimeVal is always stored in the form of
|
|
seconds elapsed since 1970-01-01 00:00:00 UTC.
|
|
|
|
This call can fail (returning %NULL) if @tv represents a time outside
|
|
of the supported range of #GDateTime.
|
|
|
|
You should release the return value by calling g_date_time_unref()
|
|
when you are done with it.</doc>
|
|
<doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use
|
|
g_date_time_new_from_unix_utc() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a new #GDateTime, or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="tv" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeVal</doc>
|
|
<type name="TimeVal" c:type="const GTimeVal*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_from_unix_local" c:identifier="g_date_time_new_from_unix_local" version="2.26">
|
|
<doc xml:space="preserve">Creates a #GDateTime corresponding to the given Unix time @t in the
|
|
local time zone.
|
|
|
|
Unix time is the number of seconds that have elapsed since 1970-01-01
|
|
00:00:00 UTC, regardless of the local time offset.
|
|
|
|
This call can fail (returning %NULL) if @t represents a time outside
|
|
of the supported range of #GDateTime.
|
|
|
|
You should release the return value by calling g_date_time_unref()
|
|
when you are done with it.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a new #GDateTime, or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="t" transfer-ownership="none">
|
|
<doc xml:space="preserve">the Unix time</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_from_unix_utc" c:identifier="g_date_time_new_from_unix_utc" version="2.26">
|
|
<doc xml:space="preserve">Creates a #GDateTime corresponding to the given Unix time @t in UTC.
|
|
|
|
Unix time is the number of seconds that have elapsed since 1970-01-01
|
|
00:00:00 UTC.
|
|
|
|
This call can fail (returning %NULL) if @t represents a time outside
|
|
of the supported range of #GDateTime.
|
|
|
|
You should release the return value by calling g_date_time_unref()
|
|
when you are done with it.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a new #GDateTime, or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="t" transfer-ownership="none">
|
|
<doc xml:space="preserve">the Unix time</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_local" c:identifier="g_date_time_new_local" version="2.26">
|
|
<doc xml:space="preserve">Creates a new #GDateTime corresponding to the given date and time in
|
|
the local time zone.
|
|
|
|
This call is equivalent to calling g_date_time_new() with the time
|
|
zone returned by g_time_zone_new_local().</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a #GDateTime, or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="year" transfer-ownership="none">
|
|
<doc xml:space="preserve">the year component of the date</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="month" transfer-ownership="none">
|
|
<doc xml:space="preserve">the month component of the date</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="day" transfer-ownership="none">
|
|
<doc xml:space="preserve">the day component of the date</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="hour" transfer-ownership="none">
|
|
<doc xml:space="preserve">the hour component of the date</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="minute" transfer-ownership="none">
|
|
<doc xml:space="preserve">the minute component of the date</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="seconds" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of seconds past the minute</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_now" c:identifier="g_date_time_new_now" version="2.26">
|
|
<doc xml:space="preserve">Creates a #GDateTime corresponding to this exact instant in the given
|
|
time zone @tz. The time is as accurate as the system allows, to a
|
|
maximum accuracy of 1 microsecond.
|
|
|
|
This function will always succeed unless GLib is still being used after the
|
|
year 9999.
|
|
|
|
You should release the return value by calling g_date_time_unref()
|
|
when you are done with it.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a new #GDateTime, or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="tz" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeZone</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_now_local" c:identifier="g_date_time_new_now_local" version="2.26">
|
|
<doc xml:space="preserve">Creates a #GDateTime corresponding to this exact instant in the local
|
|
time zone.
|
|
|
|
This is equivalent to calling g_date_time_new_now() with the time
|
|
zone returned by g_time_zone_new_local().</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a new #GDateTime, or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
</constructor>
|
|
<constructor name="new_now_utc" c:identifier="g_date_time_new_now_utc" version="2.26">
|
|
<doc xml:space="preserve">Creates a #GDateTime corresponding to this exact instant in UTC.
|
|
|
|
This is equivalent to calling g_date_time_new_now() with the time
|
|
zone returned by g_time_zone_new_utc().</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a new #GDateTime, or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
</constructor>
|
|
<constructor name="new_utc" c:identifier="g_date_time_new_utc" version="2.26">
|
|
<doc xml:space="preserve">Creates a new #GDateTime corresponding to the given date and time in
|
|
UTC.
|
|
|
|
This call is equivalent to calling g_date_time_new() with the time
|
|
zone returned by g_time_zone_new_utc().</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a #GDateTime, or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="year" transfer-ownership="none">
|
|
<doc xml:space="preserve">the year component of the date</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="month" transfer-ownership="none">
|
|
<doc xml:space="preserve">the month component of the date</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="day" transfer-ownership="none">
|
|
<doc xml:space="preserve">the day component of the date</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="hour" transfer-ownership="none">
|
|
<doc xml:space="preserve">the hour component of the date</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="minute" transfer-ownership="none">
|
|
<doc xml:space="preserve">the minute component of the date</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="seconds" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of seconds past the minute</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<method name="add" c:identifier="g_date_time_add" version="2.26">
|
|
<doc xml:space="preserve">Creates a copy of @datetime and adds the specified timespan to the copy.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the newly created #GDateTime which
|
|
should be freed with g_date_time_unref(), or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
<parameter name="timespan" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeSpan</doc>
|
|
<type name="TimeSpan" c:type="GTimeSpan"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_days" c:identifier="g_date_time_add_days" version="2.26">
|
|
<doc xml:space="preserve">Creates a copy of @datetime and adds the specified number of days to the
|
|
copy. Add negative values to subtract days.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the newly created #GDateTime which
|
|
should be freed with g_date_time_unref(), or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
<parameter name="days" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of days</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_full" c:identifier="g_date_time_add_full" version="2.26">
|
|
<doc xml:space="preserve">Creates a new #GDateTime adding the specified values to the current date and
|
|
time in @datetime. Add negative values to subtract.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the newly created #GDateTime which
|
|
should be freed with g_date_time_unref(), or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
<parameter name="years" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of years to add</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="months" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of months to add</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="days" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of days to add</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="hours" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of hours to add</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="minutes" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of minutes to add</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="seconds" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of seconds to add</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_hours" c:identifier="g_date_time_add_hours" version="2.26">
|
|
<doc xml:space="preserve">Creates a copy of @datetime and adds the specified number of hours.
|
|
Add negative values to subtract hours.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the newly created #GDateTime which
|
|
should be freed with g_date_time_unref(), or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
<parameter name="hours" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of hours to add</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_minutes" c:identifier="g_date_time_add_minutes" version="2.26">
|
|
<doc xml:space="preserve">Creates a copy of @datetime adding the specified number of minutes.
|
|
Add negative values to subtract minutes.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the newly created #GDateTime which
|
|
should be freed with g_date_time_unref(), or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
<parameter name="minutes" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of minutes to add</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_months" c:identifier="g_date_time_add_months" version="2.26">
|
|
<doc xml:space="preserve">Creates a copy of @datetime and adds the specified number of months to the
|
|
copy. Add negative values to subtract months.
|
|
|
|
The day of the month of the resulting #GDateTime is clamped to the number
|
|
of days in the updated calendar month. For example, if adding 1 month to
|
|
31st January 2018, the result would be 28th February 2018. In 2020 (a leap
|
|
year), the result would be 29th February.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the newly created #GDateTime which
|
|
should be freed with g_date_time_unref(), or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
<parameter name="months" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of months</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_seconds" c:identifier="g_date_time_add_seconds" version="2.26">
|
|
<doc xml:space="preserve">Creates a copy of @datetime and adds the specified number of seconds.
|
|
Add negative values to subtract seconds.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the newly created #GDateTime which
|
|
should be freed with g_date_time_unref(), or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
<parameter name="seconds" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of seconds to add</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_weeks" c:identifier="g_date_time_add_weeks" version="2.26">
|
|
<doc xml:space="preserve">Creates a copy of @datetime and adds the specified number of weeks to the
|
|
copy. Add negative values to subtract weeks.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the newly created #GDateTime which
|
|
should be freed with g_date_time_unref(), or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
<parameter name="weeks" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of weeks</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_years" c:identifier="g_date_time_add_years" version="2.26">
|
|
<doc xml:space="preserve">Creates a copy of @datetime and adds the specified number of years to the
|
|
copy. Add negative values to subtract years.
|
|
|
|
As with g_date_time_add_months(), if the resulting date would be 29th
|
|
February on a non-leap year, the day will be clamped to 28th February.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the newly created #GDateTime which
|
|
should be freed with g_date_time_unref(), or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
<parameter name="years" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of years</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="difference" c:identifier="g_date_time_difference" version="2.26">
|
|
<doc xml:space="preserve">Calculates the difference in time between @end and @begin. The
|
|
#GTimeSpan that is returned is effectively @end - @begin (ie:
|
|
positive if the first parameter is larger).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the difference between the two #GDateTime, as a time
|
|
span expressed in microseconds.</doc>
|
|
<type name="TimeSpan" c:type="GTimeSpan"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="end" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
<parameter name="begin" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="format" c:identifier="g_date_time_format" version="2.26">
|
|
<doc xml:space="preserve">Creates a newly allocated string representing the requested @format.
|
|
|
|
The format strings understood by this function are a subset of the
|
|
strftime() format language as specified by C99. The \%D, \%U and \%W
|
|
conversions are not supported, nor is the 'E' modifier. The GNU
|
|
extensions \%k, \%l, \%s and \%P are supported, however, as are the
|
|
'0', '_' and '-' modifiers. The Python extension \%f is also supported.
|
|
|
|
In contrast to strftime(), this function always produces a UTF-8
|
|
string, regardless of the current locale. Note that the rendering of
|
|
many formats is locale-dependent and may not match the strftime()
|
|
output exactly.
|
|
|
|
The following format specifiers are supported:
|
|
|
|
- \%a: the abbreviated weekday name according to the current locale
|
|
- \%A: the full weekday name according to the current locale
|
|
- \%b: the abbreviated month name according to the current locale
|
|
- \%B: the full month name according to the current locale
|
|
- \%c: the preferred date and time representation for the current locale
|
|
- \%C: the century number (year/100) as a 2-digit integer (00-99)
|
|
- \%d: the day of the month as a decimal number (range 01 to 31)
|
|
- \%e: the day of the month as a decimal number (range 1 to 31)
|
|
- \%F: equivalent to `%Y-%m-%d` (the ISO 8601 date format)
|
|
- \%g: the last two digits of the ISO 8601 week-based year as a
|
|
decimal number (00-99). This works well with \%V and \%u.
|
|
- \%G: the ISO 8601 week-based year as a decimal number. This works
|
|
well with \%V and \%u.
|
|
- \%h: equivalent to \%b
|
|
- \%H: the hour as a decimal number using a 24-hour clock (range 00 to 23)
|
|
- \%I: the hour as a decimal number using a 12-hour clock (range 01 to 12)
|
|
- \%j: the day of the year as a decimal number (range 001 to 366)
|
|
- \%k: the hour (24-hour clock) as a decimal number (range 0 to 23);
|
|
single digits are preceded by a blank
|
|
- \%l: the hour (12-hour clock) as a decimal number (range 1 to 12);
|
|
single digits are preceded by a blank
|
|
- \%m: the month as a decimal number (range 01 to 12)
|
|
- \%M: the minute as a decimal number (range 00 to 59)
|
|
- \%f: the microsecond as a decimal number (range 000000 to 999999)
|
|
- \%p: either "AM" or "PM" according to the given time value, or the
|
|
corresponding strings for the current locale. Noon is treated as
|
|
"PM" and midnight as "AM". Use of this format specifier is discouraged, as
|
|
many locales have no concept of AM/PM formatting. Use \%c or \%X instead.
|
|
- \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for
|
|
the current locale. Use of this format specifier is discouraged, as
|
|
many locales have no concept of AM/PM formatting. Use \%c or \%X instead.
|
|
- \%r: the time in a.m. or p.m. notation. Use of this format specifier is
|
|
discouraged, as many locales have no concept of AM/PM formatting. Use \%c
|
|
or \%X instead.
|
|
- \%R: the time in 24-hour notation (\%H:\%M)
|
|
- \%s: the number of seconds since the Epoch, that is, since 1970-01-01
|
|
00:00:00 UTC
|
|
- \%S: the second as a decimal number (range 00 to 60)
|
|
- \%t: a tab character
|
|
- \%T: the time in 24-hour notation with seconds (\%H:\%M:\%S)
|
|
- \%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7,
|
|
Monday being 1. This works well with \%G and \%V.
|
|
- \%V: the ISO 8601 standard week number of the current year as a decimal
|
|
number, range 01 to 53, where week 1 is the first week that has at
|
|
least 4 days in the new year. See g_date_time_get_week_of_year().
|
|
This works well with \%G and \%u.
|
|
- \%w: the day of the week as a decimal, range 0 to 6, Sunday being 0.
|
|
This is not the ISO 8601 standard format -- use \%u instead.
|
|
- \%x: the preferred date representation for the current locale without
|
|
the time
|
|
- \%X: the preferred time representation for the current locale without
|
|
the date
|
|
- \%y: the year as a decimal number without the century
|
|
- \%Y: the year as a decimal number including the century
|
|
- \%z: the time zone as an offset from UTC (+hhmm)
|
|
- \%:z: the time zone as an offset from UTC (+hh:mm).
|
|
This is a gnulib strftime() extension. Since: 2.38
|
|
- \%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a
|
|
gnulib strftime() extension. Since: 2.38
|
|
- \%:::z: the time zone as an offset from UTC, with : to necessary
|
|
precision (e.g., -04, +05:30). This is a gnulib strftime() extension. Since: 2.38
|
|
- \%Z: the time zone or name or abbreviation
|
|
- \%\%: a literal \% character
|
|
|
|
Some conversion specifications can be modified by preceding the
|
|
conversion specifier by one or more modifier characters. The
|
|
following modifiers are supported for many of the numeric
|
|
conversions:
|
|
|
|
- O: Use alternative numeric symbols, if the current locale supports those.
|
|
- _: Pad a numeric result with spaces. This overrides the default padding
|
|
for the specifier.
|
|
- -: Do not pad a numeric result. This overrides the default padding
|
|
for the specifier.
|
|
- 0: Pad a numeric result with zeros. This overrides the default padding
|
|
for the specifier.
|
|
|
|
Additionally, when O is used with B, b, or h, it produces the alternative
|
|
form of a month name. The alternative form should be used when the month
|
|
name is used without a day number (e.g., standalone). It is required in
|
|
some languages (Baltic, Slavic, Greek, and more) due to their grammatical
|
|
rules. For other languages there is no difference. \%OB is a GNU and BSD
|
|
strftime() extension expected to be added to the future POSIX specification,
|
|
\%Ob and \%Oh are GNU strftime() extensions. Since: 2.56</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a newly allocated string formatted to
|
|
the requested format or %NULL in the case that there was an error (such
|
|
as a format specifier not being supported in the current locale). The
|
|
string should be freed with g_free().</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid UTF-8 string, containing the format for the
|
|
#GDateTime</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="format_iso8601" c:identifier="g_date_time_format_iso8601" version="2.62">
|
|
<doc xml:space="preserve">Format @datetime in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601),
|
|
including the date, time and time zone, and return that as a UTF-8 encoded
|
|
string.
|
|
|
|
Since GLib 2.66, this will output to sub-second precision if needed.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a newly allocated string formatted in
|
|
ISO 8601 format or %NULL in the case that there was an error. The string
|
|
should be freed with g_free().</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_day_of_month" c:identifier="g_date_time_get_day_of_month" version="2.26">
|
|
<doc xml:space="preserve">Retrieves the day of the month represented by @datetime in the gregorian
|
|
calendar.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the day of the month</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_day_of_week" c:identifier="g_date_time_get_day_of_week" version="2.26">
|
|
<doc xml:space="preserve">Retrieves the ISO 8601 day of the week on which @datetime falls (1 is
|
|
Monday, 2 is Tuesday... 7 is Sunday).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the day of the week</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_day_of_year" c:identifier="g_date_time_get_day_of_year" version="2.26">
|
|
<doc xml:space="preserve">Retrieves the day of the year represented by @datetime in the Gregorian
|
|
calendar.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the day of the year</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_hour" c:identifier="g_date_time_get_hour" version="2.26">
|
|
<doc xml:space="preserve">Retrieves the hour of the day represented by @datetime</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the hour of the day</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_microsecond" c:identifier="g_date_time_get_microsecond" version="2.26">
|
|
<doc xml:space="preserve">Retrieves the microsecond of the date represented by @datetime</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the microsecond of the second</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_minute" c:identifier="g_date_time_get_minute" version="2.26">
|
|
<doc xml:space="preserve">Retrieves the minute of the hour represented by @datetime</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the minute of the hour</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_month" c:identifier="g_date_time_get_month" version="2.26">
|
|
<doc xml:space="preserve">Retrieves the month of the year represented by @datetime in the Gregorian
|
|
calendar.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the month represented by @datetime</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_second" c:identifier="g_date_time_get_second" version="2.26">
|
|
<doc xml:space="preserve">Retrieves the second of the minute represented by @datetime</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the second represented by @datetime</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_seconds" c:identifier="g_date_time_get_seconds" version="2.26">
|
|
<doc xml:space="preserve">Retrieves the number of seconds since the start of the last minute,
|
|
including the fractional part.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of seconds</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_timezone" c:identifier="g_date_time_get_timezone" version="2.58">
|
|
<doc xml:space="preserve">Get the time zone for this @datetime.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the time zone</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_timezone_abbreviation" c:identifier="g_date_time_get_timezone_abbreviation" version="2.26">
|
|
<doc xml:space="preserve">Determines the time zone abbreviation to be used at the time and in
|
|
the time zone of @datetime.
|
|
|
|
For example, in Toronto this is currently "EST" during the winter
|
|
months and "EDT" during the summer months when daylight savings
|
|
time is in effect.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the time zone abbreviation. The returned
|
|
string is owned by the #GDateTime and it should not be
|
|
modified or freed</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_utc_offset" c:identifier="g_date_time_get_utc_offset" version="2.26">
|
|
<doc xml:space="preserve">Determines the offset to UTC in effect at the time and in the time
|
|
zone of @datetime.
|
|
|
|
The offset is the number of microseconds that you add to UTC time to
|
|
arrive at local time for the time zone (ie: negative numbers for time
|
|
zones west of GMT, positive numbers for east).
|
|
|
|
If @datetime represents UTC time, then the offset is always zero.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of microseconds that should be added to UTC to
|
|
get the local time</doc>
|
|
<type name="TimeSpan" c:type="GTimeSpan"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_week_numbering_year" c:identifier="g_date_time_get_week_numbering_year" version="2.26">
|
|
<doc xml:space="preserve">Returns the ISO 8601 week-numbering year in which the week containing
|
|
@datetime falls.
|
|
|
|
This function, taken together with g_date_time_get_week_of_year() and
|
|
g_date_time_get_day_of_week() can be used to determine the full ISO
|
|
week date on which @datetime falls.
|
|
|
|
This is usually equal to the normal Gregorian year (as returned by
|
|
g_date_time_get_year()), except as detailed below:
|
|
|
|
For Thursday, the week-numbering year is always equal to the usual
|
|
calendar year. For other days, the number is such that every day
|
|
within a complete week (Monday to Sunday) is contained within the
|
|
same week-numbering year.
|
|
|
|
For Monday, Tuesday and Wednesday occurring near the end of the year,
|
|
this may mean that the week-numbering year is one greater than the
|
|
calendar year (so that these days have the same week-numbering year
|
|
as the Thursday occurring early in the next year).
|
|
|
|
For Friday, Saturday and Sunday occurring near the start of the year,
|
|
this may mean that the week-numbering year is one less than the
|
|
calendar year (so that these days have the same week-numbering year
|
|
as the Thursday occurring late in the previous year).
|
|
|
|
An equivalent description is that the week-numbering year is equal to
|
|
the calendar year containing the majority of the days in the current
|
|
week (Monday to Sunday).
|
|
|
|
Note that January 1 0001 in the proleptic Gregorian calendar is a
|
|
Monday, so this function never returns 0.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the ISO 8601 week-numbering year for @datetime</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_week_of_year" c:identifier="g_date_time_get_week_of_year" version="2.26">
|
|
<doc xml:space="preserve">Returns the ISO 8601 week number for the week containing @datetime.
|
|
The ISO 8601 week number is the same for every day of the week (from
|
|
Moday through Sunday). That can produce some unusual results
|
|
(described below).
|
|
|
|
The first week of the year is week 1. This is the week that contains
|
|
the first Thursday of the year. Equivalently, this is the first week
|
|
that has more than 4 of its days falling within the calendar year.
|
|
|
|
The value 0 is never returned by this function. Days contained
|
|
within a year but occurring before the first ISO 8601 week of that
|
|
year are considered as being contained in the last week of the
|
|
previous year. Similarly, the final days of a calendar year may be
|
|
considered as being part of the first ISO 8601 week of the next year
|
|
if 4 or more days of that week are contained within the new year.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the ISO 8601 week number for @datetime.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_year" c:identifier="g_date_time_get_year" version="2.26">
|
|
<doc xml:space="preserve">Retrieves the year represented by @datetime in the Gregorian calendar.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the year represented by @datetime</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_ymd" c:identifier="g_date_time_get_ymd" version="2.26">
|
|
<doc xml:space="preserve">Retrieves the Gregorian day, month, and year of a given #GDateTime.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime.</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
<parameter name="year" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">the return location for the gregorian year, or %NULL.</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="month" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">the return location for the month of the year, or %NULL.</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="day" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">the return location for the day of the month, or %NULL.</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_daylight_savings" c:identifier="g_date_time_is_daylight_savings" version="2.26">
|
|
<doc xml:space="preserve">Determines if daylight savings time is in effect at the time and in
|
|
the time zone of @datetime.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if daylight savings time is in effect</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_date_time_ref" version="2.26">
|
|
<doc xml:space="preserve">Atomically increments the reference count of @datetime by one.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the #GDateTime with the reference count increased</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="to_local" c:identifier="g_date_time_to_local" version="2.26">
|
|
<doc xml:space="preserve">Creates a new #GDateTime corresponding to the same instant in time as
|
|
@datetime, but in the local time zone.
|
|
|
|
This call is equivalent to calling g_date_time_to_timezone() with the
|
|
time zone returned by g_time_zone_new_local().</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the newly created #GDateTime which
|
|
should be freed with g_date_time_unref(), or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="to_timeval" c:identifier="g_date_time_to_timeval" version="2.26" deprecated="1" deprecated-version="2.62">
|
|
<doc xml:space="preserve">Stores the instant in time that @datetime represents into @tv.
|
|
|
|
The time contained in a #GTimeVal is always stored in the form of
|
|
seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time
|
|
zone associated with @datetime.
|
|
|
|
On systems where 'long' is 32bit (ie: all 32bit systems and all
|
|
Windows systems), a #GTimeVal is incapable of storing the entire
|
|
range of values that #GDateTime is capable of expressing. On those
|
|
systems, this function returns %FALSE to indicate that the time is
|
|
out of range.
|
|
|
|
On systems where 'long' is 64bit, this function never fails.</doc>
|
|
<doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use
|
|
g_date_time_to_unix() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if successful, else %FALSE</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
<parameter name="tv" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeVal to modify</doc>
|
|
<type name="TimeVal" c:type="GTimeVal*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="to_timezone" c:identifier="g_date_time_to_timezone" version="2.26">
|
|
<doc xml:space="preserve">Create a new #GDateTime corresponding to the same instant in time as
|
|
@datetime, but in the time zone @tz.
|
|
|
|
This call can fail in the case that the time goes out of bounds. For
|
|
example, converting 0001-01-01 00:00:00 UTC to a time zone west of
|
|
Greenwich will fail (due to the year 0 being out of range).</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the newly created #GDateTime which
|
|
should be freed with g_date_time_unref(), or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
<parameter name="tz" transfer-ownership="none">
|
|
<doc xml:space="preserve">the new #GTimeZone</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="to_unix" c:identifier="g_date_time_to_unix" version="2.26">
|
|
<doc xml:space="preserve">Gives the Unix time corresponding to @datetime, rounding down to the
|
|
nearest second.
|
|
|
|
Unix time is the number of seconds that have elapsed since 1970-01-01
|
|
00:00:00 UTC, regardless of the time zone associated with @datetime.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the Unix time corresponding to @datetime</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="to_utc" c:identifier="g_date_time_to_utc" version="2.26">
|
|
<doc xml:space="preserve">Creates a new #GDateTime corresponding to the same instant in time as
|
|
@datetime, but in UTC.
|
|
|
|
This call is equivalent to calling g_date_time_to_timezone() with the
|
|
time zone returned by g_time_zone_new_utc().</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the newly created #GDateTime which
|
|
should be freed with g_date_time_unref(), or %NULL</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_date_time_unref" version="2.26">
|
|
<doc xml:space="preserve">Atomically decrements the reference count of @datetime by one.
|
|
|
|
When the reference count reaches zero, the resources allocated by
|
|
@datetime are freed</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="DateTime" c:type="GDateTime*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="compare" c:identifier="g_date_time_compare" version="2.26">
|
|
<doc xml:space="preserve">A comparison function for #GDateTimes that is suitable
|
|
as a #GCompareFunc. Both #GDateTimes must be non-%NULL.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">-1, 0 or 1 if @dt1 is less than, equal to or greater
|
|
than @dt2.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dt1" transfer-ownership="none">
|
|
<doc xml:space="preserve">first #GDateTime to compare</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="dt2" transfer-ownership="none">
|
|
<doc xml:space="preserve">second #GDateTime to compare</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="equal" c:identifier="g_date_time_equal" version="2.26">
|
|
<doc xml:space="preserve">Checks to see if @dt1 and @dt2 are equal.
|
|
|
|
Equal here means that they represent the same moment after converting
|
|
them to the same time zone.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @dt1 and @dt2 are equal</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dt1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="dt2" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hash" c:identifier="g_date_time_hash" version="2.26">
|
|
<doc xml:space="preserve">Hashes @datetime into a #guint, suitable for use within #GHashTable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #guint containing the hash</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<enumeration name="DateWeekday" c:type="GDateWeekday">
|
|
<doc xml:space="preserve">Enumeration representing a day of the week; #G_DATE_MONDAY,
|
|
#G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday.</doc>
|
|
<member name="bad_weekday" value="0" c:identifier="G_DATE_BAD_WEEKDAY">
|
|
<doc xml:space="preserve">invalid value</doc>
|
|
</member>
|
|
<member name="monday" value="1" c:identifier="G_DATE_MONDAY">
|
|
<doc xml:space="preserve">Monday</doc>
|
|
</member>
|
|
<member name="tuesday" value="2" c:identifier="G_DATE_TUESDAY">
|
|
<doc xml:space="preserve">Tuesday</doc>
|
|
</member>
|
|
<member name="wednesday" value="3" c:identifier="G_DATE_WEDNESDAY">
|
|
<doc xml:space="preserve">Wednesday</doc>
|
|
</member>
|
|
<member name="thursday" value="4" c:identifier="G_DATE_THURSDAY">
|
|
<doc xml:space="preserve">Thursday</doc>
|
|
</member>
|
|
<member name="friday" value="5" c:identifier="G_DATE_FRIDAY">
|
|
<doc xml:space="preserve">Friday</doc>
|
|
</member>
|
|
<member name="saturday" value="6" c:identifier="G_DATE_SATURDAY">
|
|
<doc xml:space="preserve">Saturday</doc>
|
|
</member>
|
|
<member name="sunday" value="7" c:identifier="G_DATE_SUNDAY">
|
|
<doc xml:space="preserve">Sunday</doc>
|
|
</member>
|
|
</enumeration>
|
|
<record name="DebugKey" c:type="GDebugKey">
|
|
<doc xml:space="preserve">Associates a string with a bit flag.
|
|
Used in g_parse_debug_string().</doc>
|
|
<field name="key" writable="1">
|
|
<doc xml:space="preserve">the string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</field>
|
|
<field name="value" writable="1">
|
|
<doc xml:space="preserve">the flag</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
</record>
|
|
<callback name="DestroyNotify" c:type="GDestroyNotify">
|
|
<doc xml:space="preserve">Specifies the type of function which is called when a data element
|
|
is destroyed. It is passed the pointer to the data element and
|
|
should free any memory and resources allocated for it.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data element.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<record name="Dir" c:type="GDir" disguised="1">
|
|
<doc xml:space="preserve">An opaque structure representing an opened directory.</doc>
|
|
<method name="close" c:identifier="g_dir_close">
|
|
<doc xml:space="preserve">Closes the directory and deallocates all related resources.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="dir" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDir* created by g_dir_open()</doc>
|
|
<type name="Dir" c:type="GDir*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="read_name" c:identifier="g_dir_read_name">
|
|
<doc xml:space="preserve">Retrieves the name of another entry in the directory, or %NULL.
|
|
The order of entries returned from this function is not defined,
|
|
and may vary by file system or other operating-system dependent
|
|
factors.
|
|
|
|
%NULL may also be returned in case of errors. On Unix, you can
|
|
check `errno` to find out if %NULL was returned because of an error.
|
|
|
|
On Unix, the '.' and '..' entries are omitted, and the returned
|
|
name is in the on-disk encoding.
|
|
|
|
On Windows, as is true of all GLib functions which operate on
|
|
filenames, the returned name is in UTF-8.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">The entry's name or %NULL if there are no
|
|
more entries. The return value is owned by GLib and
|
|
must not be modified or freed.</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="dir" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDir* created by g_dir_open()</doc>
|
|
<type name="Dir" c:type="GDir*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="rewind" c:identifier="g_dir_rewind">
|
|
<doc xml:space="preserve">Resets the given directory. The next call to g_dir_read_name()
|
|
will return the first entry again.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="dir" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDir* created by g_dir_open()</doc>
|
|
<type name="Dir" c:type="GDir*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="make_tmp" c:identifier="g_dir_make_tmp" version="2.30" throws="1">
|
|
<doc xml:space="preserve">Creates a subdirectory in the preferred directory for temporary
|
|
files (as returned by g_get_tmp_dir()).
|
|
|
|
@tmpl should be a string in the GLib file name encoding containing
|
|
a sequence of six 'X' characters, as the parameter to g_mkstemp().
|
|
However, unlike these functions, the template should only be a
|
|
basename, no directory components are allowed. If template is
|
|
%NULL, a default template is used.
|
|
|
|
Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not
|
|
modified, and might thus be a read-only literal string.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">The actual name used. This string
|
|
should be freed with g_free() when not needed any longer and is
|
|
is in the GLib file name encoding. In case of errors, %NULL is
|
|
returned and @error will be set.</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="tmpl" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">Template for directory name,
|
|
as in g_mkdtemp(), basename only, or %NULL for a default template</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="open" c:identifier="g_dir_open" introspectable="0" throws="1">
|
|
<doc xml:space="preserve">Opens a directory for reading. The names of the files in the
|
|
directory can then be retrieved using g_dir_read_name(). Note
|
|
that the ordering is not defined.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a newly allocated #GDir on success, %NULL on failure.
|
|
If non-%NULL, you must free the result with g_dir_close()
|
|
when you are finished with it.</doc>
|
|
<type name="Dir" c:type="GDir*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="path" transfer-ownership="none">
|
|
<doc xml:space="preserve">the path to the directory you are interested in. On Unix
|
|
in the on-disk encoding. On Windows in UTF-8</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">Currently must be set to 0. Reserved for future use.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<union name="DoubleIEEE754" c:type="GDoubleIEEE754">
|
|
<doc xml:space="preserve">The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
|
|
mantissa and exponent of IEEE floats and doubles. These unions are defined
|
|
as appropriate for a given platform. IEEE floats and doubles are supported
|
|
(used for storage) by at least Intel, PPC and Sparc.</doc>
|
|
<field name="v_double" writable="1">
|
|
<doc xml:space="preserve">the double value</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</field>
|
|
<record name="mpn" c:type="mpn">
|
|
<field name="mantissa_low" writable="1" bits="32">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="mantissa_high" writable="1" bits="20">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="biased_exponent" writable="1" bits="11">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="sign" writable="1" bits="1">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
</record>
|
|
</union>
|
|
<callback name="DuplicateFunc" c:type="GDuplicateFunc">
|
|
<doc xml:space="preserve">The type of functions that are used to 'duplicate' an object.
|
|
What this means depends on the context, it could just be
|
|
incrementing the reference count, if @data is a ref-counted
|
|
object.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">a duplicate of data</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to duplicate</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="1">
|
|
<doc xml:space="preserve">user data that was specified in
|
|
g_datalist_id_dup_data()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<constant name="E" value="2.718282" c:type="G_E">
|
|
<doc xml:space="preserve">The base of natural logarithms.</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</constant>
|
|
<function-macro name="ENCODE_VERSION" c:identifier="G_ENCODE_VERSION" introspectable="0">
|
|
<parameters>
|
|
<parameter name="major">
|
|
</parameter>
|
|
<parameter name="minor">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<callback name="EqualFunc" c:type="GEqualFunc">
|
|
<doc xml:space="preserve">Specifies the type of a function used to test two values for
|
|
equality. The function should return %TRUE if both values are equal
|
|
and %FALSE otherwise.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @a = @b; %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="a" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a value</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="b" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a value to compare with</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<record name="Error" c:type="GError" glib:type-name="GError" glib:get-type="g_error_get_type" c:symbol-prefix="error">
|
|
<doc xml:space="preserve">The `GError` structure contains information about
|
|
an error that has occurred.</doc>
|
|
<field name="domain" writable="1">
|
|
<doc xml:space="preserve">error domain, e.g. #G_FILE_ERROR</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</field>
|
|
<field name="code" writable="1">
|
|
<doc xml:space="preserve">error code, e.g. %G_FILE_ERROR_NOENT</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</field>
|
|
<field name="message" writable="1">
|
|
<doc xml:space="preserve">human-readable informative error message</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</field>
|
|
<constructor name="new" c:identifier="g_error_new" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GError with the given @domain and @code,
|
|
and a message formatted with @format.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GError</doc>
|
|
<type name="Error" c:type="GError*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="domain" transfer-ownership="none">
|
|
<doc xml:space="preserve">error domain</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</parameter>
|
|
<parameter name="code" transfer-ownership="none">
|
|
<doc xml:space="preserve">error code</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">printf()-style format for error message</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">parameters for message format</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_literal" c:identifier="g_error_new_literal">
|
|
<doc xml:space="preserve">Creates a new #GError; unlike g_error_new(), @message is
|
|
not a printf()-style format string. Use this function if
|
|
@message contains text you don't have control over,
|
|
that could include printf() escape sequences.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GError</doc>
|
|
<type name="Error" c:type="GError*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="domain" transfer-ownership="none">
|
|
<doc xml:space="preserve">error domain</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</parameter>
|
|
<parameter name="code" transfer-ownership="none">
|
|
<doc xml:space="preserve">error code</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="message" transfer-ownership="none">
|
|
<doc xml:space="preserve">error message</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_valist" c:identifier="g_error_new_valist" version="2.22" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GError with the given @domain and @code,
|
|
and a message formatted with @format.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GError</doc>
|
|
<type name="Error" c:type="GError*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="domain" transfer-ownership="none">
|
|
<doc xml:space="preserve">error domain</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</parameter>
|
|
<parameter name="code" transfer-ownership="none">
|
|
<doc xml:space="preserve">error code</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">printf()-style format for error message</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="args" transfer-ownership="none">
|
|
<doc xml:space="preserve">#va_list of parameters for the message format</doc>
|
|
<type name="va_list" c:type="va_list"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<method name="copy" c:identifier="g_error_copy">
|
|
<doc xml:space="preserve">Makes a copy of @error.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GError</doc>
|
|
<type name="Error" c:type="GError*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="error" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GError</doc>
|
|
<type name="Error" c:type="const GError*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free" c:identifier="g_error_free">
|
|
<doc xml:space="preserve">Frees a #GError and associated resources.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="error" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GError</doc>
|
|
<type name="Error" c:type="GError*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="matches" c:identifier="g_error_matches">
|
|
<doc xml:space="preserve">Returns %TRUE if @error matches @domain and @code, %FALSE
|
|
otherwise. In particular, when @error is %NULL, %FALSE will
|
|
be returned.
|
|
|
|
If @domain contains a `FAILED` (or otherwise generic) error code,
|
|
you should generally not check for it explicitly, but should
|
|
instead treat any not-explicitly-recognized error code as being
|
|
equivalent to the `FAILED` code. This way, if the domain is
|
|
extended in the future to provide a more specific error code for
|
|
a certain case, your code will still work.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">whether @error has @domain and @code</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="error" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GError</doc>
|
|
<type name="Error" c:type="const GError*"/>
|
|
</instance-parameter>
|
|
<parameter name="domain" transfer-ownership="none">
|
|
<doc xml:space="preserve">an error domain</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</parameter>
|
|
<parameter name="code" transfer-ownership="none">
|
|
<doc xml:space="preserve">an error code</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<enumeration name="ErrorType" c:type="GErrorType">
|
|
<doc xml:space="preserve">The possible errors, used in the @v_error field
|
|
of #GTokenValue, when the token is a %G_TOKEN_ERROR.</doc>
|
|
<member name="unknown" value="0" c:identifier="G_ERR_UNKNOWN">
|
|
<doc xml:space="preserve">unknown error</doc>
|
|
</member>
|
|
<member name="unexp_eof" value="1" c:identifier="G_ERR_UNEXP_EOF">
|
|
<doc xml:space="preserve">unexpected end of file</doc>
|
|
</member>
|
|
<member name="unexp_eof_in_string" value="2" c:identifier="G_ERR_UNEXP_EOF_IN_STRING">
|
|
<doc xml:space="preserve">unterminated string constant</doc>
|
|
</member>
|
|
<member name="unexp_eof_in_comment" value="3" c:identifier="G_ERR_UNEXP_EOF_IN_COMMENT">
|
|
<doc xml:space="preserve">unterminated comment</doc>
|
|
</member>
|
|
<member name="non_digit_in_const" value="4" c:identifier="G_ERR_NON_DIGIT_IN_CONST">
|
|
<doc xml:space="preserve">non-digit character in a number</doc>
|
|
</member>
|
|
<member name="digit_radix" value="5" c:identifier="G_ERR_DIGIT_RADIX">
|
|
<doc xml:space="preserve">digit beyond radix in a number</doc>
|
|
</member>
|
|
<member name="float_radix" value="6" c:identifier="G_ERR_FLOAT_RADIX">
|
|
<doc xml:space="preserve">non-decimal floating point number</doc>
|
|
</member>
|
|
<member name="float_malformed" value="7" c:identifier="G_ERR_FLOAT_MALFORMED">
|
|
<doc xml:space="preserve">malformed floating point number</doc>
|
|
</member>
|
|
</enumeration>
|
|
<enumeration name="FileError" c:type="GFileError" glib:error-domain="g-file-error-quark">
|
|
<doc xml:space="preserve">Values corresponding to @errno codes returned from file operations
|
|
on UNIX. Unlike @errno codes, GFileError values are available on
|
|
all systems, even Windows. The exact meaning of each code depends
|
|
on what sort of file operation you were performing; the UNIX
|
|
documentation gives more details. The following error code descriptions
|
|
come from the GNU C Library manual, and are under the copyright
|
|
of that manual.
|
|
|
|
It's not very portable to make detailed assumptions about exactly
|
|
which errors will be returned from a given operation. Some errors
|
|
don't occur on some systems, etc., sometimes there are subtle
|
|
differences in when a system will report a given error, etc.</doc>
|
|
<member name="exist" value="0" c:identifier="G_FILE_ERROR_EXIST">
|
|
<doc xml:space="preserve">Operation not permitted; only the owner of
|
|
the file (or other resource) or processes with special privileges
|
|
can perform the operation.</doc>
|
|
</member>
|
|
<member name="isdir" value="1" c:identifier="G_FILE_ERROR_ISDIR">
|
|
<doc xml:space="preserve">File is a directory; you cannot open a directory
|
|
for writing, or create or remove hard links to it.</doc>
|
|
</member>
|
|
<member name="acces" value="2" c:identifier="G_FILE_ERROR_ACCES">
|
|
<doc xml:space="preserve">Permission denied; the file permissions do not
|
|
allow the attempted operation.</doc>
|
|
</member>
|
|
<member name="nametoolong" value="3" c:identifier="G_FILE_ERROR_NAMETOOLONG">
|
|
<doc xml:space="preserve">Filename too long.</doc>
|
|
</member>
|
|
<member name="noent" value="4" c:identifier="G_FILE_ERROR_NOENT">
|
|
<doc xml:space="preserve">No such file or directory. This is a "file
|
|
doesn't exist" error for ordinary files that are referenced in
|
|
contexts where they are expected to already exist.</doc>
|
|
</member>
|
|
<member name="notdir" value="5" c:identifier="G_FILE_ERROR_NOTDIR">
|
|
<doc xml:space="preserve">A file that isn't a directory was specified when
|
|
a directory is required.</doc>
|
|
</member>
|
|
<member name="nxio" value="6" c:identifier="G_FILE_ERROR_NXIO">
|
|
<doc xml:space="preserve">No such device or address. The system tried to
|
|
use the device represented by a file you specified, and it
|
|
couldn't find the device. This can mean that the device file was
|
|
installed incorrectly, or that the physical device is missing or
|
|
not correctly attached to the computer.</doc>
|
|
</member>
|
|
<member name="nodev" value="7" c:identifier="G_FILE_ERROR_NODEV">
|
|
<doc xml:space="preserve">The underlying file system of the specified file
|
|
does not support memory mapping.</doc>
|
|
</member>
|
|
<member name="rofs" value="8" c:identifier="G_FILE_ERROR_ROFS">
|
|
<doc xml:space="preserve">The directory containing the new link can't be
|
|
modified because it's on a read-only file system.</doc>
|
|
</member>
|
|
<member name="txtbsy" value="9" c:identifier="G_FILE_ERROR_TXTBSY">
|
|
<doc xml:space="preserve">Text file busy.</doc>
|
|
</member>
|
|
<member name="fault" value="10" c:identifier="G_FILE_ERROR_FAULT">
|
|
<doc xml:space="preserve">You passed in a pointer to bad memory.
|
|
(GLib won't reliably return this, don't pass in pointers to bad
|
|
memory.)</doc>
|
|
</member>
|
|
<member name="loop" value="11" c:identifier="G_FILE_ERROR_LOOP">
|
|
<doc xml:space="preserve">Too many levels of symbolic links were encountered
|
|
in looking up a file name. This often indicates a cycle of symbolic
|
|
links.</doc>
|
|
</member>
|
|
<member name="nospc" value="12" c:identifier="G_FILE_ERROR_NOSPC">
|
|
<doc xml:space="preserve">No space left on device; write operation on a
|
|
file failed because the disk is full.</doc>
|
|
</member>
|
|
<member name="nomem" value="13" c:identifier="G_FILE_ERROR_NOMEM">
|
|
<doc xml:space="preserve">No memory available. The system cannot allocate
|
|
more virtual memory because its capacity is full.</doc>
|
|
</member>
|
|
<member name="mfile" value="14" c:identifier="G_FILE_ERROR_MFILE">
|
|
<doc xml:space="preserve">The current process has too many files open and
|
|
can't open any more. Duplicate descriptors do count toward this
|
|
limit.</doc>
|
|
</member>
|
|
<member name="nfile" value="15" c:identifier="G_FILE_ERROR_NFILE">
|
|
<doc xml:space="preserve">There are too many distinct file openings in the
|
|
entire system.</doc>
|
|
</member>
|
|
<member name="badf" value="16" c:identifier="G_FILE_ERROR_BADF">
|
|
<doc xml:space="preserve">Bad file descriptor; for example, I/O on a
|
|
descriptor that has been closed or reading from a descriptor open
|
|
only for writing (or vice versa).</doc>
|
|
</member>
|
|
<member name="inval" value="17" c:identifier="G_FILE_ERROR_INVAL">
|
|
<doc xml:space="preserve">Invalid argument. This is used to indicate
|
|
various kinds of problems with passing the wrong argument to a
|
|
library function.</doc>
|
|
</member>
|
|
<member name="pipe" value="18" c:identifier="G_FILE_ERROR_PIPE">
|
|
<doc xml:space="preserve">Broken pipe; there is no process reading from the
|
|
other end of a pipe. Every library function that returns this
|
|
error code also generates a 'SIGPIPE' signal; this signal
|
|
terminates the program if not handled or blocked. Thus, your
|
|
program will never actually see this code unless it has handled
|
|
or blocked 'SIGPIPE'.</doc>
|
|
</member>
|
|
<member name="again" value="19" c:identifier="G_FILE_ERROR_AGAIN">
|
|
<doc xml:space="preserve">Resource temporarily unavailable; the call might
|
|
work if you try again later.</doc>
|
|
</member>
|
|
<member name="intr" value="20" c:identifier="G_FILE_ERROR_INTR">
|
|
<doc xml:space="preserve">Interrupted function call; an asynchronous signal
|
|
occurred and prevented completion of the call. When this
|
|
happens, you should try the call again.</doc>
|
|
</member>
|
|
<member name="io" value="21" c:identifier="G_FILE_ERROR_IO">
|
|
<doc xml:space="preserve">Input/output error; usually used for physical read
|
|
or write errors. i.e. the disk or other physical device hardware
|
|
is returning errors.</doc>
|
|
</member>
|
|
<member name="perm" value="22" c:identifier="G_FILE_ERROR_PERM">
|
|
<doc xml:space="preserve">Operation not permitted; only the owner of the
|
|
file (or other resource) or processes with special privileges can
|
|
perform the operation.</doc>
|
|
</member>
|
|
<member name="nosys" value="23" c:identifier="G_FILE_ERROR_NOSYS">
|
|
<doc xml:space="preserve">Function not implemented; this indicates that
|
|
the system is missing some functionality.</doc>
|
|
</member>
|
|
<member name="failed" value="24" c:identifier="G_FILE_ERROR_FAILED">
|
|
<doc xml:space="preserve">Does not correspond to a UNIX error code; this
|
|
is the standard "failed for unspecified reason" error code present
|
|
in all #GError error code enumerations. Returned if no specific
|
|
code applies.</doc>
|
|
</member>
|
|
</enumeration>
|
|
<bitfield name="FileSetContentsFlags" version="2.66" c:type="GFileSetContentsFlags">
|
|
<doc xml:space="preserve">Flags to pass to g_file_set_contents_full() to affect its safety and
|
|
performance.</doc>
|
|
<member name="none" value="0" c:identifier="G_FILE_SET_CONTENTS_NONE">
|
|
<doc xml:space="preserve">No guarantees about file consistency or durability.
|
|
The most dangerous setting, which is slightly faster than other settings.</doc>
|
|
</member>
|
|
<member name="consistent" value="1" c:identifier="G_FILE_SET_CONTENTS_CONSISTENT">
|
|
<doc xml:space="preserve">Guarantee file consistency: after a crash,
|
|
either the old version of the file or the new version of the file will be
|
|
available, but not a mixture. On Unix systems this equates to an `fsync()`
|
|
on the file and use of an atomic `rename()` of the new version of the file
|
|
over the old.</doc>
|
|
</member>
|
|
<member name="durable" value="2" c:identifier="G_FILE_SET_CONTENTS_DURABLE">
|
|
<doc xml:space="preserve">Guarantee file durability: after a crash, the
|
|
new version of the file will be available. On Unix systems this equates to
|
|
an `fsync()` on the file (if %G_FILE_SET_CONTENTS_CONSISTENT is unset), or
|
|
the effects of %G_FILE_SET_CONTENTS_CONSISTENT plus an `fsync()` on the
|
|
directory containing the file after calling `rename()`.</doc>
|
|
</member>
|
|
<member name="only_existing" value="4" c:identifier="G_FILE_SET_CONTENTS_ONLY_EXISTING">
|
|
<doc xml:space="preserve">Only apply consistency and durability
|
|
guarantees if the file already exists. This may speed up file operations
|
|
if the file doesn’t currently exist, but may result in a corrupted version
|
|
of the new file if the system crashes while writing it.</doc>
|
|
</member>
|
|
</bitfield>
|
|
<bitfield name="FileTest" c:type="GFileTest">
|
|
<doc xml:space="preserve">A test to perform on a file using g_file_test().</doc>
|
|
<member name="is_regular" value="1" c:identifier="G_FILE_TEST_IS_REGULAR">
|
|
<doc xml:space="preserve">%TRUE if the file is a regular file
|
|
(not a directory). Note that this test will also return %TRUE
|
|
if the tested file is a symlink to a regular file.</doc>
|
|
</member>
|
|
<member name="is_symlink" value="2" c:identifier="G_FILE_TEST_IS_SYMLINK">
|
|
<doc xml:space="preserve">%TRUE if the file is a symlink.</doc>
|
|
</member>
|
|
<member name="is_dir" value="4" c:identifier="G_FILE_TEST_IS_DIR">
|
|
<doc xml:space="preserve">%TRUE if the file is a directory.</doc>
|
|
</member>
|
|
<member name="is_executable" value="8" c:identifier="G_FILE_TEST_IS_EXECUTABLE">
|
|
<doc xml:space="preserve">%TRUE if the file is executable.</doc>
|
|
</member>
|
|
<member name="exists" value="16" c:identifier="G_FILE_TEST_EXISTS">
|
|
<doc xml:space="preserve">%TRUE if the file exists. It may or may not
|
|
be a regular file.</doc>
|
|
</member>
|
|
</bitfield>
|
|
<union name="FloatIEEE754" c:type="GFloatIEEE754">
|
|
<doc xml:space="preserve">The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign,
|
|
mantissa and exponent of IEEE floats and doubles. These unions are defined
|
|
as appropriate for a given platform. IEEE floats and doubles are supported
|
|
(used for storage) by at least Intel, PPC and Sparc.</doc>
|
|
<field name="v_float" writable="1">
|
|
<doc xml:space="preserve">the double value</doc>
|
|
<type name="gfloat" c:type="gfloat"/>
|
|
</field>
|
|
<record name="mpn" c:type="mpn">
|
|
<field name="mantissa" writable="1" bits="23">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="biased_exponent" writable="1" bits="8">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="sign" writable="1" bits="1">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
</record>
|
|
</union>
|
|
<bitfield name="FormatSizeFlags" c:type="GFormatSizeFlags">
|
|
<doc xml:space="preserve">Flags to modify the format of the string returned by g_format_size_full().</doc>
|
|
<member name="default" value="0" c:identifier="G_FORMAT_SIZE_DEFAULT">
|
|
<doc xml:space="preserve">behave the same as g_format_size()</doc>
|
|
</member>
|
|
<member name="long_format" value="1" c:identifier="G_FORMAT_SIZE_LONG_FORMAT">
|
|
<doc xml:space="preserve">include the exact number of bytes as part
|
|
of the returned string. For example, "45.6 kB (45,612 bytes)".</doc>
|
|
</member>
|
|
<member name="iec_units" value="2" c:identifier="G_FORMAT_SIZE_IEC_UNITS">
|
|
<doc xml:space="preserve">use IEC (base 1024) units with "KiB"-style
|
|
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.</doc>
|
|
</member>
|
|
<member name="bits" value="4" c:identifier="G_FORMAT_SIZE_BITS">
|
|
<doc xml:space="preserve">set the size as a quantity in bits, rather than
|
|
bytes, and return units in bits. For example, ‘Mb’ rather than ‘MB’.</doc>
|
|
</member>
|
|
</bitfield>
|
|
<callback name="FreeFunc" c:type="GFreeFunc">
|
|
<doc xml:space="preserve">Declares a type of function which takes an arbitrary
|
|
data pointer argument and has no return value. It is
|
|
not currently used in GLib or GTK+.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a data pointer</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<callback name="Func" c:type="GFunc">
|
|
<doc xml:space="preserve">Specifies the type of functions passed to g_list_foreach() and
|
|
g_slist_foreach().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the element's data</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="1">
|
|
<doc xml:space="preserve">user data passed to g_list_foreach() or g_slist_foreach()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<constant name="GINT16_FORMAT" value="hi" c:type="G_GINT16_FORMAT">
|
|
<doc xml:space="preserve">This is the platform dependent conversion specifier for scanning and
|
|
printing values of type #gint16. It is a string literal, but doesn't
|
|
include the percent-sign, such that you can add precision and length
|
|
modifiers between percent-sign and conversion specifier.
|
|
|
|
|[<!-- language="C" -->
|
|
gint16 in;
|
|
gint32 out;
|
|
sscanf ("42", "%" G_GINT16_FORMAT, &in)
|
|
out = in * 1000;
|
|
g_print ("%" G_GINT32_FORMAT, out);
|
|
]|</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="GINT16_MODIFIER" value="h" c:type="G_GINT16_MODIFIER" version="2.4">
|
|
<doc xml:space="preserve">The platform dependent length modifier for conversion specifiers
|
|
for scanning and printing values of type #gint16 or #guint16. It
|
|
is a string literal, but doesn't include the percent-sign, such
|
|
that you can add precision and length modifiers between percent-sign
|
|
and conversion specifier and append a conversion specifier.
|
|
|
|
The following example prints "0x7b";
|
|
|[<!-- language="C" -->
|
|
gint16 value = 123;
|
|
g_print ("%#" G_GINT16_MODIFIER "x", value);
|
|
]|</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="GINT32_FORMAT" value="i" c:type="G_GINT32_FORMAT">
|
|
<doc xml:space="preserve">This is the platform dependent conversion specifier for scanning
|
|
and printing values of type #gint32. See also #G_GINT16_FORMAT.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="GINT32_MODIFIER" value="" c:type="G_GINT32_MODIFIER" version="2.4">
|
|
<doc xml:space="preserve">The platform dependent length modifier for conversion specifiers
|
|
for scanning and printing values of type #gint32 or #guint32. It
|
|
is a string literal. See also #G_GINT16_MODIFIER.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<function-macro name="GINT64_CONSTANT" c:identifier="G_GINT64_CONSTANT" introspectable="0">
|
|
<doc xml:space="preserve">This macro is used to insert 64-bit integer literals
|
|
into the source code.</doc>
|
|
<parameters>
|
|
<parameter name="val">
|
|
<doc xml:space="preserve">a literal integer value, e.g. 0x1d636b02300a7aa7</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="GINT64_FORMAT" value="li" c:type="G_GINT64_FORMAT">
|
|
<doc xml:space="preserve">This is the platform dependent conversion specifier for scanning
|
|
and printing values of type #gint64. See also #G_GINT16_FORMAT.
|
|
|
|
Some platforms do not support scanning and printing 64-bit integers,
|
|
even though the types are supported. On such platforms %G_GINT64_FORMAT
|
|
is not defined. Note that scanf() may not support 64-bit integers, even
|
|
if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
|
|
is not recommended for parsing anyway; consider using g_ascii_strtoull()
|
|
instead.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="GINT64_MODIFIER" value="l" c:type="G_GINT64_MODIFIER" version="2.4">
|
|
<doc xml:space="preserve">The platform dependent length modifier for conversion specifiers
|
|
for scanning and printing values of type #gint64 or #guint64.
|
|
It is a string literal.
|
|
|
|
Some platforms do not support printing 64-bit integers, even
|
|
though the types are supported. On such platforms %G_GINT64_MODIFIER
|
|
is not defined.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="GINTPTR_FORMAT" value="li" c:type="G_GINTPTR_FORMAT" version="2.22">
|
|
<doc xml:space="preserve">This is the platform dependent conversion specifier for scanning
|
|
and printing values of type #gintptr.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="GINTPTR_MODIFIER" value="l" c:type="G_GINTPTR_MODIFIER" version="2.22">
|
|
<doc xml:space="preserve">The platform dependent length modifier for conversion specifiers
|
|
for scanning and printing values of type #gintptr or #guintptr.
|
|
It is a string literal.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<function-macro name="GNUC_ALLOC_SIZE" c:identifier="G_GNUC_ALLOC_SIZE" version="2.18" introspectable="0">
|
|
<doc xml:space="preserve">Expands to the GNU C `alloc_size` function attribute if the compiler
|
|
is a new enough gcc. This attribute tells the compiler that the
|
|
function returns a pointer to memory of a size that is specified
|
|
by the @xth function parameter.
|
|
|
|
Place the attribute after the function declaration, just before the
|
|
semicolon.
|
|
|
|
|[<!-- language="C" -->
|
|
gpointer g_malloc (gsize n_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE(1);
|
|
]|
|
|
|
|
See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details.</doc>
|
|
<parameters>
|
|
<parameter name="x">
|
|
<doc xml:space="preserve">the index of the argument specifying the allocation size</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="GNUC_ALLOC_SIZE2" c:identifier="G_GNUC_ALLOC_SIZE2" version="2.18" introspectable="0">
|
|
<doc xml:space="preserve">Expands to the GNU C `alloc_size` function attribute if the compiler is a
|
|
new enough gcc. This attribute tells the compiler that the function returns
|
|
a pointer to memory of a size that is specified by the product of two
|
|
function parameters.
|
|
|
|
Place the attribute after the function declaration, just before the
|
|
semicolon.
|
|
|
|
|[<!-- language="C" -->
|
|
gpointer g_malloc_n (gsize n_blocks,
|
|
gsize n_block_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE2(1, 2);
|
|
]|
|
|
|
|
See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details.</doc>
|
|
<parameters>
|
|
<parameter name="x">
|
|
<doc xml:space="preserve">the index of the argument specifying one factor of the allocation size</doc>
|
|
</parameter>
|
|
<parameter name="y">
|
|
<doc xml:space="preserve">the index of the argument specifying the second factor of the allocation size</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="GNUC_CHECK_VERSION" c:identifier="G_GNUC_CHECK_VERSION" version="2.42" introspectable="0">
|
|
<doc xml:space="preserve">Expands to a check for a compiler with __GNUC__ defined and a version
|
|
greater than or equal to the major and minor numbers provided. For example,
|
|
the following would only match on compilers such as GCC 4.8 or newer.
|
|
|
|
|[<!-- language="C" -->
|
|
#if G_GNUC_CHECK_VERSION(4, 8)
|
|
#endif
|
|
]|</doc>
|
|
<parameters>
|
|
<parameter name="major">
|
|
<doc xml:space="preserve">major version to check against</doc>
|
|
</parameter>
|
|
<parameter name="minor">
|
|
<doc xml:space="preserve">minor version to check against</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="GNUC_DEPRECATED_FOR" c:identifier="G_GNUC_DEPRECATED_FOR" version="2.26" introspectable="0">
|
|
<doc xml:space="preserve">Like %G_GNUC_DEPRECATED, but names the intended replacement for the
|
|
deprecated symbol if the version of gcc in use is new enough to support
|
|
custom deprecation messages.
|
|
|
|
Place the attribute after the declaration, just before the semicolon.
|
|
|
|
|[<!-- language="C" -->
|
|
int my_mistake (void) G_GNUC_DEPRECATED_FOR(my_replacement);
|
|
]|
|
|
|
|
See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-deprecated-function-attribute) for more details.
|
|
|
|
Note that if @f is a macro, it will be expanded in the warning message.
|
|
You can enclose it in quotes to prevent this. (The quotes will show up
|
|
in the warning, but it's better than showing the macro expansion.)</doc>
|
|
<parameters>
|
|
<parameter name="f">
|
|
<doc xml:space="preserve">the intended replacement for the deprecated symbol,
|
|
such as the name of a function</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="GNUC_FORMAT" c:identifier="G_GNUC_FORMAT" introspectable="0">
|
|
<doc xml:space="preserve">Expands to the GNU C `format_arg` function attribute if the compiler
|
|
is gcc. This function attribute specifies that a function takes a
|
|
format string for a `printf()`, `scanf()`, `strftime()` or `strfmon()` style
|
|
function and modifies it, so that the result can be passed to a `printf()`,
|
|
`scanf()`, `strftime()` or `strfmon()` style function (with the remaining
|
|
arguments to the format function the same as they would have been
|
|
for the unmodified string).
|
|
|
|
Place the attribute after the function declaration, just before the
|
|
semicolon.
|
|
|
|
See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-nonliteral-1) for more details.
|
|
|
|
|[<!-- language="C" -->
|
|
gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
|
|
]|</doc>
|
|
<parameters>
|
|
<parameter name="arg_idx">
|
|
<doc xml:space="preserve">the index of the argument</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="GNUC_FUNCTION" value="" c:type="G_GNUC_FUNCTION" deprecated="1" deprecated-version="2.16">
|
|
<doc xml:space="preserve">Expands to "" on all modern compilers, and to __FUNCTION__ on gcc
|
|
version 2.x. Don't use it.</doc>
|
|
<doc-deprecated xml:space="preserve">Use G_STRFUNC() instead</doc-deprecated>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="GNUC_PRETTY_FUNCTION" value="" c:type="G_GNUC_PRETTY_FUNCTION" deprecated="1" deprecated-version="2.16">
|
|
<doc xml:space="preserve">Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__
|
|
on gcc version 2.x. Don't use it.</doc>
|
|
<doc-deprecated xml:space="preserve">Use G_STRFUNC() instead</doc-deprecated>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<function-macro name="GNUC_PRINTF" c:identifier="G_GNUC_PRINTF" introspectable="0">
|
|
<doc xml:space="preserve">Expands to the GNU C `format` function attribute if the compiler is gcc.
|
|
This is used for declaring functions which take a variable number of
|
|
arguments, with the same syntax as `printf()`. It allows the compiler
|
|
to type-check the arguments passed to the function.
|
|
|
|
Place the attribute after the function declaration, just before the
|
|
semicolon.
|
|
|
|
See the
|
|
[GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
|
|
for more details.
|
|
|
|
|[<!-- language="C" -->
|
|
gint g_snprintf (gchar *string,
|
|
gulong n,
|
|
gchar const *format,
|
|
...) G_GNUC_PRINTF (3, 4);
|
|
]|</doc>
|
|
<parameters>
|
|
<parameter name="format_idx">
|
|
<doc xml:space="preserve">the index of the argument corresponding to the
|
|
format string (the arguments are numbered from 1)</doc>
|
|
</parameter>
|
|
<parameter name="arg_idx">
|
|
<doc xml:space="preserve">the index of the first of the format arguments, or 0 if
|
|
there are no format arguments</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="GNUC_SCANF" c:identifier="G_GNUC_SCANF" introspectable="0">
|
|
<doc xml:space="preserve">Expands to the GNU C `format` function attribute if the compiler is gcc.
|
|
This is used for declaring functions which take a variable number of
|
|
arguments, with the same syntax as `scanf()`. It allows the compiler
|
|
to type-check the arguments passed to the function.
|
|
|
|
|[<!-- language="C" -->
|
|
int my_scanf (MyStream *stream,
|
|
const char *format,
|
|
...) G_GNUC_SCANF (2, 3);
|
|
int my_vscanf (MyStream *stream,
|
|
const char *format,
|
|
va_list ap) G_GNUC_SCANF (2, 0);
|
|
]|
|
|
|
|
See the
|
|
[GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
|
|
for details.</doc>
|
|
<parameters>
|
|
<parameter name="format_idx">
|
|
<doc xml:space="preserve">the index of the argument corresponding to
|
|
the format string (the arguments are numbered from 1)</doc>
|
|
</parameter>
|
|
<parameter name="arg_idx">
|
|
<doc xml:space="preserve">the index of the first of the format arguments, or 0 if
|
|
there are no format arguments</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="GNUC_STRFTIME" c:identifier="G_GNUC_STRFTIME" version="2.60" introspectable="0">
|
|
<doc xml:space="preserve">Expands to the GNU C `strftime` format function attribute if the compiler
|
|
is gcc. This is used for declaring functions which take a format argument
|
|
which is passed to `strftime()` or an API implementing its formats. It allows
|
|
the compiler check the format passed to the function.
|
|
|
|
|[<!-- language="C" -->
|
|
gsize my_strftime (MyBuffer *buffer,
|
|
const char *format,
|
|
const struct tm *tm) G_GNUC_STRFTIME (2);
|
|
]|
|
|
|
|
See the
|
|
[GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
|
|
for details.</doc>
|
|
<parameters>
|
|
<parameter name="format_idx">
|
|
<doc xml:space="preserve">the index of the argument corresponding to
|
|
the format string (the arguments are numbered from 1)</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="GOFFSET_CONSTANT" c:identifier="G_GOFFSET_CONSTANT" version="2.20" introspectable="0">
|
|
<doc xml:space="preserve">This macro is used to insert #goffset 64-bit integer literals
|
|
into the source code.
|
|
|
|
See also #G_GINT64_CONSTANT.</doc>
|
|
<parameters>
|
|
<parameter name="val">
|
|
<doc xml:space="preserve">a literal integer value, e.g. 0x1d636b02300a7aa7</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="GSIZE_FORMAT" value="lu" c:type="G_GSIZE_FORMAT" version="2.6">
|
|
<doc xml:space="preserve">This is the platform dependent conversion specifier for scanning
|
|
and printing values of type #gsize. See also #G_GINT16_FORMAT.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="GSIZE_MODIFIER" value="l" c:type="G_GSIZE_MODIFIER" version="2.6">
|
|
<doc xml:space="preserve">The platform dependent length modifier for conversion specifiers
|
|
for scanning and printing values of type #gsize. It
|
|
is a string literal.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="GSSIZE_FORMAT" value="li" c:type="G_GSSIZE_FORMAT" version="2.6">
|
|
<doc xml:space="preserve">This is the platform dependent conversion specifier for scanning
|
|
and printing values of type #gssize. See also #G_GINT16_FORMAT.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="GSSIZE_MODIFIER" value="l" c:type="G_GSSIZE_MODIFIER" version="2.6">
|
|
<doc xml:space="preserve">The platform dependent length modifier for conversion specifiers
|
|
for scanning and printing values of type #gssize. It
|
|
is a string literal.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="GUINT16_FORMAT" value="hu" c:type="G_GUINT16_FORMAT">
|
|
<doc xml:space="preserve">This is the platform dependent conversion specifier for scanning
|
|
and printing values of type #guint16. See also #G_GINT16_FORMAT</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="GUINT32_FORMAT" value="u" c:type="G_GUINT32_FORMAT">
|
|
<doc xml:space="preserve">This is the platform dependent conversion specifier for scanning
|
|
and printing values of type #guint32. See also #G_GINT16_FORMAT.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<function-macro name="GUINT64_CONSTANT" c:identifier="G_GUINT64_CONSTANT" version="2.10" introspectable="0">
|
|
<doc xml:space="preserve">This macro is used to insert 64-bit unsigned integer
|
|
literals into the source code.</doc>
|
|
<parameters>
|
|
<parameter name="val">
|
|
<doc xml:space="preserve">a literal integer value, e.g. 0x1d636b02300a7aa7U</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="GUINT64_FORMAT" value="lu" c:type="G_GUINT64_FORMAT">
|
|
<doc xml:space="preserve">This is the platform dependent conversion specifier for scanning
|
|
and printing values of type #guint64. See also #G_GINT16_FORMAT.
|
|
|
|
Some platforms do not support scanning and printing 64-bit integers,
|
|
even though the types are supported. On such platforms %G_GUINT64_FORMAT
|
|
is not defined. Note that scanf() may not support 64-bit integers, even
|
|
if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
|
|
is not recommended for parsing anyway; consider using g_ascii_strtoull()
|
|
instead.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="GUINTPTR_FORMAT" value="lu" c:type="G_GUINTPTR_FORMAT" version="2.22">
|
|
<doc xml:space="preserve">This is the platform dependent conversion specifier
|
|
for scanning and printing values of type #guintptr.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="HAVE_GINT64" value="1" c:type="G_HAVE_GINT64">
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="HAVE_GNUC_VARARGS" value="1" c:type="G_HAVE_GNUC_VARARGS">
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="HAVE_GNUC_VISIBILITY" value="1" c:type="G_HAVE_GNUC_VISIBILITY">
|
|
<doc xml:space="preserve">Defined to 1 if gcc-style visibility handling is supported.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="HAVE_GROWING_STACK" value="0" c:type="G_HAVE_GROWING_STACK">
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="HAVE_ISO_VARARGS" value="1" c:type="G_HAVE_ISO_VARARGS">
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<callback name="HFunc" c:type="GHFunc">
|
|
<doc xml:space="preserve">Specifies the type of the function passed to g_hash_table_foreach().
|
|
It is called with each key/value pair, together with the @user_data
|
|
parameter which is passed to g_hash_table_foreach().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the value corresponding to the key</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2">
|
|
<doc xml:space="preserve">user data passed to g_hash_table_foreach()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<function-macro name="HOOK" c:identifier="G_HOOK" introspectable="0">
|
|
<doc xml:space="preserve">Casts a pointer to a `GHook*`.</doc>
|
|
<parameters>
|
|
<parameter name="hook">
|
|
<doc xml:space="preserve">a pointer</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="HOOK_ACTIVE" c:identifier="G_HOOK_ACTIVE" introspectable="0">
|
|
<doc xml:space="preserve">Returns %TRUE if the #GHook is active, which is normally the case
|
|
until the #GHook is destroyed.</doc>
|
|
<parameters>
|
|
<parameter name="hook">
|
|
<doc xml:space="preserve">a #GHook</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="HOOK_FLAGS" c:identifier="G_HOOK_FLAGS" introspectable="0">
|
|
<doc xml:space="preserve">Gets the flags of a hook.</doc>
|
|
<parameters>
|
|
<parameter name="hook">
|
|
<doc xml:space="preserve">a #GHook</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="HOOK_FLAG_USER_SHIFT" value="4" c:type="G_HOOK_FLAG_USER_SHIFT">
|
|
<doc xml:space="preserve">The position of the first bit which is not reserved for internal
|
|
use be the #GHook implementation, i.e.
|
|
`1 << G_HOOK_FLAG_USER_SHIFT` is the first
|
|
bit which can be used for application-defined flags.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<function-macro name="HOOK_IN_CALL" c:identifier="G_HOOK_IN_CALL" introspectable="0">
|
|
<doc xml:space="preserve">Returns %TRUE if the #GHook function is currently executing.</doc>
|
|
<parameters>
|
|
<parameter name="hook">
|
|
<doc xml:space="preserve">a #GHook</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="HOOK_IS_UNLINKED" c:identifier="G_HOOK_IS_UNLINKED" introspectable="0">
|
|
<doc xml:space="preserve">Returns %TRUE if the #GHook is not in a #GHookList.</doc>
|
|
<parameters>
|
|
<parameter name="hook">
|
|
<doc xml:space="preserve">a #GHook</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="HOOK_IS_VALID" c:identifier="G_HOOK_IS_VALID" introspectable="0">
|
|
<doc xml:space="preserve">Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList,
|
|
it is active and it has not been destroyed.</doc>
|
|
<parameters>
|
|
<parameter name="hook">
|
|
<doc xml:space="preserve">a #GHook</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<callback name="HRFunc" c:type="GHRFunc">
|
|
<doc xml:space="preserve">Specifies the type of the function passed to
|
|
g_hash_table_foreach_remove(). It is called with each key/value
|
|
pair, together with the @user_data parameter passed to
|
|
g_hash_table_foreach_remove(). It should return %TRUE if the
|
|
key/value pair should be removed from the #GHashTable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key/value pair should be removed from the
|
|
#GHashTable</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the value associated with the key</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2">
|
|
<doc xml:space="preserve">user data passed to g_hash_table_remove()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<callback name="HashFunc" c:type="GHashFunc">
|
|
<doc xml:space="preserve">Specifies the type of the hash function which is passed to
|
|
g_hash_table_new() when a #GHashTable is created.
|
|
|
|
The function is passed a key and should return a #guint hash value.
|
|
The functions g_direct_hash(), g_int_hash() and g_str_hash() provide
|
|
hash functions which can be used when the key is a #gpointer, #gint*,
|
|
and #gchar* respectively.
|
|
|
|
g_direct_hash() is also the appropriate hash function for keys
|
|
of the form `GINT_TO_POINTER (n)` (or similar macros).
|
|
|
|
A good hash functions should produce
|
|
hash values that are evenly distributed over a fairly large range.
|
|
The modulus is taken with the hash table size (a prime number) to
|
|
find the 'bucket' to place each key into. The function should also
|
|
be very fast, since it is called for each key lookup.
|
|
|
|
Note that the hash functions provided by GLib have these qualities,
|
|
but are not particularly robust against manufactured keys that
|
|
cause hash collisions. Therefore, you should consider choosing
|
|
a more secure hash function when using a GHashTable with keys
|
|
that originate in untrusted data (such as HTTP requests).
|
|
Using g_str_hash() in that situation might make your application
|
|
vulnerable to
|
|
[Algorithmic Complexity Attacks](https://lwn.net/Articles/474912/).
|
|
|
|
The key to choosing a good hash is unpredictability. Even
|
|
cryptographic hashes are very easy to find collisions for when the
|
|
remainder is taken modulo a somewhat predictable prime number. There
|
|
must be an element of randomness that an attacker is unable to guess.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the hash value corresponding to the key</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<record name="HashTable" c:type="GHashTable" glib:type-name="GHashTable" glib:get-type="g_hash_table_get_type" c:symbol-prefix="hash_table">
|
|
<doc xml:space="preserve">The #GHashTable struct is an opaque data structure to represent a
|
|
[Hash Table][glib-Hash-Tables]. It should only be accessed via the
|
|
following functions.</doc>
|
|
<function name="add" c:identifier="g_hash_table_add" version="2.32">
|
|
<doc xml:space="preserve">This is a convenience function for using a #GHashTable as a set. It
|
|
is equivalent to calling g_hash_table_replace() with @key as both the
|
|
key and the value.
|
|
|
|
In particular, this means that if @key already exists in the hash table, then
|
|
the old copy of @key in the hash table is freed and @key replaces it in the
|
|
table.
|
|
|
|
When a hash table only ever contains keys that have themselves as the
|
|
corresponding value it is able to be stored more efficiently. See
|
|
the discussion in the section description.
|
|
|
|
Starting from GLib 2.40, this function returns a boolean value to
|
|
indicate whether the newly added value was already in the hash table
|
|
or not.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key did not exist yet</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="full" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a key to insert</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="contains" c:identifier="g_hash_table_contains" version="2.32">
|
|
<doc xml:space="preserve">Checks if @key is in @hash_table.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @key is in @hash_table, %FALSE otherwise.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a key to check</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="destroy" c:identifier="g_hash_table_destroy">
|
|
<doc xml:space="preserve">Destroys all keys and values in the #GHashTable and decrements its
|
|
reference count by 1. If keys and/or values are dynamically allocated,
|
|
you should either free them first or create the #GHashTable with destroy
|
|
notifiers using g_hash_table_new_full(). In the latter case the destroy
|
|
functions you supplied will be called on all keys and values during the
|
|
destruction phase.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="find" c:identifier="g_hash_table_find" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Calls the given function for key/value pairs in the #GHashTable
|
|
until @predicate returns %TRUE. The function is passed the key
|
|
and value of each pair, and the given @user_data parameter. The
|
|
hash table may not be modified while iterating over it (you can't
|
|
add/remove items).
|
|
|
|
Note, that hash tables are really only optimized for forward
|
|
lookups, i.e. g_hash_table_lookup(). So code that frequently issues
|
|
g_hash_table_find() or g_hash_table_foreach() (e.g. in the order of
|
|
once per every entry in a hash table) should probably be reworked
|
|
to use additional or different data structures for reverse lookups
|
|
(keep in mind that an O(n) find/foreach operation issued for all n
|
|
values in a hash table ends up needing O(n*n) operations).</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">The value of the first key/value pair is returned,
|
|
for which @predicate evaluates to %TRUE. If no pair with the
|
|
requested property is found, %NULL is returned.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="predicate" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">function to test the key/value pairs for a certain property</doc>
|
|
<type name="HRFunc" c:type="GHRFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to the function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="foreach" c:identifier="g_hash_table_foreach" introspectable="0">
|
|
<doc xml:space="preserve">Calls the given function for each of the key/value pairs in the
|
|
#GHashTable. The function is passed the key and value of each
|
|
pair, and the given @user_data parameter. The hash table may not
|
|
be modified while iterating over it (you can't add/remove
|
|
items). To remove all items matching a predicate, use
|
|
g_hash_table_foreach_remove().
|
|
|
|
The order in which g_hash_table_foreach() iterates over the keys/values in
|
|
the hash table is not defined.
|
|
|
|
See g_hash_table_find() for performance caveats for linear
|
|
order searches in contrast to g_hash_table_lookup().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function to call for each key/value pair</doc>
|
|
<type name="HFunc" c:type="GHFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to the function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="foreach_remove" c:identifier="g_hash_table_foreach_remove" introspectable="0">
|
|
<doc xml:space="preserve">Calls the given function for each key/value pair in the
|
|
#GHashTable. If the function returns %TRUE, then the key/value
|
|
pair is removed from the #GHashTable. If you supplied key or
|
|
value destroy functions when creating the #GHashTable, they are
|
|
used to free the memory allocated for the removed keys and values.
|
|
|
|
See #GHashTableIter for an alternative way to loop over the
|
|
key/value pairs in the hash table.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of key/value pairs removed</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function to call for each key/value pair</doc>
|
|
<type name="HRFunc" c:type="GHRFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to the function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="foreach_steal" c:identifier="g_hash_table_foreach_steal" introspectable="0">
|
|
<doc xml:space="preserve">Calls the given function for each key/value pair in the
|
|
#GHashTable. If the function returns %TRUE, then the key/value
|
|
pair is removed from the #GHashTable, but no key or value
|
|
destroy functions are called.
|
|
|
|
See #GHashTableIter for an alternative way to loop over the
|
|
key/value pairs in the hash table.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of key/value pairs removed.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function to call for each key/value pair</doc>
|
|
<type name="HRFunc" c:type="GHRFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to the function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="get_keys" c:identifier="g_hash_table_get_keys" version="2.14" introspectable="0">
|
|
<doc xml:space="preserve">Retrieves every key inside @hash_table. The returned data is valid
|
|
until changes to the hash release those keys.
|
|
|
|
This iterates over every entry in the hash table to build its return value.
|
|
To iterate over the entries in a #GHashTable more efficiently, use a
|
|
#GHashTableIter.</doc>
|
|
<return-value transfer-ownership="container">
|
|
<doc xml:space="preserve">a #GList containing all the keys
|
|
inside the hash table. The content of the list is owned by the
|
|
hash table and should not be modified or freed. Use g_list_free()
|
|
when done using the list.</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="get_keys_as_array" c:identifier="g_hash_table_get_keys_as_array" version="2.40" introspectable="0">
|
|
<doc xml:space="preserve">Retrieves every key inside @hash_table, as an array.
|
|
|
|
The returned array is %NULL-terminated but may contain %NULL as a
|
|
key. Use @length to determine the true length if it's possible that
|
|
%NULL was used as the value for a key.
|
|
|
|
Note: in the common case of a string-keyed #GHashTable, the return
|
|
value of this function can be conveniently cast to (const gchar **).
|
|
|
|
This iterates over every entry in the hash table to build its return value.
|
|
To iterate over the entries in a #GHashTable more efficiently, use a
|
|
#GHashTableIter.
|
|
|
|
You should always free the return result with g_free(). In the
|
|
above-mentioned case of a string-keyed hash table, it may be
|
|
appropriate to use g_strfreev() if you call g_hash_table_steal_all()
|
|
first to transfer ownership of the keys.</doc>
|
|
<return-value transfer-ownership="container">
|
|
<doc xml:space="preserve">a
|
|
%NULL-terminated array containing each key from the table.</doc>
|
|
<array length="1" zero-terminated="0" c:type="gpointer*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">the length of the returned array</doc>
|
|
<type name="guint" c:type="guint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="get_values" c:identifier="g_hash_table_get_values" version="2.14" introspectable="0">
|
|
<doc xml:space="preserve">Retrieves every value inside @hash_table. The returned data
|
|
is valid until @hash_table is modified.
|
|
|
|
This iterates over every entry in the hash table to build its return value.
|
|
To iterate over the entries in a #GHashTable more efficiently, use a
|
|
#GHashTableIter.</doc>
|
|
<return-value transfer-ownership="container">
|
|
<doc xml:space="preserve">a #GList containing all the values
|
|
inside the hash table. The content of the list is owned by the
|
|
hash table and should not be modified or freed. Use g_list_free()
|
|
when done using the list.</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="insert" c:identifier="g_hash_table_insert">
|
|
<doc xml:space="preserve">Inserts a new key and value into a #GHashTable.
|
|
|
|
If the key already exists in the #GHashTable its current
|
|
value is replaced with the new value. If you supplied a
|
|
@value_destroy_func when creating the #GHashTable, the old
|
|
value is freed using that function. If you supplied a
|
|
@key_destroy_func when creating the #GHashTable, the passed
|
|
key is freed using that function.
|
|
|
|
Starting from GLib 2.40, this function returns a boolean value to
|
|
indicate whether the newly added value was already in the hash table
|
|
or not.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key did not exist yet</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a key to insert</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the value to associate with the key</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="lookup" c:identifier="g_hash_table_lookup">
|
|
<doc xml:space="preserve">Looks up a key in a #GHashTable. Note that this function cannot
|
|
distinguish between a key that is not present and one which is present
|
|
and has the value %NULL. If you need this distinction, use
|
|
g_hash_table_lookup_extended().</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the associated value, or %NULL if the key is not found</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the key to look up</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="lookup_extended" c:identifier="g_hash_table_lookup_extended">
|
|
<doc xml:space="preserve">Looks up a key in the #GHashTable, returning the original key and the
|
|
associated value and a #gboolean which is %TRUE if the key was found. This
|
|
is useful if you need to free the memory allocated for the original key,
|
|
for example before calling g_hash_table_remove().
|
|
|
|
You can actually pass %NULL for @lookup_key to test
|
|
whether the %NULL key exists, provided the hash and equal functions
|
|
of @hash_table are %NULL-safe.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key was found in the #GHashTable</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="lookup_key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the key to look up</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="orig_key" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the original key</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</parameter>
|
|
<parameter name="value" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the value associated
|
|
with the key</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="new" c:identifier="g_hash_table_new" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GHashTable with a reference count of 1.
|
|
|
|
Hash values returned by @hash_func are used to determine where keys
|
|
are stored within the #GHashTable data structure. The g_direct_hash(),
|
|
g_int_hash(), g_int64_hash(), g_double_hash() and g_str_hash()
|
|
functions are provided for some common types of keys.
|
|
If @hash_func is %NULL, g_direct_hash() is used.
|
|
|
|
@key_equal_func is used when looking up keys in the #GHashTable.
|
|
The g_direct_equal(), g_int_equal(), g_int64_equal(), g_double_equal()
|
|
and g_str_equal() functions are provided for the most common types
|
|
of keys. If @key_equal_func is %NULL, keys are compared directly in
|
|
a similar fashion to g_direct_equal(), but without the overhead of
|
|
a function call. @key_equal_func is called with the key from the hash table
|
|
as its first parameter, and the user-provided key to check against as
|
|
its second.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a new #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_func" transfer-ownership="none">
|
|
<doc xml:space="preserve">a function to create a hash value from a key</doc>
|
|
<type name="HashFunc" c:type="GHashFunc"/>
|
|
</parameter>
|
|
<parameter name="key_equal_func" transfer-ownership="none">
|
|
<doc xml:space="preserve">a function to check two keys for equality</doc>
|
|
<type name="EqualFunc" c:type="GEqualFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="new_full" c:identifier="g_hash_table_new_full" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GHashTable like g_hash_table_new() with a reference
|
|
count of 1 and allows to specify functions to free the memory
|
|
allocated for the key and value that get called when removing the
|
|
entry from the #GHashTable.
|
|
|
|
Since version 2.42 it is permissible for destroy notify functions to
|
|
recursively remove further items from the hash table. This is only
|
|
permissible if the application still holds a reference to the hash table.
|
|
This means that you may need to ensure that the hash table is empty by
|
|
calling g_hash_table_remove_all() before releasing the last reference using
|
|
g_hash_table_unref().</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a new #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_func" transfer-ownership="none">
|
|
<doc xml:space="preserve">a function to create a hash value from a key</doc>
|
|
<type name="HashFunc" c:type="GHashFunc"/>
|
|
</parameter>
|
|
<parameter name="key_equal_func" transfer-ownership="none" scope="notified" destroy="3">
|
|
<doc xml:space="preserve">a function to check two keys for equality</doc>
|
|
<type name="EqualFunc" c:type="GEqualFunc"/>
|
|
</parameter>
|
|
<parameter name="key_destroy_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">a function to free the memory allocated for the key
|
|
used when removing the entry from the #GHashTable, or %NULL
|
|
if you don't want to supply such a function.</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
<parameter name="value_destroy_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">a function to free the memory allocated for the
|
|
value used when removing the entry from the #GHashTable, or %NULL
|
|
if you don't want to supply such a function.</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ref" c:identifier="g_hash_table_ref" version="2.10" introspectable="0">
|
|
<doc xml:space="preserve">Atomically increments the reference count of @hash_table by one.
|
|
This function is MT-safe and may be called from any thread.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the passed in #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove" c:identifier="g_hash_table_remove">
|
|
<doc xml:space="preserve">Removes a key and its associated value from a #GHashTable.
|
|
|
|
If the #GHashTable was created using g_hash_table_new_full(), the
|
|
key and value are freed using the supplied destroy functions, otherwise
|
|
you have to make sure that any dynamically allocated values are freed
|
|
yourself.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key was found and removed from the #GHashTable</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the key to remove</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_all" c:identifier="g_hash_table_remove_all" version="2.12">
|
|
<doc xml:space="preserve">Removes all keys and their associated values from a #GHashTable.
|
|
|
|
If the #GHashTable was created using g_hash_table_new_full(),
|
|
the keys and values are freed using the supplied destroy functions,
|
|
otherwise you have to make sure that any dynamically allocated
|
|
values are freed yourself.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="replace" c:identifier="g_hash_table_replace">
|
|
<doc xml:space="preserve">Inserts a new key and value into a #GHashTable similar to
|
|
g_hash_table_insert(). The difference is that if the key
|
|
already exists in the #GHashTable, it gets replaced by the
|
|
new key. If you supplied a @value_destroy_func when creating
|
|
the #GHashTable, the old value is freed using that function.
|
|
If you supplied a @key_destroy_func when creating the
|
|
#GHashTable, the old key is freed using that function.
|
|
|
|
Starting from GLib 2.40, this function returns a boolean value to
|
|
indicate whether the newly added value was already in the hash table
|
|
or not.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key did not exist yet</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a key to insert</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the value to associate with the key</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="size" c:identifier="g_hash_table_size">
|
|
<doc xml:space="preserve">Returns the number of elements contained in the #GHashTable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of key/value pairs in the #GHashTable.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="steal" c:identifier="g_hash_table_steal">
|
|
<doc xml:space="preserve">Removes a key and its associated value from a #GHashTable without
|
|
calling the key and value destroy functions.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key was found and removed from the #GHashTable</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the key to remove</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="steal_all" c:identifier="g_hash_table_steal_all" version="2.12">
|
|
<doc xml:space="preserve">Removes all keys and their associated values from a #GHashTable
|
|
without calling the key and value destroy functions.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="steal_extended" c:identifier="g_hash_table_steal_extended" version="2.58">
|
|
<doc xml:space="preserve">Looks up a key in the #GHashTable, stealing the original key and the
|
|
associated value and returning %TRUE if the key was found. If the key was
|
|
not found, %FALSE is returned.
|
|
|
|
If found, the stolen key and value are removed from the hash table without
|
|
calling the key and value destroy functions, and ownership is transferred to
|
|
the caller of this method; as with g_hash_table_steal().
|
|
|
|
You can pass %NULL for @lookup_key, provided the hash and equal functions
|
|
of @hash_table are %NULL-safe.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key was found in the #GHashTable</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="lookup_key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the key to look up</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="stolen_key" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the
|
|
original key</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</parameter>
|
|
<parameter name="stolen_value" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location
|
|
for the value associated with the key</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unref" c:identifier="g_hash_table_unref" version="2.10">
|
|
<doc xml:space="preserve">Atomically decrements the reference count of @hash_table by one.
|
|
If the reference count drops to 0, all keys and values will be
|
|
destroyed, and all memory allocated by the hash table is released.
|
|
This function is MT-safe and may be called from any thread.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<record name="HashTableIter" c:type="GHashTableIter">
|
|
<doc xml:space="preserve">A GHashTableIter structure represents an iterator that can be used
|
|
to iterate over the elements of a #GHashTable. GHashTableIter
|
|
structures are typically allocated on the stack and then initialized
|
|
with g_hash_table_iter_init().
|
|
|
|
The iteration order of a #GHashTableIter over the keys/values in a hash
|
|
table is not defined.</doc>
|
|
<field name="dummy1" readable="0" private="1">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="dummy2" readable="0" private="1">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="dummy3" readable="0" private="1">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="dummy4" readable="0" private="1">
|
|
<type name="gint" c:type="int"/>
|
|
</field>
|
|
<field name="dummy5" readable="0" private="1">
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</field>
|
|
<field name="dummy6" readable="0" private="1">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<method name="get_hash_table" c:identifier="g_hash_table_iter_get_hash_table" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Returns the #GHashTable associated with @iter.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GHashTable associated with @iter.</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">an initialized #GHashTableIter</doc>
|
|
<type name="HashTableIter" c:type="GHashTableIter*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="init" c:identifier="g_hash_table_iter_init" version="2.16">
|
|
<doc xml:space="preserve">Initializes a key/value pair iterator and associates it with
|
|
@hash_table. Modifying the hash table after calling this function
|
|
invalidates the returned iterator.
|
|
|
|
The iteration order of a #GHashTableIter over the keys/values in a hash
|
|
table is not defined.
|
|
|
|
|[<!-- language="C" -->
|
|
GHashTableIter iter;
|
|
gpointer key, value;
|
|
|
|
g_hash_table_iter_init (&iter, hash_table);
|
|
while (g_hash_table_iter_next (&iter, &key, &value))
|
|
{
|
|
// do something with key and value
|
|
}
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">an uninitialized #GHashTableIter</doc>
|
|
<type name="HashTableIter" c:type="GHashTableIter*"/>
|
|
</instance-parameter>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="next" c:identifier="g_hash_table_iter_next" version="2.16">
|
|
<doc xml:space="preserve">Advances @iter and retrieves the key and/or value that are now
|
|
pointed to as a result of this advancement. If %FALSE is returned,
|
|
@key and @value are not set, and the iterator becomes invalid.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%FALSE if the end of the #GHashTable has been reached.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">an initialized #GHashTableIter</doc>
|
|
<type name="HashTableIter" c:type="GHashTableIter*"/>
|
|
</instance-parameter>
|
|
<parameter name="key" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">a location to store the key</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</parameter>
|
|
<parameter name="value" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">a location to store the value</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="remove" c:identifier="g_hash_table_iter_remove" version="2.16">
|
|
<doc xml:space="preserve">Removes the key/value pair currently pointed to by the iterator
|
|
from its associated #GHashTable. Can only be called after
|
|
g_hash_table_iter_next() returned %TRUE, and cannot be called
|
|
more than once for the same key/value pair.
|
|
|
|
If the #GHashTable was created using g_hash_table_new_full(),
|
|
the key and value are freed using the supplied destroy functions,
|
|
otherwise you have to make sure that any dynamically allocated
|
|
values are freed yourself.
|
|
|
|
It is safe to continue iterating the #GHashTable afterward:
|
|
|[<!-- language="C" -->
|
|
while (g_hash_table_iter_next (&iter, &key, &value))
|
|
{
|
|
if (condition)
|
|
g_hash_table_iter_remove (&iter);
|
|
}
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">an initialized #GHashTableIter</doc>
|
|
<type name="HashTableIter" c:type="GHashTableIter*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="replace" c:identifier="g_hash_table_iter_replace" version="2.30">
|
|
<doc xml:space="preserve">Replaces the value currently pointed to by the iterator
|
|
from its associated #GHashTable. Can only be called after
|
|
g_hash_table_iter_next() returned %TRUE.
|
|
|
|
If you supplied a @value_destroy_func when creating the
|
|
#GHashTable, the old value is freed using that function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">an initialized #GHashTableIter</doc>
|
|
<type name="HashTableIter" c:type="GHashTableIter*"/>
|
|
</instance-parameter>
|
|
<parameter name="value" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the value to replace with</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="steal" c:identifier="g_hash_table_iter_steal" version="2.16">
|
|
<doc xml:space="preserve">Removes the key/value pair currently pointed to by the
|
|
iterator from its associated #GHashTable, without calling
|
|
the key and value destroy functions. Can only be called
|
|
after g_hash_table_iter_next() returned %TRUE, and cannot
|
|
be called more than once for the same key/value pair.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">an initialized #GHashTableIter</doc>
|
|
<type name="HashTableIter" c:type="GHashTableIter*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<record name="Hmac" c:type="GHmac" disguised="1" version="2.30">
|
|
<doc xml:space="preserve">An opaque structure representing a HMAC operation.
|
|
To create a new GHmac, use g_hmac_new(). To free
|
|
a GHmac, use g_hmac_unref().</doc>
|
|
<method name="copy" c:identifier="g_hmac_copy" version="2.30" introspectable="0">
|
|
<doc xml:space="preserve">Copies a #GHmac. If @hmac has been closed, by calling
|
|
g_hmac_get_string() or g_hmac_get_digest(), the copied
|
|
HMAC will be closed as well.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the copy of the passed #GHmac. Use g_hmac_unref()
|
|
when finished using it.</doc>
|
|
<type name="Hmac" c:type="GHmac*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="hmac" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GHmac to copy</doc>
|
|
<type name="Hmac" c:type="const GHmac*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_digest" c:identifier="g_hmac_get_digest" version="2.30">
|
|
<doc xml:space="preserve">Gets the digest from @checksum as a raw binary array and places it
|
|
into @buffer. The size of the digest depends on the type of checksum.
|
|
|
|
Once this function has been called, the #GHmac is closed and can
|
|
no longer be updated with g_checksum_update().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="hmac" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHmac</doc>
|
|
<type name="Hmac" c:type="GHmac*"/>
|
|
</instance-parameter>
|
|
<parameter name="buffer" transfer-ownership="none">
|
|
<doc xml:space="preserve">output buffer</doc>
|
|
<array length="1" zero-terminated="0" c:type="guint8*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="digest_len" direction="inout" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">an inout parameter. The caller initializes it to the
|
|
size of @buffer. After the call it contains the length of the digest</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_string" c:identifier="g_hmac_get_string" version="2.30">
|
|
<doc xml:space="preserve">Gets the HMAC as a hexadecimal string.
|
|
|
|
Once this function has been called the #GHmac can no longer be
|
|
updated with g_hmac_update().
|
|
|
|
The hexadecimal characters will be lower case.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the hexadecimal representation of the HMAC. The
|
|
returned string is owned by the HMAC and should not be modified
|
|
or freed.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="hmac" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHmac</doc>
|
|
<type name="Hmac" c:type="GHmac*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_hmac_ref" version="2.30" introspectable="0">
|
|
<doc xml:space="preserve">Atomically increments the reference count of @hmac by one.
|
|
|
|
This function is MT-safe and may be called from any thread.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the passed in #GHmac.</doc>
|
|
<type name="Hmac" c:type="GHmac*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="hmac" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid #GHmac</doc>
|
|
<type name="Hmac" c:type="GHmac*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_hmac_unref" version="2.30">
|
|
<doc xml:space="preserve">Atomically decrements the reference count of @hmac by one.
|
|
|
|
If the reference count drops to 0, all keys and values will be
|
|
destroyed, and all memory allocated by the hash table is released.
|
|
This function is MT-safe and may be called from any thread.
|
|
Frees the memory allocated for @hmac.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="hmac" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHmac</doc>
|
|
<type name="Hmac" c:type="GHmac*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="update" c:identifier="g_hmac_update" version="2.30">
|
|
<doc xml:space="preserve">Feeds @data into an existing #GHmac.
|
|
|
|
The HMAC must still be open, that is g_hmac_get_string() or
|
|
g_hmac_get_digest() must not have been called on @hmac.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="hmac" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHmac</doc>
|
|
<type name="Hmac" c:type="GHmac*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none">
|
|
<doc xml:space="preserve">buffer used to compute the checksum</doc>
|
|
<array length="1" zero-terminated="0" c:type="const guchar*">
|
|
<type name="guint8" c:type="guchar"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">size of the buffer, or -1 if it is a nul-terminated string</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="new" c:identifier="g_hmac_new" version="2.30" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GHmac, using the digest algorithm @digest_type.
|
|
If the @digest_type is not known, %NULL is returned.
|
|
A #GHmac can be used to compute the HMAC of a key and an
|
|
arbitrary binary blob, using different hashing algorithms.
|
|
|
|
A #GHmac works by feeding a binary blob through g_hmac_update()
|
|
until the data is complete; the digest can then be extracted
|
|
using g_hmac_get_string(), which will return the checksum as a
|
|
hexadecimal string; or g_hmac_get_digest(), which will return a
|
|
array of raw bytes. Once either g_hmac_get_string() or
|
|
g_hmac_get_digest() have been called on a #GHmac, the HMAC
|
|
will be closed and it won't be possible to call g_hmac_update()
|
|
on it anymore.
|
|
|
|
Support for digests of type %G_CHECKSUM_SHA512 has been added in GLib 2.42.
|
|
Support for %G_CHECKSUM_SHA384 was added in GLib 2.52.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the newly created #GHmac, or %NULL.
|
|
Use g_hmac_unref() to free the memory allocated by it.</doc>
|
|
<type name="Hmac" c:type="GHmac*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="digest_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">the desired type of digest</doc>
|
|
<type name="ChecksumType" c:type="GChecksumType"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">the key for the HMAC</doc>
|
|
<array length="2" zero-terminated="0" c:type="const guchar*">
|
|
<type name="guint8" c:type="guchar"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="key_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the keys</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<record name="Hook" c:type="GHook">
|
|
<doc xml:space="preserve">The #GHook struct represents a single hook function in a #GHookList.</doc>
|
|
<field name="data" writable="1">
|
|
<doc xml:space="preserve">data which is passed to func when this hook is invoked</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="next" writable="1">
|
|
<doc xml:space="preserve">pointer to the next hook in the list</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</field>
|
|
<field name="prev" writable="1">
|
|
<doc xml:space="preserve">pointer to the previous hook in the list</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</field>
|
|
<field name="ref_count" writable="1">
|
|
<doc xml:space="preserve">the reference count of this hook</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="hook_id" writable="1">
|
|
<doc xml:space="preserve">the id of this hook, which is unique within its list</doc>
|
|
<type name="gulong" c:type="gulong"/>
|
|
</field>
|
|
<field name="flags" writable="1">
|
|
<doc xml:space="preserve">flags which are set for this hook. See #GHookFlagMask for
|
|
predefined flags</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="func" writable="1">
|
|
<doc xml:space="preserve">the function to call when this hook is invoked. The possible
|
|
signatures for this function are #GHookFunc and #GHookCheckFunc</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="destroy" writable="1">
|
|
<doc xml:space="preserve">the default @finalize_hook function of a #GHookList calls
|
|
this member of the hook that is being finalized</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</field>
|
|
<method name="compare_ids" c:identifier="g_hook_compare_ids">
|
|
<doc xml:space="preserve">Compares the ids of two #GHook elements, returning a negative value
|
|
if the second id is greater than the first.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a value <= 0 if the id of @sibling is >= the id of @new_hook</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="new_hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHook</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</instance-parameter>
|
|
<parameter name="sibling" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHook to compare with @new_hook</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="alloc" c:identifier="g_hook_alloc" introspectable="0">
|
|
<doc xml:space="preserve">Allocates space for a #GHook and initializes it.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a new #GHook</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="destroy" c:identifier="g_hook_destroy">
|
|
<doc xml:space="preserve">Destroys a #GHook, given its ID.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the #GHook was found in the #GHookList and destroyed</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="hook_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">a hook ID</doc>
|
|
<type name="gulong" c:type="gulong"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="destroy_link" c:identifier="g_hook_destroy_link">
|
|
<doc xml:space="preserve">Removes one #GHook from a #GHookList, marking it
|
|
inactive and calling g_hook_unref() on it.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GHook to remove</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="find" c:identifier="g_hook_find" introspectable="0">
|
|
<doc xml:space="preserve">Finds a #GHook in a #GHookList using the given function to
|
|
test for a match.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the found #GHook or %NULL if no matching #GHook is found</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="need_valids" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if #GHook elements which have been destroyed
|
|
should be skipped</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="3">
|
|
<doc xml:space="preserve">the function to call for each #GHook, which should return
|
|
%TRUE when the #GHook has been found</doc>
|
|
<type name="HookFindFunc" c:type="GHookFindFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to pass to @func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="find_data" c:identifier="g_hook_find_data" introspectable="0">
|
|
<doc xml:space="preserve">Finds a #GHook in a #GHookList with the given data.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GHook with the given @data or %NULL if no matching
|
|
#GHook is found</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="need_valids" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if #GHook elements which have been destroyed
|
|
should be skipped</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to find</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="find_func" c:identifier="g_hook_find_func" introspectable="0">
|
|
<doc xml:space="preserve">Finds a #GHook in a #GHookList with the given function.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GHook with the given @func or %NULL if no matching
|
|
#GHook is found</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="need_valids" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if #GHook elements which have been destroyed
|
|
should be skipped</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the function to find</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="find_func_data" c:identifier="g_hook_find_func_data" introspectable="0">
|
|
<doc xml:space="preserve">Finds a #GHook in a #GHookList with the given function and data.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GHook with the given @func and @data or %NULL if
|
|
no matching #GHook is found</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="need_valids" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if #GHook elements which have been destroyed
|
|
should be skipped</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<doc xml:space="preserve">the function to find</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to find</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="first_valid" c:identifier="g_hook_first_valid" introspectable="0">
|
|
<doc xml:space="preserve">Returns the first #GHook in a #GHookList which has not been destroyed.
|
|
The reference count for the #GHook is incremented, so you must call
|
|
g_hook_unref() to restore it when no longer needed. (Or call
|
|
g_hook_next_valid() if you are stepping through the #GHookList.)</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the first valid #GHook, or %NULL if none are valid</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="may_be_in_call" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if hooks which are currently running
|
|
(e.g. in another thread) are considered valid. If set to %FALSE,
|
|
these are skipped</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="free" c:identifier="g_hook_free">
|
|
<doc xml:space="preserve">Calls the #GHookList @finalize_hook function if it exists,
|
|
and frees the memory allocated for the #GHook.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GHook to free</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="get" c:identifier="g_hook_get" introspectable="0">
|
|
<doc xml:space="preserve">Returns the #GHook with the given id, or %NULL if it is not found.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GHook with the given id, or %NULL if it is not found</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="hook_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">a hook id</doc>
|
|
<type name="gulong" c:type="gulong"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="insert_before" c:identifier="g_hook_insert_before">
|
|
<doc xml:space="preserve">Inserts a #GHook into a #GHookList, before a given #GHook.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="sibling" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the #GHook to insert the new #GHook before</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
<parameter name="hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GHook to insert</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="insert_sorted" c:identifier="g_hook_insert_sorted" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a #GHook into a #GHookList, sorted by the given function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GHook to insert</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<doc xml:space="preserve">the comparison function used to sort the #GHook elements</doc>
|
|
<type name="HookCompareFunc" c:type="GHookCompareFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="next_valid" c:identifier="g_hook_next_valid" introspectable="0">
|
|
<doc xml:space="preserve">Returns the next #GHook in a #GHookList which has not been destroyed.
|
|
The reference count for the #GHook is incremented, so you must call
|
|
g_hook_unref() to restore it when no longer needed. (Or continue to call
|
|
g_hook_next_valid() until %NULL is returned.)</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the next valid #GHook, or %NULL if none are valid</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">the current #GHook</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
<parameter name="may_be_in_call" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if hooks which are currently running
|
|
(e.g. in another thread) are considered valid. If set to %FALSE,
|
|
these are skipped</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="prepend" c:identifier="g_hook_prepend">
|
|
<doc xml:space="preserve">Prepends a #GHook on the start of a #GHookList.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GHook to add to the start of @hook_list</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ref" c:identifier="g_hook_ref" introspectable="0">
|
|
<doc xml:space="preserve">Increments the reference count for a #GHook.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the @hook that was passed in (since 2.6)</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GHook to increment the reference count of</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unref" c:identifier="g_hook_unref">
|
|
<doc xml:space="preserve">Decrements the reference count of a #GHook.
|
|
If the reference count falls to 0, the #GHook is removed
|
|
from the #GHookList and g_hook_free() is called to free it.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GHook to unref</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<callback name="HookCheckFunc" c:type="GHookCheckFunc">
|
|
<doc xml:space="preserve">Defines the type of a hook function that can be invoked
|
|
by g_hook_list_invoke_check().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%FALSE if the #GHook should be destroyed</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data field of the #GHook is passed to the hook function here</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<callback name="HookCheckMarshaller" c:type="GHookCheckMarshaller">
|
|
<doc xml:space="preserve">Defines the type of function used by g_hook_list_marshal_check().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%FALSE if @hook should be destroyed</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHook</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
<parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<callback name="HookCompareFunc" c:type="GHookCompareFunc">
|
|
<doc xml:space="preserve">Defines the type of function used to compare #GHook elements in
|
|
g_hook_insert_sorted().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a value <= 0 if @new_hook should be before @sibling</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="new_hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GHook being inserted</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
<parameter name="sibling" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GHook to compare with @new_hook</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<callback name="HookFinalizeFunc" c:type="GHookFinalizeFunc">
|
|
<doc xml:space="preserve">Defines the type of function to be called when a hook in a
|
|
list of hooks gets finalized.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">the hook in @hook_list that gets finalized</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<callback name="HookFindFunc" c:type="GHookFindFunc">
|
|
<doc xml:space="preserve">Defines the type of the function passed to g_hook_find().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the required #GHook has been found</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHook</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to g_hook_find_func()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<bitfield name="HookFlagMask" c:type="GHookFlagMask">
|
|
<doc xml:space="preserve">Flags used internally in the #GHook implementation.</doc>
|
|
<member name="active" value="1" c:identifier="G_HOOK_FLAG_ACTIVE">
|
|
<doc xml:space="preserve">set if the hook has not been destroyed</doc>
|
|
</member>
|
|
<member name="in_call" value="2" c:identifier="G_HOOK_FLAG_IN_CALL">
|
|
<doc xml:space="preserve">set if the hook is currently being run</doc>
|
|
</member>
|
|
<member name="mask" value="15" c:identifier="G_HOOK_FLAG_MASK">
|
|
<doc xml:space="preserve">A mask covering all bits reserved for
|
|
hook flags; see %G_HOOK_FLAG_USER_SHIFT</doc>
|
|
</member>
|
|
</bitfield>
|
|
<callback name="HookFunc" c:type="GHookFunc">
|
|
<doc xml:space="preserve">Defines the type of a hook function that can be invoked
|
|
by g_hook_list_invoke().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data field of the #GHook is passed to the hook function here</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<record name="HookList" c:type="GHookList">
|
|
<doc xml:space="preserve">The #GHookList struct represents a list of hook functions.</doc>
|
|
<field name="seq_id" writable="1">
|
|
<doc xml:space="preserve">the next free #GHook id</doc>
|
|
<type name="gulong" c:type="gulong"/>
|
|
</field>
|
|
<field name="hook_size" writable="1" bits="16">
|
|
<doc xml:space="preserve">the size of the #GHookList elements, in bytes</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="is_setup" writable="1" bits="1">
|
|
<doc xml:space="preserve">1 if the #GHookList has been initialized</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="hooks" writable="1">
|
|
<doc xml:space="preserve">the first #GHook element in the list</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</field>
|
|
<field name="dummy3" writable="1">
|
|
<doc xml:space="preserve">unused</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="finalize_hook" writable="1">
|
|
<doc xml:space="preserve">the function to call to finalize a #GHook element.
|
|
The default behaviour is to call the hooks @destroy function</doc>
|
|
<type name="HookFinalizeFunc" c:type="GHookFinalizeFunc"/>
|
|
</field>
|
|
<field name="dummy" writable="1">
|
|
<doc xml:space="preserve">unused</doc>
|
|
<array zero-terminated="0" fixed-size="2">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</field>
|
|
<method name="clear" c:identifier="g_hook_list_clear">
|
|
<doc xml:space="preserve">Removes all the #GHook elements from a #GHookList.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="init" c:identifier="g_hook_list_init">
|
|
<doc xml:space="preserve">Initializes a #GHookList.
|
|
This must be called before the #GHookList is used.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</instance-parameter>
|
|
<parameter name="hook_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of each element in the #GHookList,
|
|
typically `sizeof (GHook)`.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="invoke" c:identifier="g_hook_list_invoke">
|
|
<doc xml:space="preserve">Calls all of the #GHook functions in a #GHookList.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</instance-parameter>
|
|
<parameter name="may_recurse" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if functions which are already running
|
|
(e.g. in another thread) can be called. If set to %FALSE,
|
|
these are skipped</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="invoke_check" c:identifier="g_hook_list_invoke_check">
|
|
<doc xml:space="preserve">Calls all of the #GHook functions in a #GHookList.
|
|
Any function which returns %FALSE is removed from the #GHookList.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</instance-parameter>
|
|
<parameter name="may_recurse" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if functions which are already running
|
|
(e.g. in another thread) can be called. If set to %FALSE,
|
|
these are skipped</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="marshal" c:identifier="g_hook_list_marshal" introspectable="0">
|
|
<doc xml:space="preserve">Calls a function on each valid #GHook.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</instance-parameter>
|
|
<parameter name="may_recurse" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if hooks which are currently running
|
|
(e.g. in another thread) are considered valid. If set to %FALSE,
|
|
these are skipped</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
<parameter name="marshaller" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function to call for each #GHook</doc>
|
|
<type name="HookMarshaller" c:type="GHookMarshaller"/>
|
|
</parameter>
|
|
<parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @marshaller</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="marshal_check" c:identifier="g_hook_list_marshal_check" introspectable="0">
|
|
<doc xml:space="preserve">Calls a function on each valid #GHook and destroys it if the
|
|
function returns %FALSE.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</instance-parameter>
|
|
<parameter name="may_recurse" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if hooks which are currently running
|
|
(e.g. in another thread) are considered valid. If set to %FALSE,
|
|
these are skipped</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
<parameter name="marshaller" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function to call for each #GHook</doc>
|
|
<type name="HookCheckMarshaller" c:type="GHookCheckMarshaller"/>
|
|
</parameter>
|
|
<parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @marshaller</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<callback name="HookMarshaller" c:type="GHookMarshaller">
|
|
<doc xml:space="preserve">Defines the type of function used by g_hook_list_marshal().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHook</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
<parameter name="marshal_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<record name="IConv" c:type="GIConv" disguised="1" introspectable="0">
|
|
<doc xml:space="preserve">The GIConv struct wraps an iconv() conversion descriptor. It contains
|
|
private data and should only be accessed using the following functions.</doc>
|
|
<method name="" c:identifier="g_iconv" moved-to="iconv" introspectable="0">
|
|
<doc xml:space="preserve">Same as the standard UNIX routine iconv(), but
|
|
may be implemented via libiconv on UNIX flavors that lack
|
|
a native implementation.
|
|
|
|
GLib provides g_convert() and g_locale_to_utf8() which are likely
|
|
more convenient than the raw iconv wrappers.
|
|
|
|
Note that the behaviour of iconv() for characters which are valid in the
|
|
input character set, but which have no representation in the output character
|
|
set, is implementation defined. This function may return success (with a
|
|
positive number of non-reversible conversions as replacement characters were
|
|
used), or it may return -1 and set an error such as %EILSEQ, in such a
|
|
situation.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">count of non-reversible conversions, or -1 on error</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="converter" transfer-ownership="none">
|
|
<doc xml:space="preserve">conversion descriptor from g_iconv_open()</doc>
|
|
<type name="IConv" c:type="GIConv"/>
|
|
</instance-parameter>
|
|
<parameter name="inbuf" transfer-ownership="none">
|
|
<doc xml:space="preserve">bytes to convert</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="inbytes_left" transfer-ownership="none">
|
|
<doc xml:space="preserve">inout parameter, bytes remaining to convert in @inbuf</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
<parameter name="outbuf" transfer-ownership="none">
|
|
<doc xml:space="preserve">converted output bytes</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="outbytes_left" transfer-ownership="none">
|
|
<doc xml:space="preserve">inout parameter, bytes available to fill in @outbuf</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="close" c:identifier="g_iconv_close" introspectable="0">
|
|
<doc xml:space="preserve">Same as the standard UNIX routine iconv_close(), but
|
|
may be implemented via libiconv on UNIX flavors that lack
|
|
a native implementation. Should be called to clean up
|
|
the conversion descriptor from g_iconv_open() when
|
|
you are done converting things.
|
|
|
|
GLib provides g_convert() and g_locale_to_utf8() which are likely
|
|
more convenient than the raw iconv wrappers.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">-1 on error, 0 on success</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="converter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a conversion descriptor from g_iconv_open()</doc>
|
|
<type name="IConv" c:type="GIConv"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="open" c:identifier="g_iconv_open" introspectable="0">
|
|
<doc xml:space="preserve">Same as the standard UNIX routine iconv_open(), but
|
|
may be implemented via libiconv on UNIX flavors that lack
|
|
a native implementation.
|
|
|
|
GLib provides g_convert() and g_locale_to_utf8() which are likely
|
|
more convenient than the raw iconv wrappers.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a "conversion descriptor", or (GIConv)-1 if
|
|
opening the converter failed.</doc>
|
|
<type name="IConv" c:type="GIConv"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="to_codeset" transfer-ownership="none">
|
|
<doc xml:space="preserve">destination codeset</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="from_codeset" transfer-ownership="none">
|
|
<doc xml:space="preserve">source codeset</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<constant name="IEEE754_DOUBLE_BIAS" value="1023" c:type="G_IEEE754_DOUBLE_BIAS">
|
|
<doc xml:space="preserve">The bias by which exponents in double-precision floats are offset.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="IEEE754_FLOAT_BIAS" value="127" c:type="G_IEEE754_FLOAT_BIAS">
|
|
<doc xml:space="preserve">The bias by which exponents in single-precision floats are offset.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<record name="IOChannel" c:type="GIOChannel" glib:type-name="GIOChannel" glib:get-type="g_io_channel_get_type" c:symbol-prefix="io_channel">
|
|
<doc xml:space="preserve">A data structure representing an IO Channel. The fields should be
|
|
considered private and should only be accessed with the following
|
|
functions.</doc>
|
|
<field name="ref_count" readable="0" private="1">
|
|
<type name="gint" c:type="gint"/>
|
|
</field>
|
|
<field name="funcs" readable="0" private="1">
|
|
<type name="IOFuncs" c:type="GIOFuncs*"/>
|
|
</field>
|
|
<field name="encoding" readable="0" private="1">
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</field>
|
|
<field name="read_cd" introspectable="0" readable="0" private="1">
|
|
<type name="IConv" c:type="GIConv"/>
|
|
</field>
|
|
<field name="write_cd" introspectable="0" readable="0" private="1">
|
|
<type name="IConv" c:type="GIConv"/>
|
|
</field>
|
|
<field name="line_term" readable="0" private="1">
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</field>
|
|
<field name="line_term_len" readable="0" private="1">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="buf_size" readable="0" private="1">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</field>
|
|
<field name="read_buf" readable="0" private="1">
|
|
<type name="String" c:type="GString*"/>
|
|
</field>
|
|
<field name="encoded_read_buf" readable="0" private="1">
|
|
<type name="String" c:type="GString*"/>
|
|
</field>
|
|
<field name="write_buf" readable="0" private="1">
|
|
<type name="String" c:type="GString*"/>
|
|
</field>
|
|
<field name="partial_write_buf" readable="0" private="1">
|
|
<array zero-terminated="0" fixed-size="6">
|
|
<type name="gchar" c:type="gchar"/>
|
|
</array>
|
|
</field>
|
|
<field name="use_buffer" readable="0" bits="1" private="1">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="do_encode" readable="0" bits="1" private="1">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="close_on_unref" readable="0" bits="1" private="1">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="is_readable" readable="0" bits="1" private="1">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="is_writeable" readable="0" bits="1" private="1">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="is_seekable" readable="0" bits="1" private="1">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="reserved1" readable="0" private="1">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="reserved2" readable="0" private="1">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<constructor name="new_file" c:identifier="g_io_channel_new_file" throws="1">
|
|
<doc xml:space="preserve">Open a file @filename as a #GIOChannel using mode @mode. This
|
|
channel will be closed when the last reference to it is dropped,
|
|
so there is no need to call g_io_channel_close() (though doing
|
|
so will not cause problems, as long as no attempt is made to
|
|
access the channel after it is closed).</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">A #GIOChannel on success, %NULL on failure.</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="filename" transfer-ownership="none">
|
|
<doc xml:space="preserve">A string containing the name of a file</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="mode" transfer-ownership="none">
|
|
<doc xml:space="preserve">One of "r", "w", "a", "r+", "w+", "a+". These have
|
|
the same meaning as in fopen()</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="unix_new" c:identifier="g_io_channel_unix_new">
|
|
<doc xml:space="preserve">Creates a new #GIOChannel given a file descriptor. On UNIX systems
|
|
this works for plain files, pipes, and sockets.
|
|
|
|
The returned #GIOChannel has a reference count of 1.
|
|
|
|
The default encoding for #GIOChannel is UTF-8. If your application
|
|
is reading output from a command using via pipe, you may need to set
|
|
the encoding to the encoding of the current locale (see
|
|
g_get_charset()) with the g_io_channel_set_encoding() function.
|
|
By default, the fd passed will not be closed when the final reference
|
|
to the #GIOChannel data structure is dropped.
|
|
|
|
If you want to read raw binary data without interpretation, then
|
|
call the g_io_channel_set_encoding() function with %NULL for the
|
|
encoding argument.
|
|
|
|
This function is available in GLib on Windows, too, but you should
|
|
avoid using it on Windows. The domain of file descriptors and
|
|
sockets overlap. There is no way for GLib to know which one you mean
|
|
in case the argument you pass to this function happens to be both a
|
|
valid file descriptor and socket. If that happens a warning is
|
|
issued, and GLib assumes that it is the file descriptor you mean.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GIOChannel.</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">a file descriptor.</doc>
|
|
<type name="gint" c:type="int"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<method name="close" c:identifier="g_io_channel_close" deprecated="1" deprecated-version="2.2">
|
|
<doc xml:space="preserve">Close an IO channel. Any pending data to be written will be
|
|
flushed, ignoring errors. The channel will not be freed until the
|
|
last reference is dropped using g_io_channel_unref().</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_io_channel_shutdown() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="flush" c:identifier="g_io_channel_flush" throws="1">
|
|
<doc xml:space="preserve">Flushes the write buffer for the GIOChannel.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the status of the operation: One of
|
|
#G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or
|
|
#G_IO_STATUS_ERROR.</doc>
|
|
<type name="IOStatus" c:type="GIOStatus"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_buffer_condition" c:identifier="g_io_channel_get_buffer_condition">
|
|
<doc xml:space="preserve">This function returns a #GIOCondition depending on whether there
|
|
is data to be read/space to write data in the internal buffers in
|
|
the #GIOChannel. Only the flags %G_IO_IN and %G_IO_OUT may be set.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GIOCondition</doc>
|
|
<type name="IOCondition" c:type="GIOCondition"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_buffer_size" c:identifier="g_io_channel_get_buffer_size">
|
|
<doc xml:space="preserve">Gets the buffer size.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of the buffer.</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_buffered" c:identifier="g_io_channel_get_buffered">
|
|
<doc xml:space="preserve">Returns whether @channel is buffered.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the @channel is buffered.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_close_on_unref" c:identifier="g_io_channel_get_close_on_unref">
|
|
<doc xml:space="preserve">Returns whether the file/socket/whatever associated with @channel
|
|
will be closed when @channel receives its final unref and is
|
|
destroyed. The default value of this is %TRUE for channels created
|
|
by g_io_channel_new_file (), and %FALSE for all other channels.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the channel will be closed, %FALSE otherwise.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel.</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_encoding" c:identifier="g_io_channel_get_encoding">
|
|
<doc xml:space="preserve">Gets the encoding for the input/output of the channel.
|
|
The internal encoding is always UTF-8. The encoding %NULL
|
|
makes the channel safe for binary data.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">A string containing the encoding, this string is
|
|
owned by GLib and must not be freed.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_flags" c:identifier="g_io_channel_get_flags">
|
|
<doc xml:space="preserve">Gets the current flags for a #GIOChannel, including read-only
|
|
flags such as %G_IO_FLAG_IS_READABLE.
|
|
|
|
The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITABLE
|
|
are cached for internal use by the channel when it is created.
|
|
If they should change at some later point (e.g. partial shutdown
|
|
of a socket with the UNIX shutdown() function), the user
|
|
should immediately call g_io_channel_get_flags() to update
|
|
the internal values of these flags.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the flags which are set on the channel</doc>
|
|
<type name="IOFlags" c:type="GIOFlags"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_line_term" c:identifier="g_io_channel_get_line_term">
|
|
<doc xml:space="preserve">This returns the string that #GIOChannel uses to determine
|
|
where in the file a line break occurs. A value of %NULL
|
|
indicates autodetection.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">The line termination string. This value
|
|
is owned by GLib and must not be freed.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">a location to return the length of the line terminator</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="init" c:identifier="g_io_channel_init">
|
|
<doc xml:space="preserve">Initializes a #GIOChannel struct.
|
|
|
|
This is called by each of the above functions when creating a
|
|
#GIOChannel, and so is not often needed by the application
|
|
programmer (unless you are creating a new type of #GIOChannel).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="read" c:identifier="g_io_channel_read" deprecated="1" deprecated-version="2.2">
|
|
<doc xml:space="preserve">Reads data from a #GIOChannel.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_io_channel_read_chars() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%G_IO_ERROR_NONE if the operation was successful.</doc>
|
|
<type name="IOError" c:type="GIOError"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="buf" transfer-ownership="none">
|
|
<doc xml:space="preserve">a buffer to read the data into (which should be at least
|
|
count bytes long)</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="count" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes to read from the #GIOChannel</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="bytes_read" transfer-ownership="none">
|
|
<doc xml:space="preserve">returns the number of bytes actually read</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="read_chars" c:identifier="g_io_channel_read_chars" throws="1">
|
|
<doc xml:space="preserve">Replacement for g_io_channel_read() with the new API.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the status of the operation.</doc>
|
|
<type name="IOStatus" c:type="GIOStatus"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="buf" direction="out" caller-allocates="1" transfer-ownership="none">
|
|
<doc xml:space="preserve">
|
|
a buffer to read data into</doc>
|
|
<array length="1" zero-terminated="0" c:type="gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="count" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of the buffer. Note that the buffer may not be
|
|
completely filled even if there is data in the buffer if the
|
|
remaining data is not a complete character.</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">The number of bytes read. This may be
|
|
zero even on success if count < 6 and the channel's encoding
|
|
is non-%NULL. This indicates that the next UTF-8 character is
|
|
too wide for the buffer.</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="read_line" c:identifier="g_io_channel_read_line" throws="1">
|
|
<doc xml:space="preserve">Reads a line, including the terminating character(s),
|
|
from a #GIOChannel into a newly-allocated string.
|
|
@str_return will contain allocated memory if the return
|
|
is %G_IO_STATUS_NORMAL.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the status of the operation.</doc>
|
|
<type name="IOStatus" c:type="GIOStatus"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="str_return" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">The line read from the #GIOChannel, including the
|
|
line terminator. This data should be freed with g_free()
|
|
when no longer needed. This is a nul-terminated string.
|
|
If a @length of zero is returned, this will be %NULL instead.</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store length of the read data, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
<parameter name="terminator_pos" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store position of line terminator, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="read_line_string" c:identifier="g_io_channel_read_line_string" throws="1">
|
|
<doc xml:space="preserve">Reads a line from a #GIOChannel, using a #GString as a buffer.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the status of the operation.</doc>
|
|
<type name="IOStatus" c:type="GIOStatus"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="buffer" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString into which the line will be written.
|
|
If @buffer already contains data, the old data will
|
|
be overwritten.</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</parameter>
|
|
<parameter name="terminator_pos" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store position of line terminator, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="read_to_end" c:identifier="g_io_channel_read_to_end" throws="1">
|
|
<doc xml:space="preserve">Reads all the remaining data from the file.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%G_IO_STATUS_NORMAL on success.
|
|
This function never returns %G_IO_STATUS_EOF.</doc>
|
|
<type name="IOStatus" c:type="GIOStatus"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="str_return" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">Location to
|
|
store a pointer to a string holding the remaining data in the
|
|
#GIOChannel. This data should be freed with g_free() when no
|
|
longer needed. This data is terminated by an extra nul
|
|
character, but there may be other nuls in the intervening data.</doc>
|
|
<array length="1" zero-terminated="0" c:type="gchar**">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">location to store length of the data</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="read_unichar" c:identifier="g_io_channel_read_unichar" throws="1">
|
|
<doc xml:space="preserve">Reads a Unicode character from @channel.
|
|
This function cannot be called on a channel with %NULL encoding.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOStatus</doc>
|
|
<type name="IOStatus" c:type="GIOStatus"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="thechar" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">a location to return a character</doc>
|
|
<type name="gunichar" c:type="gunichar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_io_channel_ref">
|
|
<doc xml:space="preserve">Increments the reference count of a #GIOChannel.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the @channel that was passed in (since 2.6)</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="seek" c:identifier="g_io_channel_seek" deprecated="1" deprecated-version="2.2">
|
|
<doc xml:space="preserve">Sets the current position in the #GIOChannel, similar to the standard
|
|
library function fseek().</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_io_channel_seek_position() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%G_IO_ERROR_NONE if the operation was successful.</doc>
|
|
<type name="IOError" c:type="GIOError"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="offset" transfer-ownership="none">
|
|
<doc xml:space="preserve">an offset, in bytes, which is added to the position specified
|
|
by @type</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</parameter>
|
|
<parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position in the file, which can be %G_SEEK_CUR (the current
|
|
position), %G_SEEK_SET (the start of the file), or %G_SEEK_END
|
|
(the end of the file)</doc>
|
|
<type name="SeekType" c:type="GSeekType"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="seek_position" c:identifier="g_io_channel_seek_position" throws="1">
|
|
<doc xml:space="preserve">Replacement for g_io_channel_seek() with the new API.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the status of the operation.</doc>
|
|
<type name="IOStatus" c:type="GIOStatus"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="offset" transfer-ownership="none">
|
|
<doc xml:space="preserve">The offset in bytes from the position specified by @type</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</parameter>
|
|
<parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSeekType. The type %G_SEEK_CUR is only allowed in those
|
|
cases where a call to g_io_channel_set_encoding ()
|
|
is allowed. See the documentation for
|
|
g_io_channel_set_encoding () for details.</doc>
|
|
<type name="SeekType" c:type="GSeekType"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_buffer_size" c:identifier="g_io_channel_set_buffer_size">
|
|
<doc xml:space="preserve">Sets the buffer size.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of the buffer, or 0 to let GLib pick a good size</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_buffered" c:identifier="g_io_channel_set_buffered">
|
|
<doc xml:space="preserve">The buffering state can only be set if the channel's encoding
|
|
is %NULL. For any other encoding, the channel must be buffered.
|
|
|
|
A buffered channel can only be set unbuffered if the channel's
|
|
internal buffers have been flushed. Newly created channels or
|
|
channels which have returned %G_IO_STATUS_EOF
|
|
not require such a flush. For write-only channels, a call to
|
|
g_io_channel_flush () is sufficient. For all other channels,
|
|
the buffers may be flushed by a call to g_io_channel_seek_position ().
|
|
This includes the possibility of seeking with seek type %G_SEEK_CUR
|
|
and an offset of zero. Note that this means that socket-based
|
|
channels cannot be set unbuffered once they have had data
|
|
read from them.
|
|
|
|
On unbuffered channels, it is safe to mix read and write
|
|
calls from the new and old APIs, if this is necessary for
|
|
maintaining old code.
|
|
|
|
The default state of the channel is buffered.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="buffered" transfer-ownership="none">
|
|
<doc xml:space="preserve">whether to set the channel buffered or unbuffered</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_close_on_unref" c:identifier="g_io_channel_set_close_on_unref">
|
|
<doc xml:space="preserve">Whether to close the channel on the final unref of the #GIOChannel
|
|
data structure. The default value of this is %TRUE for channels
|
|
created by g_io_channel_new_file (), and %FALSE for all other channels.
|
|
|
|
Setting this flag to %TRUE for a channel you have already closed
|
|
can cause problems when the final reference to the #GIOChannel is dropped.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="do_close" transfer-ownership="none">
|
|
<doc xml:space="preserve">Whether to close the channel on the final unref of
|
|
the GIOChannel data structure.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_encoding" c:identifier="g_io_channel_set_encoding" throws="1">
|
|
<doc xml:space="preserve">Sets the encoding for the input/output of the channel.
|
|
The internal encoding is always UTF-8. The default encoding
|
|
for the external file is UTF-8.
|
|
|
|
The encoding %NULL is safe to use with binary data.
|
|
|
|
The encoding can only be set if one of the following conditions
|
|
is true:
|
|
|
|
- The channel was just created, and has not been written to or read from yet.
|
|
|
|
- The channel is write-only.
|
|
|
|
- The channel is a file, and the file pointer was just repositioned
|
|
by a call to g_io_channel_seek_position(). (This flushes all the
|
|
internal buffers.)
|
|
|
|
- The current encoding is %NULL or UTF-8.
|
|
|
|
- One of the (new API) read functions has just returned %G_IO_STATUS_EOF
|
|
(or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL).
|
|
|
|
- One of the functions g_io_channel_read_chars() or
|
|
g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or
|
|
%G_IO_STATUS_ERROR. This may be useful in the case of
|
|
%G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
|
|
Returning one of these statuses from g_io_channel_read_line(),
|
|
g_io_channel_read_line_string(), or g_io_channel_read_to_end()
|
|
does not guarantee that the encoding can be changed.
|
|
|
|
Channels which do not meet one of the above conditions cannot call
|
|
g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if
|
|
they are "seekable", cannot call g_io_channel_write_chars() after
|
|
calling one of the API "read" functions.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%G_IO_STATUS_NORMAL if the encoding was successfully set</doc>
|
|
<type name="IOStatus" c:type="GIOStatus"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="encoding" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the encoding type</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_flags" c:identifier="g_io_channel_set_flags" throws="1">
|
|
<doc xml:space="preserve">Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the status of the operation.</doc>
|
|
<type name="IOStatus" c:type="GIOStatus"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">the flags to set on the IO channel</doc>
|
|
<type name="IOFlags" c:type="GIOFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_line_term" c:identifier="g_io_channel_set_line_term">
|
|
<doc xml:space="preserve">This sets the string that #GIOChannel uses to determine
|
|
where in the file a line break occurs.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="line_term" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">The line termination string. Use %NULL for
|
|
autodetect. Autodetection breaks on "\n", "\r\n", "\r", "\0",
|
|
and the Unicode paragraph separator. Autodetection should not be
|
|
used for anything other than file-based channels.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">The length of the termination string. If -1 is passed, the
|
|
string is assumed to be nul-terminated. This option allows
|
|
termination strings with embedded nuls.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="shutdown" c:identifier="g_io_channel_shutdown" throws="1">
|
|
<doc xml:space="preserve">Close an IO channel. Any pending data to be written will be
|
|
flushed if @flush is %TRUE. The channel will not be freed until the
|
|
last reference is dropped using g_io_channel_unref().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the status of the operation.</doc>
|
|
<type name="IOStatus" c:type="GIOStatus"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="flush" transfer-ownership="none">
|
|
<doc xml:space="preserve">if %TRUE, flush pending</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unix_get_fd" c:identifier="g_io_channel_unix_get_fd">
|
|
<doc xml:space="preserve">Returns the file descriptor of the #GIOChannel.
|
|
|
|
On Windows this function returns the file descriptor or socket of
|
|
the #GIOChannel.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the file descriptor of the #GIOChannel.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel, created with g_io_channel_unix_new().</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_io_channel_unref">
|
|
<doc xml:space="preserve">Decrements the reference count of a #GIOChannel.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="write" c:identifier="g_io_channel_write" deprecated="1" deprecated-version="2.2">
|
|
<doc xml:space="preserve">Writes data to a #GIOChannel.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_io_channel_write_chars() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%G_IO_ERROR_NONE if the operation was successful.</doc>
|
|
<type name="IOError" c:type="GIOError"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="buf" transfer-ownership="none">
|
|
<doc xml:space="preserve">the buffer containing the data to write</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="count" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes to write</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="bytes_written" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes actually written</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="write_chars" c:identifier="g_io_channel_write_chars" throws="1">
|
|
<doc xml:space="preserve">Replacement for g_io_channel_write() with the new API.
|
|
|
|
On seekable channels with encodings other than %NULL or UTF-8, generic
|
|
mixing of reading and writing is not allowed. A call to g_io_channel_write_chars ()
|
|
may only be made on a channel from which data has been read in the
|
|
cases described in the documentation for g_io_channel_set_encoding ().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the status of the operation.</doc>
|
|
<type name="IOStatus" c:type="GIOStatus"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="buf" transfer-ownership="none">
|
|
<doc xml:space="preserve">a buffer to write data from</doc>
|
|
<array zero-terminated="0" c:type="const gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="count" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of the buffer. If -1, the buffer
|
|
is taken to be a nul-terminated string.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">The number of bytes written. This can be nonzero
|
|
even if the return value is not %G_IO_STATUS_NORMAL.
|
|
If the return value is %G_IO_STATUS_NORMAL and the
|
|
channel is blocking, this will always be equal
|
|
to @count if @count >= 0.</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="write_unichar" c:identifier="g_io_channel_write_unichar" throws="1">
|
|
<doc xml:space="preserve">Writes a Unicode character to @channel.
|
|
This function cannot be called on a channel with %NULL encoding.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOStatus</doc>
|
|
<type name="IOStatus" c:type="GIOStatus"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</instance-parameter>
|
|
<parameter name="thechar" transfer-ownership="none">
|
|
<doc xml:space="preserve">a character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="error_from_errno" c:identifier="g_io_channel_error_from_errno">
|
|
<doc xml:space="preserve">Converts an `errno` error number to a #GIOChannelError.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannelError error number, e.g.
|
|
%G_IO_CHANNEL_ERROR_INVAL.</doc>
|
|
<type name="IOChannelError" c:type="GIOChannelError"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="en" transfer-ownership="none">
|
|
<doc xml:space="preserve">an `errno` error number, e.g. `EINVAL`</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="error_quark" c:identifier="g_io_channel_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
</record>
|
|
<enumeration name="IOChannelError" c:type="GIOChannelError" glib:error-domain="g-io-channel-error-quark">
|
|
<doc xml:space="preserve">Error codes returned by #GIOChannel operations.</doc>
|
|
<member name="fbig" value="0" c:identifier="G_IO_CHANNEL_ERROR_FBIG">
|
|
<doc xml:space="preserve">File too large.</doc>
|
|
</member>
|
|
<member name="inval" value="1" c:identifier="G_IO_CHANNEL_ERROR_INVAL">
|
|
<doc xml:space="preserve">Invalid argument.</doc>
|
|
</member>
|
|
<member name="io" value="2" c:identifier="G_IO_CHANNEL_ERROR_IO">
|
|
<doc xml:space="preserve">IO error.</doc>
|
|
</member>
|
|
<member name="isdir" value="3" c:identifier="G_IO_CHANNEL_ERROR_ISDIR">
|
|
<doc xml:space="preserve">File is a directory.</doc>
|
|
</member>
|
|
<member name="nospc" value="4" c:identifier="G_IO_CHANNEL_ERROR_NOSPC">
|
|
<doc xml:space="preserve">No space left on device.</doc>
|
|
</member>
|
|
<member name="nxio" value="5" c:identifier="G_IO_CHANNEL_ERROR_NXIO">
|
|
<doc xml:space="preserve">No such device or address.</doc>
|
|
</member>
|
|
<member name="overflow" value="6" c:identifier="G_IO_CHANNEL_ERROR_OVERFLOW">
|
|
<doc xml:space="preserve">Value too large for defined datatype.</doc>
|
|
</member>
|
|
<member name="pipe" value="7" c:identifier="G_IO_CHANNEL_ERROR_PIPE">
|
|
<doc xml:space="preserve">Broken pipe.</doc>
|
|
</member>
|
|
<member name="failed" value="8" c:identifier="G_IO_CHANNEL_ERROR_FAILED">
|
|
<doc xml:space="preserve">Some other error.</doc>
|
|
</member>
|
|
</enumeration>
|
|
<bitfield name="IOCondition" glib:type-name="GIOCondition" glib:get-type="g_io_condition_get_type" c:type="GIOCondition">
|
|
<doc xml:space="preserve">A bitwise combination representing a condition to watch for on an
|
|
event source.</doc>
|
|
<member name="in" value="1" c:identifier="G_IO_IN" glib:nick="in">
|
|
<doc xml:space="preserve">There is data to read.</doc>
|
|
</member>
|
|
<member name="out" value="4" c:identifier="G_IO_OUT" glib:nick="out">
|
|
<doc xml:space="preserve">Data can be written (without blocking).</doc>
|
|
</member>
|
|
<member name="pri" value="2" c:identifier="G_IO_PRI" glib:nick="pri">
|
|
<doc xml:space="preserve">There is urgent data to read.</doc>
|
|
</member>
|
|
<member name="err" value="8" c:identifier="G_IO_ERR" glib:nick="err">
|
|
<doc xml:space="preserve">Error condition.</doc>
|
|
</member>
|
|
<member name="hup" value="16" c:identifier="G_IO_HUP" glib:nick="hup">
|
|
<doc xml:space="preserve">Hung up (the connection has been broken, usually for
|
|
pipes and sockets).</doc>
|
|
</member>
|
|
<member name="nval" value="32" c:identifier="G_IO_NVAL" glib:nick="nval">
|
|
<doc xml:space="preserve">Invalid request. The file descriptor is not open.</doc>
|
|
</member>
|
|
</bitfield>
|
|
<enumeration name="IOError" c:type="GIOError">
|
|
<doc xml:space="preserve">#GIOError is only used by the deprecated functions
|
|
g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek().</doc>
|
|
<member name="none" value="0" c:identifier="G_IO_ERROR_NONE">
|
|
<doc xml:space="preserve">no error</doc>
|
|
</member>
|
|
<member name="again" value="1" c:identifier="G_IO_ERROR_AGAIN">
|
|
<doc xml:space="preserve">an EAGAIN error occurred</doc>
|
|
</member>
|
|
<member name="inval" value="2" c:identifier="G_IO_ERROR_INVAL">
|
|
<doc xml:space="preserve">an EINVAL error occurred</doc>
|
|
</member>
|
|
<member name="unknown" value="3" c:identifier="G_IO_ERROR_UNKNOWN">
|
|
<doc xml:space="preserve">another error occurred</doc>
|
|
</member>
|
|
</enumeration>
|
|
<bitfield name="IOFlags" c:type="GIOFlags">
|
|
<doc xml:space="preserve">Specifies properties of a #GIOChannel. Some of the flags can only be
|
|
read with g_io_channel_get_flags(), but not changed with
|
|
g_io_channel_set_flags().</doc>
|
|
<member name="append" value="1" c:identifier="G_IO_FLAG_APPEND">
|
|
<doc xml:space="preserve">turns on append mode, corresponds to %O_APPEND
|
|
(see the documentation of the UNIX open() syscall)</doc>
|
|
</member>
|
|
<member name="nonblock" value="2" c:identifier="G_IO_FLAG_NONBLOCK">
|
|
<doc xml:space="preserve">turns on nonblocking mode, corresponds to
|
|
%O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open()
|
|
syscall)</doc>
|
|
</member>
|
|
<member name="is_readable" value="4" c:identifier="G_IO_FLAG_IS_READABLE">
|
|
<doc xml:space="preserve">indicates that the io channel is readable.
|
|
This flag cannot be changed.</doc>
|
|
</member>
|
|
<member name="is_writable" value="8" c:identifier="G_IO_FLAG_IS_WRITABLE">
|
|
<doc xml:space="preserve">indicates that the io channel is writable.
|
|
This flag cannot be changed.</doc>
|
|
</member>
|
|
<member name="is_writeable" value="8" c:identifier="G_IO_FLAG_IS_WRITEABLE">
|
|
<doc xml:space="preserve">a misspelled version of @G_IO_FLAG_IS_WRITABLE
|
|
that existed before the spelling was fixed in GLib 2.30. It is kept
|
|
here for compatibility reasons. Deprecated since 2.30</doc>
|
|
</member>
|
|
<member name="is_seekable" value="16" c:identifier="G_IO_FLAG_IS_SEEKABLE">
|
|
<doc xml:space="preserve">indicates that the io channel is seekable,
|
|
i.e. that g_io_channel_seek_position() can be used on it.
|
|
This flag cannot be changed.</doc>
|
|
</member>
|
|
<member name="mask" value="31" c:identifier="G_IO_FLAG_MASK">
|
|
<doc xml:space="preserve">the mask that specifies all the valid flags.</doc>
|
|
</member>
|
|
<member name="get_mask" value="31" c:identifier="G_IO_FLAG_GET_MASK">
|
|
<doc xml:space="preserve">the mask of the flags that are returned from
|
|
g_io_channel_get_flags()</doc>
|
|
</member>
|
|
<member name="set_mask" value="3" c:identifier="G_IO_FLAG_SET_MASK">
|
|
<doc xml:space="preserve">the mask of the flags that the user can modify
|
|
with g_io_channel_set_flags()</doc>
|
|
</member>
|
|
</bitfield>
|
|
<callback name="IOFunc" c:type="GIOFunc">
|
|
<doc xml:space="preserve">Specifies the type of function passed to g_io_add_watch() or
|
|
g_io_add_watch_full(), which is called when the requested condition
|
|
on a #GIOChannel is satisfied.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the function should return %FALSE if the event source
|
|
should be removed</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GIOChannel event source</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</parameter>
|
|
<parameter name="condition" transfer-ownership="none">
|
|
<doc xml:space="preserve">the condition which has been satisfied</doc>
|
|
<type name="IOCondition" c:type="GIOCondition"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data set in g_io_add_watch() or g_io_add_watch_full()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<record name="IOFuncs" c:type="GIOFuncs">
|
|
<doc xml:space="preserve">A table of functions used to handle different types of #GIOChannel
|
|
in a generic way.</doc>
|
|
<field name="io_read">
|
|
<callback name="io_read" throws="1">
|
|
<return-value transfer-ownership="none">
|
|
<type name="IOStatus" c:type="GIOStatus"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="channel" transfer-ownership="none">
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</parameter>
|
|
<parameter name="buf" transfer-ownership="none">
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="count" transfer-ownership="none">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="bytes_read" transfer-ownership="none">
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="io_write">
|
|
<callback name="io_write" throws="1">
|
|
<return-value transfer-ownership="none">
|
|
<type name="IOStatus" c:type="GIOStatus"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="channel" transfer-ownership="none">
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</parameter>
|
|
<parameter name="buf" transfer-ownership="none">
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="count" transfer-ownership="none">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="bytes_written" transfer-ownership="none">
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="io_seek">
|
|
<callback name="io_seek" throws="1">
|
|
<return-value transfer-ownership="none">
|
|
<type name="IOStatus" c:type="GIOStatus"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="channel" transfer-ownership="none">
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</parameter>
|
|
<parameter name="offset" transfer-ownership="none">
|
|
<type name="gint64" c:type="gint64"/>
|
|
</parameter>
|
|
<parameter name="type" transfer-ownership="none">
|
|
<type name="SeekType" c:type="GSeekType"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="io_close">
|
|
<callback name="io_close" throws="1">
|
|
<return-value transfer-ownership="none">
|
|
<type name="IOStatus" c:type="GIOStatus"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="channel" transfer-ownership="none">
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="io_create_watch">
|
|
<callback name="io_create_watch">
|
|
<return-value transfer-ownership="full">
|
|
<type name="Source" c:type="GSource*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="channel" transfer-ownership="none">
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</parameter>
|
|
<parameter name="condition" transfer-ownership="none">
|
|
<type name="IOCondition" c:type="GIOCondition"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="io_free">
|
|
<callback name="io_free">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="channel" transfer-ownership="none">
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="io_set_flags">
|
|
<callback name="io_set_flags" throws="1">
|
|
<return-value transfer-ownership="none">
|
|
<type name="IOStatus" c:type="GIOStatus"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="channel" transfer-ownership="none">
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<type name="IOFlags" c:type="GIOFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="io_get_flags">
|
|
<callback name="io_get_flags">
|
|
<return-value transfer-ownership="none">
|
|
<type name="IOFlags" c:type="GIOFlags"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="channel" transfer-ownership="none">
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
</record>
|
|
<enumeration name="IOStatus" c:type="GIOStatus">
|
|
<doc xml:space="preserve">Statuses returned by most of the #GIOFuncs functions.</doc>
|
|
<member name="error" value="0" c:identifier="G_IO_STATUS_ERROR">
|
|
<doc xml:space="preserve">An error occurred.</doc>
|
|
</member>
|
|
<member name="normal" value="1" c:identifier="G_IO_STATUS_NORMAL">
|
|
<doc xml:space="preserve">Success.</doc>
|
|
</member>
|
|
<member name="eof" value="2" c:identifier="G_IO_STATUS_EOF">
|
|
<doc xml:space="preserve">End of file.</doc>
|
|
</member>
|
|
<member name="again" value="3" c:identifier="G_IO_STATUS_AGAIN">
|
|
<doc xml:space="preserve">Resource temporarily unavailable.</doc>
|
|
</member>
|
|
</enumeration>
|
|
<function-macro name="IS_DIR_SEPARATOR" c:identifier="G_IS_DIR_SEPARATOR" version="2.6" introspectable="0">
|
|
<doc xml:space="preserve">Checks whether a character is a directory
|
|
separator. It returns %TRUE for '/' on UNIX
|
|
machines and for '\' or '/' under Windows.</doc>
|
|
<parameters>
|
|
<parameter name="c">
|
|
<doc xml:space="preserve">a character</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="KEY_FILE_DESKTOP_GROUP" value="Desktop Entry" c:type="G_KEY_FILE_DESKTOP_GROUP" version="2.14">
|
|
<doc xml:space="preserve">The name of the main group of a desktop entry file, as defined in the
|
|
[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec).
|
|
Consult the specification for more
|
|
details about the meanings of the keys below.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_ACTIONS" value="Actions" c:type="G_KEY_FILE_DESKTOP_KEY_ACTIONS" version="2.38">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string list
|
|
giving the available application actions.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_CATEGORIES" value="Categories" c:type="G_KEY_FILE_DESKTOP_KEY_CATEGORIES" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list
|
|
of strings giving the categories in which the desktop entry
|
|
should be shown in a menu.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_COMMENT" value="Comment" c:type="G_KEY_FILE_DESKTOP_KEY_COMMENT" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
|
|
string giving the tooltip for the desktop entry.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_DBUS_ACTIVATABLE" value="DBusActivatable" c:type="G_KEY_FILE_DESKTOP_KEY_DBUS_ACTIVATABLE" version="2.38">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean set to true
|
|
if the application is D-Bus activatable.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_EXEC" value="Exec" c:type="G_KEY_FILE_DESKTOP_KEY_EXEC" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
|
|
giving the command line to execute. It is only valid for desktop
|
|
entries with the `Application` type.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_GENERIC_NAME" value="GenericName" c:type="G_KEY_FILE_DESKTOP_KEY_GENERIC_NAME" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
|
|
string giving the generic name of the desktop entry.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_HIDDEN" value="Hidden" c:type="G_KEY_FILE_DESKTOP_KEY_HIDDEN" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
|
|
stating whether the desktop entry has been deleted by the user.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_ICON" value="Icon" c:type="G_KEY_FILE_DESKTOP_KEY_ICON" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
|
|
string giving the name of the icon to be displayed for the desktop
|
|
entry.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_MIME_TYPE" value="MimeType" c:type="G_KEY_FILE_DESKTOP_KEY_MIME_TYPE" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list
|
|
of strings giving the MIME types supported by this desktop entry.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_NAME" value="Name" c:type="G_KEY_FILE_DESKTOP_KEY_NAME" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
|
|
string giving the specific name of the desktop entry.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN" value="NotShowIn" c:type="G_KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
|
|
strings identifying the environments that should not display the
|
|
desktop entry.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_NO_DISPLAY" value="NoDisplay" c:type="G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
|
|
stating whether the desktop entry should be shown in menus.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN" value="OnlyShowIn" c:type="G_KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
|
|
strings identifying the environments that should display the
|
|
desktop entry.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_PATH" value="Path" c:type="G_KEY_FILE_DESKTOP_KEY_PATH" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
|
|
containing the working directory to run the program in. It is only
|
|
valid for desktop entries with the `Application` type.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY" value="StartupNotify" c:type="G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
|
|
stating whether the application supports the
|
|
[Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec).</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS" value="StartupWMClass" c:type="G_KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is string
|
|
identifying the WM class or name hint of a window that the application
|
|
will create, which can be used to emulate Startup Notification with
|
|
older applications.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_TERMINAL" value="Terminal" c:type="G_KEY_FILE_DESKTOP_KEY_TERMINAL" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
|
|
stating whether the program should be run in a terminal window.
|
|
It is only valid for desktop entries with the
|
|
`Application` type.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_TRY_EXEC" value="TryExec" c:type="G_KEY_FILE_DESKTOP_KEY_TRY_EXEC" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
|
|
giving the file name of a binary on disk used to determine if the
|
|
program is actually installed. It is only valid for desktop entries
|
|
with the `Application` type.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_TYPE" value="Type" c:type="G_KEY_FILE_DESKTOP_KEY_TYPE" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
|
|
giving the type of the desktop entry. Usually
|
|
#G_KEY_FILE_DESKTOP_TYPE_APPLICATION,
|
|
#G_KEY_FILE_DESKTOP_TYPE_LINK, or
|
|
#G_KEY_FILE_DESKTOP_TYPE_DIRECTORY.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_URL" value="URL" c:type="G_KEY_FILE_DESKTOP_KEY_URL" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
|
|
giving the URL to access. It is only valid for desktop entries
|
|
with the `Link` type.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_KEY_VERSION" value="Version" c:type="G_KEY_FILE_DESKTOP_KEY_VERSION" version="2.14">
|
|
<doc xml:space="preserve">A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
|
|
giving the version of the Desktop Entry Specification used for
|
|
the desktop entry file.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_TYPE_APPLICATION" value="Application" c:type="G_KEY_FILE_DESKTOP_TYPE_APPLICATION" version="2.14">
|
|
<doc xml:space="preserve">The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
|
|
entries representing applications.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_TYPE_DIRECTORY" value="Directory" c:type="G_KEY_FILE_DESKTOP_TYPE_DIRECTORY" version="2.14">
|
|
<doc xml:space="preserve">The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
|
|
entries representing directories.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="KEY_FILE_DESKTOP_TYPE_LINK" value="Link" c:type="G_KEY_FILE_DESKTOP_TYPE_LINK" version="2.14">
|
|
<doc xml:space="preserve">The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
|
|
entries representing links to documents.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<record name="KeyFile" c:type="GKeyFile" glib:type-name="GKeyFile" glib:get-type="g_key_file_get_type" c:symbol-prefix="key_file">
|
|
<doc xml:space="preserve">The GKeyFile struct contains only private data
|
|
and should not be accessed directly.</doc>
|
|
<constructor name="new" c:identifier="g_key_file_new" version="2.6">
|
|
<doc xml:space="preserve">Creates a new empty #GKeyFile object. Use
|
|
g_key_file_load_from_file(), g_key_file_load_from_data(),
|
|
g_key_file_load_from_dirs() or g_key_file_load_from_data_dirs() to
|
|
read an existing key file.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an empty #GKeyFile.</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</return-value>
|
|
</constructor>
|
|
<method name="free" c:identifier="g_key_file_free" version="2.6" introspectable="0">
|
|
<doc xml:space="preserve">Clears all keys and groups from @key_file, and decreases the
|
|
reference count by 1. If the reference count reaches zero,
|
|
frees the key file and all its allocated memory.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_boolean" c:identifier="g_key_file_get_boolean" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Returns the value associated with @key under @group_name as a
|
|
boolean.
|
|
|
|
If @key cannot be found then %FALSE is returned and @error is set
|
|
to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value
|
|
associated with @key cannot be interpreted as a boolean then %FALSE
|
|
is returned and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the value associated with the key as a boolean,
|
|
or %FALSE if the key was not found or could not be parsed.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_boolean_list" c:identifier="g_key_file_get_boolean_list" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Returns the values associated with @key under @group_name as
|
|
booleans.
|
|
|
|
If @key cannot be found then %NULL is returned and @error is set to
|
|
#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
|
|
with @key cannot be interpreted as booleans then %NULL is returned
|
|
and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.</doc>
|
|
<return-value transfer-ownership="container">
|
|
<doc xml:space="preserve">
|
|
the values associated with the key as a list of booleans, or %NULL if the
|
|
key was not found or could not be parsed. The returned list of booleans
|
|
should be freed with g_free() when no longer needed.</doc>
|
|
<array length="2" zero-terminated="0" c:type="gboolean*">
|
|
<type name="gboolean"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">the number of booleans returned</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_comment" c:identifier="g_key_file_get_comment" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Retrieves a comment above @key from @group_name.
|
|
If @key is %NULL then @comment will be read from above
|
|
@group_name. If both @key and @group_name are %NULL, then
|
|
@comment will be read from above the first group in the file.
|
|
|
|
Note that the returned string does not include the '#' comment markers,
|
|
but does include any whitespace after them (on each line). It includes
|
|
the line breaks between lines, but does not include the final line break.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a comment that should be freed with g_free()</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a group name, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_double" c:identifier="g_key_file_get_double" version="2.12" throws="1">
|
|
<doc xml:space="preserve">Returns the value associated with @key under @group_name as a
|
|
double. If @group_name is %NULL, the start_group is used.
|
|
|
|
If @key cannot be found then 0.0 is returned and @error is set to
|
|
#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated
|
|
with @key cannot be interpreted as a double then 0.0 is returned
|
|
and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the value associated with the key as a double, or
|
|
0.0 if the key was not found or could not be parsed.</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_double_list" c:identifier="g_key_file_get_double_list" version="2.12" throws="1">
|
|
<doc xml:space="preserve">Returns the values associated with @key under @group_name as
|
|
doubles.
|
|
|
|
If @key cannot be found then %NULL is returned and @error is set to
|
|
#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
|
|
with @key cannot be interpreted as doubles then %NULL is returned
|
|
and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.</doc>
|
|
<return-value transfer-ownership="container">
|
|
<doc xml:space="preserve">
|
|
the values associated with the key as a list of doubles, or %NULL if the
|
|
key was not found or could not be parsed. The returned list of doubles
|
|
should be freed with g_free() when no longer needed.</doc>
|
|
<array length="2" zero-terminated="0" c:type="gdouble*">
|
|
<type name="gdouble"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">the number of doubles returned</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_groups" c:identifier="g_key_file_get_groups" version="2.6">
|
|
<doc xml:space="preserve">Returns all groups in the key file loaded with @key_file.
|
|
The array of returned groups will be %NULL-terminated, so
|
|
@length may optionally be %NULL.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated %NULL-terminated array of strings.
|
|
Use g_strfreev() to free it.</doc>
|
|
<array c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the number of returned groups, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_int64" c:identifier="g_key_file_get_int64" version="2.26" throws="1">
|
|
<doc xml:space="preserve">Returns the value associated with @key under @group_name as a signed
|
|
64-bit integer. This is similar to g_key_file_get_integer() but can return
|
|
64-bit results without truncation.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the value associated with the key as a signed 64-bit integer, or
|
|
0 if the key was not found or could not be parsed.</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a non-%NULL #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a non-%NULL group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a non-%NULL key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_integer" c:identifier="g_key_file_get_integer" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Returns the value associated with @key under @group_name as an
|
|
integer.
|
|
|
|
If @key cannot be found then 0 is returned and @error is set to
|
|
#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated
|
|
with @key cannot be interpreted as an integer, or is out of range
|
|
for a #gint, then 0 is returned
|
|
and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the value associated with the key as an integer, or
|
|
0 if the key was not found or could not be parsed.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_integer_list" c:identifier="g_key_file_get_integer_list" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Returns the values associated with @key under @group_name as
|
|
integers.
|
|
|
|
If @key cannot be found then %NULL is returned and @error is set to
|
|
#G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
|
|
with @key cannot be interpreted as integers, or are out of range for
|
|
#gint, then %NULL is returned
|
|
and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.</doc>
|
|
<return-value transfer-ownership="container">
|
|
<doc xml:space="preserve">
|
|
the values associated with the key as a list of integers, or %NULL if
|
|
the key was not found or could not be parsed. The returned list of
|
|
integers should be freed with g_free() when no longer needed.</doc>
|
|
<array length="2" zero-terminated="0" c:type="gint*">
|
|
<type name="gint"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">the number of integers returned</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_keys" c:identifier="g_key_file_get_keys" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Returns all keys for the group name @group_name. The array of
|
|
returned keys will be %NULL-terminated, so @length may
|
|
optionally be %NULL. In the event that the @group_name cannot
|
|
be found, %NULL is returned and @error is set to
|
|
#G_KEY_FILE_ERROR_GROUP_NOT_FOUND.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated %NULL-terminated array of strings.
|
|
Use g_strfreev() to free it.</doc>
|
|
<array c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the number of keys returned, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_locale_for_key" c:identifier="g_key_file_get_locale_for_key" version="2.56">
|
|
<doc xml:space="preserve">Returns the actual locale which the result of
|
|
g_key_file_get_locale_string() or g_key_file_get_locale_string_list()
|
|
came from.
|
|
|
|
If calling g_key_file_get_locale_string() or
|
|
g_key_file_get_locale_string_list() with exactly the same @key_file,
|
|
@group_name, @key and @locale, the result of those functions will
|
|
have originally been tagged with the locale that is the result of
|
|
this function.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the locale from the file, or %NULL if the key was not
|
|
found or the entry in the file was was untranslated</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="locale" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a locale identifier or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_locale_string" c:identifier="g_key_file_get_locale_string" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Returns the value associated with @key under @group_name
|
|
translated in the given @locale if available. If @locale is
|
|
%NULL then the current locale is assumed.
|
|
|
|
If @locale is to be non-%NULL, or if the current locale will change over
|
|
the lifetime of the #GKeyFile, it must be loaded with
|
|
%G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales.
|
|
|
|
If @key cannot be found then %NULL is returned and @error is set
|
|
to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the value associated
|
|
with @key cannot be interpreted or no suitable translation can
|
|
be found then the untranslated value is returned.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string or %NULL if the specified
|
|
key cannot be found.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="locale" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a locale identifier or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_locale_string_list" c:identifier="g_key_file_get_locale_string_list" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Returns the values associated with @key under @group_name
|
|
translated in the given @locale if available. If @locale is
|
|
%NULL then the current locale is assumed.
|
|
|
|
If @locale is to be non-%NULL, or if the current locale will change over
|
|
the lifetime of the #GKeyFile, it must be loaded with
|
|
%G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales.
|
|
|
|
If @key cannot be found then %NULL is returned and @error is set
|
|
to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the values associated
|
|
with @key cannot be interpreted or no suitable translations
|
|
can be found then the untranslated values are returned. The
|
|
returned array is %NULL-terminated, so @length may optionally
|
|
be %NULL.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated %NULL-terminated string array
|
|
or %NULL if the key isn't found. The string array should be freed
|
|
with g_strfreev().</doc>
|
|
<array length="3" zero-terminated="1" c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="locale" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a locale identifier or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the number of returned strings or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_start_group" c:identifier="g_key_file_get_start_group" version="2.6">
|
|
<doc xml:space="preserve">Returns the name of the start group of the file.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">The start group of the key file.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_string" c:identifier="g_key_file_get_string" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Returns the string value associated with @key under @group_name.
|
|
Unlike g_key_file_get_value(), this function handles escape sequences
|
|
like \s.
|
|
|
|
In the event the key cannot be found, %NULL is returned and
|
|
@error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
|
|
event that the @group_name cannot be found, %NULL is returned
|
|
and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string or %NULL if the specified
|
|
key cannot be found.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_string_list" c:identifier="g_key_file_get_string_list" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Returns the values associated with @key under @group_name.
|
|
|
|
In the event the key cannot be found, %NULL is returned and
|
|
@error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
|
|
event that the @group_name cannot be found, %NULL is returned
|
|
and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">
|
|
a %NULL-terminated string array or %NULL if the specified
|
|
key cannot be found. The array should be freed with g_strfreev().</doc>
|
|
<array length="2" zero-terminated="1" c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the number of returned strings, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_uint64" c:identifier="g_key_file_get_uint64" version="2.26" throws="1">
|
|
<doc xml:space="preserve">Returns the value associated with @key under @group_name as an unsigned
|
|
64-bit integer. This is similar to g_key_file_get_integer() but can return
|
|
large positive results without truncation.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the value associated with the key as an unsigned 64-bit integer,
|
|
or 0 if the key was not found or could not be parsed.</doc>
|
|
<type name="guint64" c:type="guint64"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a non-%NULL #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a non-%NULL group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a non-%NULL key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_value" c:identifier="g_key_file_get_value" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Returns the raw value associated with @key under @group_name.
|
|
Use g_key_file_get_string() to retrieve an unescaped UTF-8 string.
|
|
|
|
In the event the key cannot be found, %NULL is returned and
|
|
@error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
|
|
event that the @group_name cannot be found, %NULL is returned
|
|
and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string or %NULL if the specified
|
|
key cannot be found.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="has_group" c:identifier="g_key_file_has_group" version="2.6">
|
|
<doc xml:space="preserve">Looks whether the key file has the group @group_name.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @group_name is a part of @key_file, %FALSE
|
|
otherwise.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="has_key" c:identifier="g_key_file_has_key" version="2.6" introspectable="0" throws="1">
|
|
<doc xml:space="preserve">Looks whether the key file has the key @key in the group
|
|
@group_name.
|
|
|
|
Note that this function does not follow the rules for #GError strictly;
|
|
the return value both carries meaning and signals an error. To use
|
|
this function, you must pass a #GError pointer in @error, and check
|
|
whether it is not %NULL to see if an error occurred.
|
|
|
|
Language bindings should use g_key_file_get_value() to test whether
|
|
or not a key exists.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @key is a part of @group_name, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="load_from_bytes" c:identifier="g_key_file_load_from_bytes" version="2.50" throws="1">
|
|
<doc xml:space="preserve">Loads a key file from the data in @bytes into an empty #GKeyFile structure.
|
|
If the object cannot be created then %error is set to a #GKeyFileError.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a key file could be loaded, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">an empty #GKeyFile struct</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBytes</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags from #GKeyFileFlags</doc>
|
|
<type name="KeyFileFlags" c:type="GKeyFileFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="load_from_data" c:identifier="g_key_file_load_from_data" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Loads a key file from memory into an empty #GKeyFile structure.
|
|
If the object cannot be created then %error is set to a #GKeyFileError.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a key file could be loaded, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">an empty #GKeyFile struct</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none">
|
|
<doc xml:space="preserve">key file loaded in memory</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @data in bytes (or (gsize)-1 if data is nul-terminated)</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags from #GKeyFileFlags</doc>
|
|
<type name="KeyFileFlags" c:type="GKeyFileFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="load_from_data_dirs" c:identifier="g_key_file_load_from_data_dirs" version="2.6" throws="1">
|
|
<doc xml:space="preserve">This function looks for a key file named @file in the paths
|
|
returned from g_get_user_data_dir() and g_get_system_data_dirs(),
|
|
loads the file into @key_file and returns the file's full path in
|
|
@full_path. If the file could not be loaded then an %error is
|
|
set to either a #GFileError or #GKeyFileError.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a key file could be loaded, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">an empty #GKeyFile struct</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a relative path to a filename to open and parse</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="full_path" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for a string containing the full path
|
|
of the file, or %NULL</doc>
|
|
<type name="filename" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags from #GKeyFileFlags</doc>
|
|
<type name="KeyFileFlags" c:type="GKeyFileFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="load_from_dirs" c:identifier="g_key_file_load_from_dirs" version="2.14" throws="1">
|
|
<doc xml:space="preserve">This function looks for a key file named @file in the paths
|
|
specified in @search_dirs, loads the file into @key_file and
|
|
returns the file's full path in @full_path.
|
|
|
|
If the file could not be found in any of the @search_dirs,
|
|
%G_KEY_FILE_ERROR_NOT_FOUND is returned. If
|
|
the file is found but the OS returns an error when opening or reading the
|
|
file, a %G_FILE_ERROR is returned. If there is a problem parsing the file, a
|
|
%G_KEY_FILE_ERROR is returned.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a key file could be loaded, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">an empty #GKeyFile struct</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a relative path to a filename to open and parse</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="search_dirs" transfer-ownership="none">
|
|
<doc xml:space="preserve">%NULL-terminated array of directories to search</doc>
|
|
<array c:type="const gchar**">
|
|
<type name="filename"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="full_path" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for a string containing the full path
|
|
of the file, or %NULL</doc>
|
|
<type name="filename" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags from #GKeyFileFlags</doc>
|
|
<type name="KeyFileFlags" c:type="GKeyFileFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="load_from_file" c:identifier="g_key_file_load_from_file" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Loads a key file into an empty #GKeyFile structure.
|
|
|
|
If the OS returns an error when opening or reading the file, a
|
|
%G_FILE_ERROR is returned. If there is a problem parsing the file, a
|
|
%G_KEY_FILE_ERROR is returned.
|
|
|
|
This function will never return a %G_KEY_FILE_ERROR_NOT_FOUND error. If the
|
|
@file is not found, %G_FILE_ERROR_NOENT is returned.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a key file could be loaded, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">an empty #GKeyFile struct</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="file" transfer-ownership="none">
|
|
<doc xml:space="preserve">the path of a filename to load, in the GLib filename encoding</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags from #GKeyFileFlags</doc>
|
|
<type name="KeyFileFlags" c:type="GKeyFileFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_key_file_ref" version="2.32" introspectable="0">
|
|
<doc xml:space="preserve">Increases the reference count of @key_file.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the same @key_file.</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="remove_comment" c:identifier="g_key_file_remove_comment" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Removes a comment above @key from @group_name.
|
|
If @key is %NULL then @comment will be removed above @group_name.
|
|
If both @key and @group_name are %NULL, then @comment will
|
|
be removed above the first group in the file.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the comment was removed, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a group name, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="remove_group" c:identifier="g_key_file_remove_group" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Removes the specified group, @group_name,
|
|
from the key file.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the group was removed, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="remove_key" c:identifier="g_key_file_remove_key" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Removes @key in @group_name from the key file.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key was removed, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key name to remove</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="save_to_file" c:identifier="g_key_file_save_to_file" version="2.40" throws="1">
|
|
<doc xml:space="preserve">Writes the contents of @key_file to @filename using
|
|
g_file_set_contents(). If you need stricter guarantees about durability of
|
|
the written file than are provided by g_file_set_contents(), use
|
|
g_file_set_contents_full() with the return value of g_key_file_to_data().
|
|
|
|
This function can fail for any of the reasons that
|
|
g_file_set_contents() may fail.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if successful, else %FALSE with @error set</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="filename" transfer-ownership="none">
|
|
<doc xml:space="preserve">the name of the file to write to</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_boolean" c:identifier="g_key_file_set_boolean" version="2.6">
|
|
<doc xml:space="preserve">Associates a new boolean value with @key under @group_name.
|
|
If @key cannot be found then it is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE or %FALSE</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_boolean_list" c:identifier="g_key_file_set_boolean_list" version="2.6">
|
|
<doc xml:space="preserve">Associates a list of boolean values with @key under @group_name.
|
|
If @key cannot be found then it is created.
|
|
If @group_name is %NULL, the start_group is used.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array of boolean values</doc>
|
|
<array length="3" zero-terminated="0" c:type="gboolean*">
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @list</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_comment" c:identifier="g_key_file_set_comment" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Places a comment above @key from @group_name.
|
|
|
|
If @key is %NULL then @comment will be written above @group_name.
|
|
If both @key and @group_name are %NULL, then @comment will be
|
|
written above the first group in the file.
|
|
|
|
Note that this function prepends a '#' comment marker to
|
|
each line of @comment.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the comment was written, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a group name, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="comment" transfer-ownership="none">
|
|
<doc xml:space="preserve">a comment</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_double" c:identifier="g_key_file_set_double" version="2.12">
|
|
<doc xml:space="preserve">Associates a new double value with @key under @group_name.
|
|
If @key cannot be found then it is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a double value</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_double_list" c:identifier="g_key_file_set_double_list" version="2.12">
|
|
<doc xml:space="preserve">Associates a list of double values with @key under
|
|
@group_name. If @key cannot be found then it is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array of double values</doc>
|
|
<array length="3" zero-terminated="0" c:type="gdouble*">
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of double values in @list</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_int64" c:identifier="g_key_file_set_int64" version="2.26">
|
|
<doc xml:space="preserve">Associates a new integer value with @key under @group_name.
|
|
If @key cannot be found then it is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">an integer value</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_integer" c:identifier="g_key_file_set_integer" version="2.6">
|
|
<doc xml:space="preserve">Associates a new integer value with @key under @group_name.
|
|
If @key cannot be found then it is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">an integer value</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_integer_list" c:identifier="g_key_file_set_integer_list" version="2.6">
|
|
<doc xml:space="preserve">Associates a list of integer values with @key under @group_name.
|
|
If @key cannot be found then it is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array of integer values</doc>
|
|
<array length="3" zero-terminated="0" c:type="gint*">
|
|
<type name="gint" c:type="gint"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of integer values in @list</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_list_separator" c:identifier="g_key_file_set_list_separator" version="2.6">
|
|
<doc xml:space="preserve">Sets the character which is used to separate
|
|
values in lists. Typically ';' or ',' are used
|
|
as separators. The default list separator is ';'.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="separator" transfer-ownership="none">
|
|
<doc xml:space="preserve">the separator</doc>
|
|
<type name="gchar" c:type="gchar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_locale_string" c:identifier="g_key_file_set_locale_string" version="2.6">
|
|
<doc xml:space="preserve">Associates a string value for @key and @locale under @group_name.
|
|
If the translation for @key cannot be found then it is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="locale" transfer-ownership="none">
|
|
<doc xml:space="preserve">a locale identifier</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_locale_string_list" c:identifier="g_key_file_set_locale_string_list" version="2.6">
|
|
<doc xml:space="preserve">Associates a list of string values for @key and @locale under
|
|
@group_name. If the translation for @key cannot be found then
|
|
it is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="locale" transfer-ownership="none">
|
|
<doc xml:space="preserve">a locale identifier</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a %NULL-terminated array of locale string values</doc>
|
|
<array length="4" zero-terminated="1" c:type="const gchar* const*">
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @list</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_string" c:identifier="g_key_file_set_string" version="2.6">
|
|
<doc xml:space="preserve">Associates a new string value with @key under @group_name.
|
|
If @key cannot be found then it is created.
|
|
If @group_name cannot be found then it is created.
|
|
Unlike g_key_file_set_value(), this function handles characters
|
|
that need escaping, such as newlines.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_string_list" c:identifier="g_key_file_set_string_list" version="2.6">
|
|
<doc xml:space="preserve">Associates a list of string values for @key under @group_name.
|
|
If @key cannot be found then it is created.
|
|
If @group_name cannot be found then it is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array of string values</doc>
|
|
<array length="3" zero-terminated="1" c:type="const gchar* const*">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of string values in @list</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_uint64" c:identifier="g_key_file_set_uint64" version="2.26">
|
|
<doc xml:space="preserve">Associates a new integer value with @key under @group_name.
|
|
If @key cannot be found then it is created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">an integer value</doc>
|
|
<type name="guint64" c:type="guint64"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_value" c:identifier="g_key_file_set_value" version="2.6">
|
|
<doc xml:space="preserve">Associates a new value with @key under @group_name.
|
|
|
|
If @key cannot be found then it is created. If @group_name cannot
|
|
be found then it is created. To set an UTF-8 string which may contain
|
|
characters that need escaping (such as newlines or spaces), use
|
|
g_key_file_set_string().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="group_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a group name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="to_data" c:identifier="g_key_file_to_data" version="2.6" throws="1">
|
|
<doc xml:space="preserve">This function outputs @key_file as a string.
|
|
|
|
Note that this function never reports an error,
|
|
so it is safe to pass %NULL as @error.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string holding
|
|
the contents of the #GKeyFile</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the length of the
|
|
returned string, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_key_file_unref" version="2.32">
|
|
<doc xml:space="preserve">Decreases the reference count of @key_file by 1. If the reference count
|
|
reaches zero, frees the key file and all its allocated memory.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key_file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GKeyFile</doc>
|
|
<type name="KeyFile" c:type="GKeyFile*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="error_quark" c:identifier="g_key_file_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
</record>
|
|
<enumeration name="KeyFileError" c:type="GKeyFileError" glib:error-domain="g-key-file-error-quark">
|
|
<doc xml:space="preserve">Error codes returned by key file parsing.</doc>
|
|
<member name="unknown_encoding" value="0" c:identifier="G_KEY_FILE_ERROR_UNKNOWN_ENCODING">
|
|
<doc xml:space="preserve">the text being parsed was in
|
|
an unknown encoding</doc>
|
|
</member>
|
|
<member name="parse" value="1" c:identifier="G_KEY_FILE_ERROR_PARSE">
|
|
<doc xml:space="preserve">document was ill-formed</doc>
|
|
</member>
|
|
<member name="not_found" value="2" c:identifier="G_KEY_FILE_ERROR_NOT_FOUND">
|
|
<doc xml:space="preserve">the file was not found</doc>
|
|
</member>
|
|
<member name="key_not_found" value="3" c:identifier="G_KEY_FILE_ERROR_KEY_NOT_FOUND">
|
|
<doc xml:space="preserve">a requested key was not found</doc>
|
|
</member>
|
|
<member name="group_not_found" value="4" c:identifier="G_KEY_FILE_ERROR_GROUP_NOT_FOUND">
|
|
<doc xml:space="preserve">a requested group was not found</doc>
|
|
</member>
|
|
<member name="invalid_value" value="5" c:identifier="G_KEY_FILE_ERROR_INVALID_VALUE">
|
|
<doc xml:space="preserve">a value could not be parsed</doc>
|
|
</member>
|
|
</enumeration>
|
|
<bitfield name="KeyFileFlags" c:type="GKeyFileFlags">
|
|
<doc xml:space="preserve">Flags which influence the parsing.</doc>
|
|
<member name="none" value="0" c:identifier="G_KEY_FILE_NONE">
|
|
<doc xml:space="preserve">No flags, default behaviour</doc>
|
|
</member>
|
|
<member name="keep_comments" value="1" c:identifier="G_KEY_FILE_KEEP_COMMENTS">
|
|
<doc xml:space="preserve">Use this flag if you plan to write the
|
|
(possibly modified) contents of the key file back to a file;
|
|
otherwise all comments will be lost when the key file is
|
|
written back.</doc>
|
|
</member>
|
|
<member name="keep_translations" value="2" c:identifier="G_KEY_FILE_KEEP_TRANSLATIONS">
|
|
<doc xml:space="preserve">Use this flag if you plan to write the
|
|
(possibly modified) contents of the key file back to a file;
|
|
otherwise only the translations for the current language will be
|
|
written back.</doc>
|
|
</member>
|
|
</bitfield>
|
|
<function-macro name="LIKELY" c:identifier="G_LIKELY" version="2.2" introspectable="0">
|
|
<doc xml:space="preserve">Hints the compiler that the expression is likely to evaluate to
|
|
a true value. The compiler may use this information for optimizations.
|
|
|
|
|[<!-- language="C" -->
|
|
if (G_LIKELY (random () != 1))
|
|
g_print ("not one");
|
|
]|</doc>
|
|
<parameters>
|
|
<parameter name="expr">
|
|
<doc xml:space="preserve">the expression</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="LITTLE_ENDIAN" value="1234" c:type="G_LITTLE_ENDIAN">
|
|
<doc xml:space="preserve">Specifies one of the possible types of byte order.
|
|
See #G_BYTE_ORDER.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="LN10" value="2.302585" c:type="G_LN10">
|
|
<doc xml:space="preserve">The natural logarithm of 10.</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</constant>
|
|
<constant name="LN2" value="0.693147" c:type="G_LN2">
|
|
<doc xml:space="preserve">The natural logarithm of 2.</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</constant>
|
|
<function-macro name="LOCK" c:identifier="G_LOCK" introspectable="0">
|
|
<doc xml:space="preserve">Works like g_mutex_lock(), but for a lock defined with
|
|
#G_LOCK_DEFINE.</doc>
|
|
<parameters>
|
|
<parameter name="name">
|
|
<doc xml:space="preserve">the name of the lock</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="LOCK_DEFINE" c:identifier="G_LOCK_DEFINE" introspectable="0">
|
|
<doc xml:space="preserve">The #G_LOCK_ macros provide a convenient interface to #GMutex.
|
|
#G_LOCK_DEFINE defines a lock. It can appear in any place where
|
|
variable definitions may appear in programs, i.e. in the first block
|
|
of a function or outside of functions. The @name parameter will be
|
|
mangled to get the name of the #GMutex. This means that you
|
|
can use names of existing variables as the parameter - e.g. the name
|
|
of the variable you intend to protect with the lock. Look at our
|
|
give_me_next_number() example using the #G_LOCK macros:
|
|
|
|
Here is an example for using the #G_LOCK convenience macros:
|
|
|[<!-- language="C" -->
|
|
G_LOCK_DEFINE (current_number);
|
|
|
|
int
|
|
give_me_next_number (void)
|
|
{
|
|
static int current_number = 0;
|
|
int ret_val;
|
|
|
|
G_LOCK (current_number);
|
|
ret_val = current_number = calc_next_number (current_number);
|
|
G_UNLOCK (current_number);
|
|
|
|
return ret_val;
|
|
}
|
|
]|</doc>
|
|
<parameters>
|
|
<parameter name="name">
|
|
<doc xml:space="preserve">the name of the lock</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="LOCK_DEFINE_STATIC" c:identifier="G_LOCK_DEFINE_STATIC" introspectable="0">
|
|
<doc xml:space="preserve">This works like #G_LOCK_DEFINE, but it creates a static object.</doc>
|
|
<parameters>
|
|
<parameter name="name">
|
|
<doc xml:space="preserve">the name of the lock</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="LOCK_EXTERN" c:identifier="G_LOCK_EXTERN" introspectable="0">
|
|
<doc xml:space="preserve">This declares a lock, that is defined with #G_LOCK_DEFINE in another
|
|
module.</doc>
|
|
<parameters>
|
|
<parameter name="name">
|
|
<doc xml:space="preserve">the name of the lock</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="LOCK_NAME" c:identifier="G_LOCK_NAME" introspectable="0">
|
|
<parameters>
|
|
<parameter name="name">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="LOG_2_BASE_10" value="0.301030" c:type="G_LOG_2_BASE_10">
|
|
<doc xml:space="preserve">Multiplying the base 2 exponent by this number yields the base 10 exponent.</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</constant>
|
|
<constant name="LOG_DOMAIN" value="0" c:type="G_LOG_DOMAIN">
|
|
<doc xml:space="preserve">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.
|
|
|
|
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 `""`)
|
|
domain. However, defining the domain offers the same advantages as
|
|
above.</doc>
|
|
<type name="gchar" c:type="gchar"/>
|
|
</constant>
|
|
<constant name="LOG_FATAL_MASK" value="5" c:type="G_LOG_FATAL_MASK">
|
|
<doc xml:space="preserve">GLib log levels that are considered fatal by default.
|
|
|
|
This is not used if structured logging is enabled; see
|
|
[Using Structured Logging][using-structured-logging].</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="LOG_LEVEL_USER_SHIFT" value="8" c:type="G_LOG_LEVEL_USER_SHIFT">
|
|
<doc xml:space="preserve">Log levels below 1<<G_LOG_LEVEL_USER_SHIFT are used by GLib.
|
|
Higher bits can be used for user-defined log levels.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<record name="List" c:type="GList">
|
|
<doc xml:space="preserve">The #GList struct is used for each element in a doubly-linked list.</doc>
|
|
<field name="data" writable="1">
|
|
<doc xml:space="preserve">holds the element's data, which can be a pointer to any kind
|
|
of data, or any integer value using the
|
|
[Type Conversion Macros][glib-Type-Conversion-Macros]</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="next" writable="1">
|
|
<doc xml:space="preserve">contains the link to the next element in the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</field>
|
|
<field name="prev" writable="1">
|
|
<doc xml:space="preserve">contains the link to the previous element in the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</field>
|
|
<function name="alloc" c:identifier="g_list_alloc" introspectable="0">
|
|
<doc xml:space="preserve">Allocates space for one #GList element. It is called by
|
|
g_list_append(), g_list_prepend(), g_list_insert() and
|
|
g_list_insert_sorted() and so is rarely used on its own.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a pointer to the newly-allocated #GList element</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
</function>
|
|
<function name="append" c:identifier="g_list_append" introspectable="0">
|
|
<doc xml:space="preserve">Adds a new element on to the end of the list.
|
|
|
|
Note that the return value is the new start of the list,
|
|
if @list was empty; make sure you store the new value.
|
|
|
|
g_list_append() has to traverse the entire list to find the end,
|
|
which is inefficient when adding multiple elements. A common idiom
|
|
to avoid the inefficiency is to use g_list_prepend() and reverse
|
|
the list with g_list_reverse() when all elements have been added.
|
|
|
|
|[<!-- language="C" -->
|
|
// Notice that these are initialized to the empty list.
|
|
GList *string_list = NULL, *number_list = NULL;
|
|
|
|
// This is a list of strings.
|
|
string_list = g_list_append (string_list, "first");
|
|
string_list = g_list_append (string_list, "second");
|
|
|
|
// This is a list of integers.
|
|
number_list = g_list_append (number_list, GINT_TO_POINTER (27));
|
|
number_list = g_list_append (number_list, GINT_TO_POINTER (14));
|
|
]|</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">either @list or the new start of the #GList if @list was %NULL</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new element</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="concat" c:identifier="g_list_concat" introspectable="0">
|
|
<doc xml:space="preserve">Adds the second #GList onto the end of the first #GList.
|
|
Note that the elements of the second #GList are not copied.
|
|
They are used directly.
|
|
|
|
This function is for example used to move an element in the list.
|
|
The following example moves an element to the top of the list:
|
|
|[<!-- language="C" -->
|
|
list = g_list_remove_link (list, llink);
|
|
list = g_list_concat (llink, list);
|
|
]|</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the start of the new #GList, which equals @list1 if not %NULL</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="list2" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GList to add to the end of the first #GList,
|
|
this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="copy" c:identifier="g_list_copy" introspectable="0">
|
|
<doc xml:space="preserve">Copies a #GList.
|
|
|
|
Note that this is a "shallow" copy. If the list elements
|
|
consist of pointers to data, the pointers are copied but
|
|
the actual data is not. See g_list_copy_deep() if you need
|
|
to copy the data as well.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the start of the new list that holds the same data as @list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="copy_deep" c:identifier="g_list_copy_deep" version="2.34" introspectable="0">
|
|
<doc xml:space="preserve">Makes a full (deep) copy of a #GList.
|
|
|
|
In contrast with g_list_copy(), this function uses @func to make
|
|
a copy of each list element, in addition to copying the list
|
|
container itself.
|
|
|
|
@func, as a #GCopyFunc, takes two arguments, the data to be copied
|
|
and a @user_data pointer. On common processor architectures, it's safe to
|
|
pass %NULL as @user_data if the copy function takes only one argument. You
|
|
may get compiler warnings from this though if compiling with GCC’s
|
|
`-Wcast-function-type` warning.
|
|
|
|
For instance, if @list holds a list of GObjects, you can do:
|
|
|[<!-- language="C" -->
|
|
another_list = g_list_copy_deep (list, (GCopyFunc) g_object_ref, NULL);
|
|
]|
|
|
|
|
And, to entirely free the new list, you could do:
|
|
|[<!-- language="C" -->
|
|
g_list_free_full (another_list, g_object_unref);
|
|
]|</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the start of the new list that holds a full copy of @list,
|
|
use g_list_free_full() to free it</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">a copy function used to copy every element in the list</doc>
|
|
<type name="CopyFunc" c:type="GCopyFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to the copy function @func, or %NULL</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="delete_link" c:identifier="g_list_delete_link" introspectable="0">
|
|
<doc xml:space="preserve">Removes the node link_ from the list and frees it.
|
|
Compare this to g_list_remove_link() which removes the node
|
|
without freeing it.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the (possibly changed) start of the #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="link_" transfer-ownership="none">
|
|
<doc xml:space="preserve">node to delete from @list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="find" c:identifier="g_list_find" introspectable="0">
|
|
<doc xml:space="preserve">Finds the element in a #GList which contains the given data.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the found #GList element, or %NULL if it is not found</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the element data to find</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="find_custom" c:identifier="g_list_find_custom" introspectable="0">
|
|
<doc xml:space="preserve">Finds an element in a #GList, using a supplied function to
|
|
find the desired element. It iterates over the list, calling
|
|
the given function which should return 0 when the desired
|
|
element is found. The function takes two #gconstpointer arguments,
|
|
the #GList element's data as the first argument and the
|
|
given user data.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the found #GList element, or %NULL if it is not found</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to the function</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<doc xml:space="preserve">the function to call for each element.
|
|
It should return 0 when the desired element is found</doc>
|
|
<type name="CompareFunc" c:type="GCompareFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="first" c:identifier="g_list_first" introspectable="0">
|
|
<doc xml:space="preserve">Gets the first element in a #GList.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the first element in the #GList,
|
|
or %NULL if the #GList has no elements</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">any #GList element</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="foreach" c:identifier="g_list_foreach" introspectable="0">
|
|
<doc xml:space="preserve">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.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function to call with each element's data</doc>
|
|
<type name="Func" c:type="GFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to the function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="free" c:identifier="g_list_free" introspectable="0">
|
|
<doc xml:space="preserve">Frees all of the memory used by a #GList.
|
|
The freed elements are returned to the slice allocator.
|
|
|
|
If list elements contain dynamically-allocated memory, you should
|
|
either use g_list_free_full() or free them manually first.
|
|
|
|
It can be combined with g_steal_pointer() to ensure the list head pointer
|
|
is not left dangling:
|
|
|[<!-- language="C" -->
|
|
GList *list_of_borrowed_things = …; /<!-- -->* (transfer container) *<!-- -->/
|
|
g_list_free (g_steal_pointer (&list_of_borrowed_things));
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="free_1" c:identifier="g_list_free_1" introspectable="0">
|
|
<doc xml:space="preserve">Frees one #GList element, but does not update links from the next and
|
|
previous elements in the list, so you should not call this function on an
|
|
element that is currently part of a list.
|
|
|
|
It is usually used after g_list_remove_link().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList element</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="free_full" c:identifier="g_list_free_full" version="2.28" introspectable="0">
|
|
<doc xml:space="preserve">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).
|
|
|
|
It can be combined with g_steal_pointer() to ensure the list head pointer
|
|
is not left dangling ­— this also has the nice property that the head pointer
|
|
is cleared before any of the list elements are freed, to prevent double frees
|
|
from @free_func:
|
|
|[<!-- language="C" -->
|
|
GList *list_of_owned_things = …; /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/
|
|
g_list_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref);
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="free_func" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">the function to be called to free each element's data</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="index" c:identifier="g_list_index" introspectable="0">
|
|
<doc xml:space="preserve">Gets the position of the element containing
|
|
the given data (starting from 0).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the element containing the data,
|
|
or -1 if the data is not found</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to find</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="insert" c:identifier="g_list_insert" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a new element into the list at the given position.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the (possibly changed) start of the #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new element</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="position" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position to insert the element. If this is
|
|
negative, or is larger than the number of elements in the
|
|
list, the new element is added on to the end of the list.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="insert_before" c:identifier="g_list_insert_before" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a new element into the list before the given position.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the (possibly changed) start of the #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="sibling" transfer-ownership="none">
|
|
<doc xml:space="preserve">the list element before which the new element
|
|
is inserted or %NULL to insert at the end of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new element</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="insert_before_link" c:identifier="g_list_insert_before_link" version="2.62" introspectable="0">
|
|
<doc xml:space="preserve">Inserts @link_ into the list before the given position.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the (possibly changed) start of the #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="sibling" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the list element before which the new element
|
|
is inserted or %NULL to insert at the end of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="link_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the list element to be added, which must not be part of
|
|
any other list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="insert_sorted" c:identifier="g_list_insert_sorted" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a new element into the list, using the given comparison
|
|
function to determine its position.
|
|
|
|
If you are adding many new elements to a list, and the number of
|
|
new elements is much larger than the length of the list, use
|
|
g_list_prepend() to add the new items and sort the list afterwards
|
|
with g_list_sort().</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the (possibly changed) start of the #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GList, this must point to the top of the
|
|
already sorted list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new element</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<doc xml:space="preserve">the function to compare elements in the list. It should
|
|
return a number > 0 if the first parameter comes after the
|
|
second parameter in the sort order.</doc>
|
|
<type name="CompareFunc" c:type="GCompareFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="insert_sorted_with_data" c:identifier="g_list_insert_sorted_with_data" version="2.10" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a new element into the list, using the given comparison
|
|
function to determine its position.
|
|
|
|
If you are adding many new elements to a list, and the number of
|
|
new elements is much larger than the length of the list, use
|
|
g_list_prepend() to add the new items and sort the list afterwards
|
|
with g_list_sort().</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the (possibly changed) start of the #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GList, this must point to the top of the
|
|
already sorted list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new element</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="3">
|
|
<doc xml:space="preserve">the function to compare elements in the list. It should
|
|
return a number > 0 if the first parameter comes after the
|
|
second parameter in the sort order.</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to comparison function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="last" c:identifier="g_list_last" introspectable="0">
|
|
<doc xml:space="preserve">Gets the last element in a #GList.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the last element in the #GList,
|
|
or %NULL if the #GList has no elements</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">any #GList element</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="length" c:identifier="g_list_length" introspectable="0">
|
|
<doc xml:space="preserve">Gets the number of elements in a #GList.
|
|
|
|
This function iterates over the whole list to count its elements.
|
|
Use a #GQueue instead of a GList if you regularly need the number
|
|
of items. To check whether the list is non-empty, it is faster to check
|
|
@list against %NULL.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of elements in the #GList</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="nth" c:identifier="g_list_nth" introspectable="0">
|
|
<doc xml:space="preserve">Gets the element at the given position in a #GList.
|
|
|
|
This iterates over the list until it reaches the @n-th position. If you
|
|
intend to iterate over every element, it is better to use a for-loop as
|
|
described in the #GList introduction.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the element, or %NULL if the position is off
|
|
the end of the #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position of the element, counting from 0</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="nth_data" c:identifier="g_list_nth_data" introspectable="0">
|
|
<doc xml:space="preserve">Gets the data of the element at the given position.
|
|
|
|
This iterates over the list until it reaches the @n-th position. If you
|
|
intend to iterate over every element, it is better to use a for-loop as
|
|
described in the #GList introduction.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the element's data, or %NULL if the position
|
|
is off the end of the #GList</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position of the element</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="nth_prev" c:identifier="g_list_nth_prev" introspectable="0">
|
|
<doc xml:space="preserve">Gets the element @n places before @list.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the element, or %NULL if the position is
|
|
off the end of the #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position of the element, counting from 0</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="position" c:identifier="g_list_position" introspectable="0">
|
|
<doc xml:space="preserve">Gets the position of the given element
|
|
in the #GList (starting from 0).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the position of the element in the #GList,
|
|
or -1 if the element is not found</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="llink" transfer-ownership="none">
|
|
<doc xml:space="preserve">an element in the #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="prepend" c:identifier="g_list_prepend" introspectable="0">
|
|
<doc xml:space="preserve">Prepends a new element on to the start of the list.
|
|
|
|
Note that the return value is the new start of the list,
|
|
which will have changed, so make sure you store the new value.
|
|
|
|
|[<!-- language="C" -->
|
|
// Notice that it is initialized to the empty list.
|
|
GList *list = NULL;
|
|
|
|
list = g_list_prepend (list, "last");
|
|
list = g_list_prepend (list, "first");
|
|
]|
|
|
|
|
Do not use this function to prepend a new element to a different
|
|
element than the start of the list. Use g_list_insert_before() instead.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a pointer to the newly prepended element, which is the new
|
|
start of the #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new element</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove" c:identifier="g_list_remove" introspectable="0">
|
|
<doc xml:space="preserve">Removes an element from a #GList.
|
|
If two elements contain the same data, only the first is removed.
|
|
If none of the elements contain the data, the #GList is unchanged.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the (possibly changed) start of the #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data of the element to remove</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_all" c:identifier="g_list_remove_all" introspectable="0">
|
|
<doc xml:space="preserve">Removes all list nodes with data equal to @data.
|
|
Returns the new head of the list. Contrast with
|
|
g_list_remove() which removes only the first node
|
|
matching the given data.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the (possibly changed) start of the #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to remove</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_link" c:identifier="g_list_remove_link" introspectable="0">
|
|
<doc xml:space="preserve">Removes an element from a #GList, without freeing the element.
|
|
The removed element's prev and next links are set to %NULL, so
|
|
that it becomes a self-contained list with one element.
|
|
|
|
This function is for example used to move an element in the list
|
|
(see the example for g_list_concat()) or to remove an element in
|
|
the list before freeing its data:
|
|
|[<!-- language="C" -->
|
|
list = g_list_remove_link (list, llink);
|
|
free_some_data_that_may_access_the_list_again (llink->data);
|
|
g_list_free (llink);
|
|
]|</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the (possibly changed) start of the #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="llink" transfer-ownership="none">
|
|
<doc xml:space="preserve">an element in the #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="reverse" c:identifier="g_list_reverse" introspectable="0">
|
|
<doc xml:space="preserve">Reverses a #GList.
|
|
It simply switches the next and prev pointers of each element.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the start of the reversed #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sort" c:identifier="g_list_sort" introspectable="0">
|
|
<doc xml:space="preserve">Sorts a #GList using the given comparison function. The algorithm
|
|
used is a stable sort.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the (possibly changed) start of the #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="compare_func" transfer-ownership="none">
|
|
<doc xml:space="preserve">the comparison function used to sort the #GList.
|
|
This function is passed the data from 2 elements of the #GList
|
|
and should return 0 if they are equal, a negative value if the
|
|
first element comes before the second, or a positive value if
|
|
the first element comes after the second.</doc>
|
|
<type name="CompareFunc" c:type="GCompareFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sort_with_data" c:identifier="g_list_sort_with_data" introspectable="0">
|
|
<doc xml:space="preserve">Like g_list_sort(), but the comparison function accepts
|
|
a user data argument.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the (possibly changed) start of the #GList</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList, this must point to the top of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="compare_func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">comparison function</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to comparison function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<record name="LogField" c:type="GLogField" version="2.50">
|
|
<doc xml:space="preserve">Structure representing a single field in a structured log entry. See
|
|
g_log_structured() for details.
|
|
|
|
Log fields may contain arbitrary values, including binary with embedded nul
|
|
bytes. If the field contains a string, the string must be UTF-8 encoded and
|
|
have a trailing nul byte. Otherwise, @length must be set to a non-negative
|
|
value.</doc>
|
|
<field name="key" writable="1">
|
|
<doc xml:space="preserve">field name (UTF-8 string)</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</field>
|
|
<field name="value" writable="1">
|
|
<doc xml:space="preserve">field value (arbitrary bytes)</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</field>
|
|
<field name="length" writable="1">
|
|
<doc xml:space="preserve">length of @value, in bytes, or -1 if it is nul-terminated</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</field>
|
|
</record>
|
|
<callback name="LogFunc" c:type="GLogFunc">
|
|
<doc xml:space="preserve">Specifies the prototype of log handler functions.
|
|
|
|
The default log handler, g_log_default_handler(), automatically appends a
|
|
new-line character to @message when printing it. It is advised that any
|
|
custom log handler functions behave similarly, so that logging calls in user
|
|
code do not need modifying to add a new-line character to the message if the
|
|
log handler is changed.
|
|
|
|
This is not used if structured logging is enabled; see
|
|
[Using Structured Logging][using-structured-logging].</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_domain" transfer-ownership="none">
|
|
<doc xml:space="preserve">the log domain of the message</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="log_level" transfer-ownership="none">
|
|
<doc xml:space="preserve">the log level of the message (including the
|
|
fatal and recursion flags)</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
<parameter name="message" transfer-ownership="none">
|
|
<doc xml:space="preserve">the message to process</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3">
|
|
<doc xml:space="preserve">user data, set in g_log_set_handler()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<bitfield name="LogLevelFlags" c:type="GLogLevelFlags">
|
|
<doc xml:space="preserve">Flags specifying the level of log messages.
|
|
|
|
It is possible to change how GLib treats messages of the various
|
|
levels using g_log_set_handler() and g_log_set_fatal_mask().</doc>
|
|
<member name="flag_recursion" value="1" c:identifier="G_LOG_FLAG_RECURSION">
|
|
<doc xml:space="preserve">internal flag</doc>
|
|
</member>
|
|
<member name="flag_fatal" value="2" c:identifier="G_LOG_FLAG_FATAL">
|
|
<doc xml:space="preserve">internal flag</doc>
|
|
</member>
|
|
<member name="level_error" value="4" c:identifier="G_LOG_LEVEL_ERROR">
|
|
<doc xml:space="preserve">log level for errors, see g_error().
|
|
This level is also used for messages produced by g_assert().</doc>
|
|
</member>
|
|
<member name="level_critical" value="8" c:identifier="G_LOG_LEVEL_CRITICAL">
|
|
<doc xml:space="preserve">log level for critical warning messages, see
|
|
g_critical().
|
|
This level is also used for messages produced by g_return_if_fail()
|
|
and g_return_val_if_fail().</doc>
|
|
</member>
|
|
<member name="level_warning" value="16" c:identifier="G_LOG_LEVEL_WARNING">
|
|
<doc xml:space="preserve">log level for warnings, see g_warning()</doc>
|
|
</member>
|
|
<member name="level_message" value="32" c:identifier="G_LOG_LEVEL_MESSAGE">
|
|
<doc xml:space="preserve">log level for messages, see g_message()</doc>
|
|
</member>
|
|
<member name="level_info" value="64" c:identifier="G_LOG_LEVEL_INFO">
|
|
<doc xml:space="preserve">log level for informational messages, see g_info()</doc>
|
|
</member>
|
|
<member name="level_debug" value="128" c:identifier="G_LOG_LEVEL_DEBUG">
|
|
<doc xml:space="preserve">log level for debug messages, see g_debug()</doc>
|
|
</member>
|
|
<member name="level_mask" value="-4" c:identifier="G_LOG_LEVEL_MASK">
|
|
<doc xml:space="preserve">a mask including all log levels</doc>
|
|
</member>
|
|
</bitfield>
|
|
<callback name="LogWriterFunc" c:type="GLogWriterFunc" version="2.50">
|
|
<doc xml:space="preserve">Writer function for log entries. A log entry is a collection of one or more
|
|
#GLogFields, using the standard [field names from journal
|
|
specification](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html).
|
|
See g_log_structured() for more information.
|
|
|
|
Writer functions must ignore fields which they do not recognise, unless they
|
|
can write arbitrary binary output, as field values may be arbitrary binary.
|
|
|
|
@log_level is guaranteed to be included in @fields as the `PRIORITY` field,
|
|
but is provided separately for convenience of deciding whether or where to
|
|
output the log entry.
|
|
|
|
Writer functions should return %G_LOG_WRITER_HANDLED if they handled the log
|
|
message successfully or if they deliberately ignored it. If there was an
|
|
error handling the message (for example, if the writer function is meant to
|
|
send messages to a remote logging server and there is a network error), it
|
|
should return %G_LOG_WRITER_UNHANDLED. This allows writer functions to be
|
|
chained and fall back to simpler handlers in case of failure.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%G_LOG_WRITER_HANDLED if the log entry was handled successfully;
|
|
%G_LOG_WRITER_UNHANDLED otherwise</doc>
|
|
<type name="LogWriterOutput" c:type="GLogWriterOutput"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_level" transfer-ownership="none">
|
|
<doc xml:space="preserve">log level of the message</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
<parameter name="fields" transfer-ownership="none">
|
|
<doc xml:space="preserve">fields forming the message</doc>
|
|
<array length="2" zero-terminated="0" c:type="const GLogField*">
|
|
<type name="LogField" c:type="GLogField"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="n_fields" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of @fields</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3">
|
|
<doc xml:space="preserve">user data passed to g_log_set_writer_func()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<enumeration name="LogWriterOutput" version="2.50" c:type="GLogWriterOutput">
|
|
<doc xml:space="preserve">Return values from #GLogWriterFuncs to indicate whether the given log entry
|
|
was successfully handled by the writer, or whether there was an error in
|
|
handling it (and hence a fallback writer should be used).
|
|
|
|
If a #GLogWriterFunc ignores a log entry, it should return
|
|
%G_LOG_WRITER_HANDLED.</doc>
|
|
<member name="handled" value="1" c:identifier="G_LOG_WRITER_HANDLED">
|
|
<doc xml:space="preserve">Log writer has handled the log entry.</doc>
|
|
</member>
|
|
<member name="unhandled" value="0" c:identifier="G_LOG_WRITER_UNHANDLED">
|
|
<doc xml:space="preserve">Log writer could not handle the log entry.</doc>
|
|
</member>
|
|
</enumeration>
|
|
<constant name="MAJOR_VERSION" value="2" c:type="GLIB_MAJOR_VERSION">
|
|
<doc xml:space="preserve">The major version number of the GLib library.
|
|
|
|
Like #glib_major_version, but from the headers used at
|
|
application compile time, rather than from the library
|
|
linked against at application run time.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="MAXINT16" value="32767" c:type="G_MAXINT16" version="2.4">
|
|
<doc xml:space="preserve">The maximum value which can be held in a #gint16.</doc>
|
|
<type name="gint16" c:type="gint16"/>
|
|
</constant>
|
|
<constant name="MAXINT32" value="2147483647" c:type="G_MAXINT32" version="2.4">
|
|
<doc xml:space="preserve">The maximum value which can be held in a #gint32.</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</constant>
|
|
<constant name="MAXINT64" value="9223372036854775807" c:type="G_MAXINT64">
|
|
<doc xml:space="preserve">The maximum value which can be held in a #gint64.</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</constant>
|
|
<constant name="MAXINT8" value="127" c:type="G_MAXINT8" version="2.4">
|
|
<doc xml:space="preserve">The maximum value which can be held in a #gint8.</doc>
|
|
<type name="gint8" c:type="gint8"/>
|
|
</constant>
|
|
<constant name="MAXUINT16" value="65535" c:type="G_MAXUINT16" version="2.4">
|
|
<doc xml:space="preserve">The maximum value which can be held in a #guint16.</doc>
|
|
<type name="guint16" c:type="guint16"/>
|
|
</constant>
|
|
<constant name="MAXUINT32" value="4294967295" c:type="G_MAXUINT32" version="2.4">
|
|
<doc xml:space="preserve">The maximum value which can be held in a #guint32.</doc>
|
|
<type name="guint32" c:type="guint32"/>
|
|
</constant>
|
|
<constant name="MAXUINT64" value="18446744073709551615" c:type="G_MAXUINT64">
|
|
<doc xml:space="preserve">The maximum value which can be held in a #guint64.</doc>
|
|
<type name="guint64" c:type="guint64"/>
|
|
</constant>
|
|
<constant name="MAXUINT8" value="255" c:type="G_MAXUINT8" version="2.4">
|
|
<doc xml:space="preserve">The maximum value which can be held in a #guint8.</doc>
|
|
<type name="guint8" c:type="guint8"/>
|
|
</constant>
|
|
<constant name="MICRO_VERSION" value="0" c:type="GLIB_MICRO_VERSION">
|
|
<doc xml:space="preserve">The micro version number of the GLib library.
|
|
|
|
Like #gtk_micro_version, but from the headers used at
|
|
application compile time, rather than from the library
|
|
linked against at application run time.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="MININT16" value="-32768" c:type="G_MININT16" version="2.4">
|
|
<doc xml:space="preserve">The minimum value which can be held in a #gint16.</doc>
|
|
<type name="gint16" c:type="gint16"/>
|
|
</constant>
|
|
<constant name="MININT32" value="-2147483648" c:type="G_MININT32" version="2.4">
|
|
<doc xml:space="preserve">The minimum value which can be held in a #gint32.</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</constant>
|
|
<constant name="MININT64" value="-9223372036854775808" c:type="G_MININT64">
|
|
<doc xml:space="preserve">The minimum value which can be held in a #gint64.</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</constant>
|
|
<constant name="MININT8" value="-128" c:type="G_MININT8" version="2.4">
|
|
<doc xml:space="preserve">The minimum value which can be held in a #gint8.</doc>
|
|
<type name="gint8" c:type="gint8"/>
|
|
</constant>
|
|
<constant name="MINOR_VERSION" value="66" c:type="GLIB_MINOR_VERSION">
|
|
<doc xml:space="preserve">The minor version number of the GLib library.
|
|
|
|
Like #gtk_minor_version, but from the headers used at
|
|
application compile time, rather than from the library
|
|
linked against at application run time.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="MODULE_SUFFIX" value="so" c:type="G_MODULE_SUFFIX">
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<record name="MainContext" c:type="GMainContext" glib:type-name="GMainContext" glib:get-type="g_main_context_get_type" c:symbol-prefix="main_context">
|
|
<doc xml:space="preserve">The `GMainContext` struct is an opaque data
|
|
type representing a set of sources to be handled in a main loop.</doc>
|
|
<constructor name="new" c:identifier="g_main_context_new">
|
|
<doc xml:space="preserve">Creates a new #GMainContext structure.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the new #GMainContext</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</return-value>
|
|
</constructor>
|
|
<method name="acquire" c:identifier="g_main_context_acquire">
|
|
<doc xml:space="preserve">Tries to become the owner of the specified context.
|
|
If some other thread is the owner of the context,
|
|
returns %FALSE immediately. Ownership is properly
|
|
recursive: the owner can require ownership again
|
|
and will release ownership when g_main_context_release()
|
|
is called as many times as g_main_context_acquire().
|
|
|
|
You must be the owner of a context before you
|
|
can call g_main_context_prepare(), g_main_context_query(),
|
|
g_main_context_check(), g_main_context_dispatch().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the operation succeeded, and
|
|
this thread is now the owner of @context.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainContext</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_poll" c:identifier="g_main_context_add_poll">
|
|
<doc xml:space="preserve">Adds a file descriptor to the set of file descriptors polled for
|
|
this context. This will very seldom be used directly. Instead
|
|
a typical event source will use g_source_add_unix_fd() instead.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GMainContext (or %NULL for the default context)</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPollFD structure holding information about a file
|
|
descriptor to watch.</doc>
|
|
<type name="PollFD" c:type="GPollFD*"/>
|
|
</parameter>
|
|
<parameter name="priority" transfer-ownership="none">
|
|
<doc xml:space="preserve">the priority for this file descriptor which should be
|
|
the same as the priority used for g_source_attach() to ensure that the
|
|
file descriptor is polled whenever the results may be needed.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="check" c:identifier="g_main_context_check">
|
|
<doc xml:space="preserve">Passes the results of polling back to the main loop.
|
|
|
|
You must have successfully acquired the context with
|
|
g_main_context_acquire() before you may call this function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if some sources are ready to be dispatched.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainContext</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="max_priority" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum numerical priority of sources to check</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="fds" transfer-ownership="none">
|
|
<doc xml:space="preserve">array of #GPollFD's that was passed to
|
|
the last call to g_main_context_query()</doc>
|
|
<array length="2" zero-terminated="0" c:type="GPollFD*">
|
|
<type name="PollFD" c:type="GPollFD"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="n_fds" transfer-ownership="none">
|
|
<doc xml:space="preserve">return value of g_main_context_query()</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="dispatch" c:identifier="g_main_context_dispatch">
|
|
<doc xml:space="preserve">Dispatches all pending sources.
|
|
|
|
You must have successfully acquired the context with
|
|
g_main_context_acquire() before you may call this function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainContext</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="find_source_by_funcs_user_data" c:identifier="g_main_context_find_source_by_funcs_user_data">
|
|
<doc xml:space="preserve">Finds a source with the given source functions and user data. If
|
|
multiple sources exist with the same source function and user data,
|
|
the first one found will be returned.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the source, if one was found, otherwise %NULL</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GMainContext (if %NULL, the default context will be used).</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="funcs" transfer-ownership="none">
|
|
<doc xml:space="preserve">the @source_funcs passed to g_source_new().</doc>
|
|
<type name="SourceFuncs" c:type="GSourceFuncs*"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the user data from the callback.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="find_source_by_id" c:identifier="g_main_context_find_source_by_id">
|
|
<doc xml:space="preserve">Finds a #GSource given a pair of context and ID.
|
|
|
|
It is a programmer error to attempt to look up a non-existent source.
|
|
|
|
More specifically: source IDs can be reissued after a source has been
|
|
destroyed and therefore it is never valid to use this function with a
|
|
source ID which may have already been removed. An example is when
|
|
scheduling an idle to run in another thread with g_idle_add(): the
|
|
idle may already have run and been removed by the time this function
|
|
is called on its (now invalid) source ID. This source ID may have
|
|
been reissued, leading to the operation being performed against the
|
|
wrong source.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GMainContext (if %NULL, the default context will be used)</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="source_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">the source ID, as returned by g_source_get_id().</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="find_source_by_user_data" c:identifier="g_main_context_find_source_by_user_data">
|
|
<doc xml:space="preserve">Finds a source with the given user data for the callback. If
|
|
multiple sources exist with the same user data, the first
|
|
one found will be returned.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the source, if one was found, otherwise %NULL</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainContext</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the user_data for the callback.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_poll_func" c:identifier="g_main_context_get_poll_func" introspectable="0">
|
|
<doc xml:space="preserve">Gets the poll function set by g_main_context_set_poll_func().</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the poll function</doc>
|
|
<type name="PollFunc" c:type="GPollFunc"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainContext</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="invoke" c:identifier="g_main_context_invoke" version="2.28" introspectable="0">
|
|
<doc xml:space="preserve">Invokes a function in such a way that @context is owned during the
|
|
invocation of @function.
|
|
|
|
If @context is %NULL then the global default main context — as
|
|
returned by g_main_context_default() — is used.
|
|
|
|
If @context is owned by the current thread, @function is called
|
|
directly. Otherwise, if @context is the thread-default main context
|
|
of the current thread and g_main_context_acquire() succeeds, then
|
|
@function is called and g_main_context_release() is called
|
|
afterwards.
|
|
|
|
In any other case, an idle source is created to call @function and
|
|
that source is attached to @context (presumably to be run in another
|
|
thread). The idle source is attached with #G_PRIORITY_DEFAULT
|
|
priority. If you want a different priority, use
|
|
g_main_context_invoke_full().
|
|
|
|
Note that, as with normal idle functions, @function should probably
|
|
return %FALSE. If it returns %TRUE, it will be continuously run in a
|
|
loop (and may prevent this call from returning).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GMainContext, or %NULL</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="function" transfer-ownership="none" closure="1">
|
|
<doc xml:space="preserve">function to call</doc>
|
|
<type name="SourceFunc" c:type="GSourceFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="invoke_full" c:identifier="g_main_context_invoke_full" version="2.28">
|
|
<doc xml:space="preserve">Invokes a function in such a way that @context is owned during the
|
|
invocation of @function.
|
|
|
|
This function is the same as g_main_context_invoke() except that it
|
|
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
|
|
thread or with any particular context acquired.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GMainContext, or %NULL</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="priority" transfer-ownership="none">
|
|
<doc xml:space="preserve">the priority at which to run @function</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="function" transfer-ownership="none" scope="notified" closure="2" destroy="3">
|
|
<doc xml:space="preserve">function to call</doc>
|
|
<type name="SourceFunc" c:type="GSourceFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">a function to call when @data is no longer in use, or %NULL.</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_owner" c:identifier="g_main_context_is_owner" version="2.10">
|
|
<doc xml:space="preserve">Determines whether this thread holds the (recursive)
|
|
ownership of this #GMainContext. This is useful to
|
|
know before waiting on another thread that may be
|
|
blocking to get ownership of @context.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if current thread is owner of @context.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainContext</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="iteration" c:identifier="g_main_context_iteration">
|
|
<doc xml:space="preserve">Runs a single iteration for the given main loop. This involves
|
|
checking to see if any event sources are ready to be processed,
|
|
then if no events sources are ready and @may_block is %TRUE, waiting
|
|
for a source to become ready, then dispatching the highest priority
|
|
events sources that are ready. Otherwise, if @may_block is %FALSE
|
|
sources are not waited to become ready, only those highest priority
|
|
events sources will be dispatched (if any), that are ready at this
|
|
given moment without further waiting.
|
|
|
|
Note that even when @may_block is %TRUE, it is still possible for
|
|
g_main_context_iteration() to return %FALSE, since the wait may
|
|
be interrupted for other reasons than an event source becoming ready.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if events were dispatched.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GMainContext (if %NULL, the default context will be used)</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="may_block" transfer-ownership="none">
|
|
<doc xml:space="preserve">whether the call may block.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="pending" c:identifier="g_main_context_pending">
|
|
<doc xml:space="preserve">Checks if any sources have pending events for the given context.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if events are pending.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GMainContext (if %NULL, the default context will be used)</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="pop_thread_default" c:identifier="g_main_context_pop_thread_default" version="2.22">
|
|
<doc xml:space="preserve">Pops @context off the thread-default context stack (verifying that
|
|
it was on the top of the stack).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GMainContext object, or %NULL</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="prepare" c:identifier="g_main_context_prepare">
|
|
<doc xml:space="preserve">Prepares to poll sources within a main loop. The resulting information
|
|
for polling is determined by calling g_main_context_query ().
|
|
|
|
You must have successfully acquired the context with
|
|
g_main_context_acquire() before you may call this function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if some source is ready to be dispatched
|
|
prior to polling.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainContext</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="priority" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store priority of highest priority
|
|
source already ready.</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="push_thread_default" c:identifier="g_main_context_push_thread_default" version="2.22">
|
|
<doc xml:space="preserve">Acquires @context and sets it as the thread-default context for the
|
|
current thread. This will cause certain asynchronous operations
|
|
(such as most [gio][gio]-based I/O) which are
|
|
started in this thread to run under @context and deliver their
|
|
results to its main loop, rather than running under the global
|
|
default context in the main thread. Note that calling this function
|
|
changes the context returned by g_main_context_get_thread_default(),
|
|
not the one returned by g_main_context_default(), so it does not affect
|
|
the context used by functions like g_idle_add().
|
|
|
|
Normally you would call this function shortly after creating a new
|
|
thread, passing it a #GMainContext which will be run by a
|
|
#GMainLoop in that thread, to set a new default context for all
|
|
async operations in that thread. In this case you may not need to
|
|
ever call g_main_context_pop_thread_default(), assuming you want the
|
|
new #GMainContext to be the default for the whole lifecycle of the
|
|
thread.
|
|
|
|
If you don't have control over how the new thread was created (e.g.
|
|
in the new thread isn't newly created, or if the thread life
|
|
cycle is managed by a #GThreadPool), it is always suggested to wrap
|
|
the logic that needs to use the new #GMainContext inside a
|
|
g_main_context_push_thread_default() / g_main_context_pop_thread_default()
|
|
pair, otherwise threads that are re-used will end up never explicitly
|
|
releasing the #GMainContext reference they hold.
|
|
|
|
In some cases you may want to schedule a single operation in a
|
|
non-default context, or temporarily use a non-default context in
|
|
the main thread. In that case, you can wrap the call to the
|
|
asynchronous operation inside a
|
|
g_main_context_push_thread_default() /
|
|
g_main_context_pop_thread_default() pair, but it is up to you to
|
|
ensure that no other asynchronous operations accidentally get
|
|
started while the non-default context is active.
|
|
|
|
Beware that libraries that predate this function may not correctly
|
|
handle being used from a thread with a thread-default context. Eg,
|
|
see g_file_supports_thread_contexts().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GMainContext, or %NULL for the global default context</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="query" c:identifier="g_main_context_query">
|
|
<doc xml:space="preserve">Determines information necessary to poll this main loop.
|
|
|
|
You must have successfully acquired the context with
|
|
g_main_context_acquire() before you may call this function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of records actually stored in @fds,
|
|
or, if more than @n_fds records need to be stored, the number
|
|
of records that need to be stored.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainContext</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="max_priority" transfer-ownership="none">
|
|
<doc xml:space="preserve">maximum priority source to check</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="timeout_" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">location to store timeout to be used in polling</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="fds" direction="out" caller-allocates="1" transfer-ownership="none">
|
|
<doc xml:space="preserve">location to
|
|
store #GPollFD records that need to be polled.</doc>
|
|
<array length="3" zero-terminated="0" c:type="GPollFD*">
|
|
<type name="PollFD" c:type="GPollFD"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="n_fds" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @fds.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_main_context_ref">
|
|
<doc xml:space="preserve">Increases the reference count on a #GMainContext object by one.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the @context that was passed in (since 2.6)</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainContext</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="release" c:identifier="g_main_context_release">
|
|
<doc xml:space="preserve">Releases ownership of a context previously acquired by this thread
|
|
with g_main_context_acquire(). If the context was acquired multiple
|
|
times, the ownership will be released only when g_main_context_release()
|
|
is called as many times as it was acquired.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainContext</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="remove_poll" c:identifier="g_main_context_remove_poll">
|
|
<doc xml:space="preserve">Removes file descriptor from the set of file descriptors to be
|
|
polled for a particular context.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainContext</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPollFD descriptor previously added with g_main_context_add_poll()</doc>
|
|
<type name="PollFD" c:type="GPollFD*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_poll_func" c:identifier="g_main_context_set_poll_func" introspectable="0">
|
|
<doc xml:space="preserve">Sets the function to use to handle polling of file descriptors. It
|
|
will be used instead of the poll() system call
|
|
(or GLib's replacement function, which is used where
|
|
poll() isn't available).
|
|
|
|
This function could possibly be used to integrate the GLib event
|
|
loop with an external event loop.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainContext</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<doc xml:space="preserve">the function to call to poll all file descriptors</doc>
|
|
<type name="PollFunc" c:type="GPollFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_main_context_unref">
|
|
<doc xml:space="preserve">Decreases the reference count on a #GMainContext object by one. If
|
|
the result is zero, free the context and free all associated memory.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainContext</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="wait" c:identifier="g_main_context_wait" deprecated="1" deprecated-version="2.58">
|
|
<doc xml:space="preserve">Tries to become the owner of the specified context,
|
|
as with g_main_context_acquire(). But if another thread
|
|
is the owner, atomically drop @mutex and wait on @cond until
|
|
that owner releases ownership or until @cond is signaled, then
|
|
try again (once) to become the owner.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_main_context_is_owner() and separate locking instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the operation succeeded, and
|
|
this thread is now the owner of @context.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainContext</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="cond" transfer-ownership="none">
|
|
<doc xml:space="preserve">a condition variable</doc>
|
|
<type name="Cond" c:type="GCond*"/>
|
|
</parameter>
|
|
<parameter name="mutex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a mutex, currently held</doc>
|
|
<type name="Mutex" c:type="GMutex*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="wakeup" c:identifier="g_main_context_wakeup">
|
|
<doc xml:space="preserve">If @context is currently blocking in g_main_context_iteration()
|
|
waiting for a source to become ready, cause it to stop blocking
|
|
and return. Otherwise, cause the next invocation of
|
|
g_main_context_iteration() to return without blocking.
|
|
|
|
This API is useful for low-level control over #GMainContext; for
|
|
example, integrating it with main loop implementations such as
|
|
#GMainLoop.
|
|
|
|
Another related use for this function is when implementing a main
|
|
loop with a termination condition, computed from multiple threads:
|
|
|
|
|[<!-- language="C" -->
|
|
#define NUM_TASKS 10
|
|
static volatile gint tasks_remaining = NUM_TASKS;
|
|
...
|
|
|
|
while (g_atomic_int_get (&tasks_remaining) != 0)
|
|
g_main_context_iteration (NULL, TRUE);
|
|
]|
|
|
|
|
Then in a thread:
|
|
|[<!-- language="C" -->
|
|
perform_work();
|
|
|
|
if (g_atomic_int_dec_and_test (&tasks_remaining))
|
|
g_main_context_wakeup (NULL);
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainContext</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="default" c:identifier="g_main_context_default">
|
|
<doc xml:space="preserve">Returns the global default main context. This is the main context
|
|
used for main loop functions when a main loop is not explicitly
|
|
specified, and corresponds to the "main" main loop. See also
|
|
g_main_context_get_thread_default().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the global default main context.</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_thread_default" c:identifier="g_main_context_get_thread_default" version="2.22">
|
|
<doc xml:space="preserve">Gets the thread-default #GMainContext for this thread. Asynchronous
|
|
operations that want to be able to be run in contexts other than
|
|
the default one should call this method or
|
|
g_main_context_ref_thread_default() to get a #GMainContext to add
|
|
their #GSources to. (Note that even in single-threaded
|
|
programs applications may sometimes want to temporarily push a
|
|
non-default context, so it is not safe to assume that this will
|
|
always return %NULL if you are running in the default thread.)
|
|
|
|
If you need to hold a reference on the context, use
|
|
g_main_context_ref_thread_default() instead.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the thread-default #GMainContext, or
|
|
%NULL if the thread-default context is the global default context.</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="ref_thread_default" c:identifier="g_main_context_ref_thread_default" version="2.32">
|
|
<doc xml:space="preserve">Gets the thread-default #GMainContext for this thread, as with
|
|
g_main_context_get_thread_default(), but also adds a reference to
|
|
it with g_main_context_ref(). In addition, unlike
|
|
g_main_context_get_thread_default(), if the thread-default context
|
|
is the global default context, this will return that #GMainContext
|
|
(with a ref added to it) rather than returning %NULL.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the thread-default #GMainContext. Unref
|
|
with g_main_context_unref() when you are done with it.</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</return-value>
|
|
</function>
|
|
</record>
|
|
<record name="MainLoop" c:type="GMainLoop" glib:type-name="GMainLoop" glib:get-type="g_main_loop_get_type" c:symbol-prefix="main_loop">
|
|
<doc xml:space="preserve">The `GMainLoop` struct is an opaque data type
|
|
representing the main event loop of a GLib or GTK+ application.</doc>
|
|
<constructor name="new" c:identifier="g_main_loop_new">
|
|
<doc xml:space="preserve">Creates a new #GMainLoop structure.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GMainLoop.</doc>
|
|
<type name="MainLoop" c:type="GMainLoop*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="context" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GMainContext (if %NULL, the default context will be used).</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</parameter>
|
|
<parameter name="is_running" transfer-ownership="none">
|
|
<doc xml:space="preserve">set to %TRUE to indicate that the loop is running. This
|
|
is not very important since calling g_main_loop_run() will set this to
|
|
%TRUE anyway.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<method name="get_context" c:identifier="g_main_loop_get_context">
|
|
<doc xml:space="preserve">Returns the #GMainContext of @loop.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GMainContext of @loop</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="loop" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainLoop.</doc>
|
|
<type name="MainLoop" c:type="GMainLoop*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_running" c:identifier="g_main_loop_is_running">
|
|
<doc xml:space="preserve">Checks to see if the main loop is currently being run via g_main_loop_run().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the mainloop is currently being run.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="loop" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainLoop.</doc>
|
|
<type name="MainLoop" c:type="GMainLoop*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="quit" c:identifier="g_main_loop_quit">
|
|
<doc xml:space="preserve">Stops a #GMainLoop from running. Any calls to g_main_loop_run()
|
|
for the loop will return.
|
|
|
|
Note that sources that have already been dispatched when
|
|
g_main_loop_quit() is called will still be executed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="loop" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainLoop</doc>
|
|
<type name="MainLoop" c:type="GMainLoop*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_main_loop_ref">
|
|
<doc xml:space="preserve">Increases the reference count on a #GMainLoop object by one.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">@loop</doc>
|
|
<type name="MainLoop" c:type="GMainLoop*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="loop" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainLoop</doc>
|
|
<type name="MainLoop" c:type="GMainLoop*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="run" c:identifier="g_main_loop_run">
|
|
<doc xml:space="preserve">Runs a main loop until g_main_loop_quit() is called on the loop.
|
|
If this is called for the thread of the loop's #GMainContext,
|
|
it will process events from the loop, otherwise it will
|
|
simply wait.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="loop" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainLoop</doc>
|
|
<type name="MainLoop" c:type="GMainLoop*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_main_loop_unref">
|
|
<doc xml:space="preserve">Decreases the reference count on a #GMainLoop object by one. If
|
|
the result is zero, free the loop and free all associated memory.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="loop" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMainLoop</doc>
|
|
<type name="MainLoop" c:type="GMainLoop*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<record name="MappedFile" c:type="GMappedFile" glib:type-name="GMappedFile" glib:get-type="g_mapped_file_get_type" c:symbol-prefix="mapped_file">
|
|
<doc xml:space="preserve">The #GMappedFile represents a file mapping created with
|
|
g_mapped_file_new(). It has only private members and should
|
|
not be accessed directly.</doc>
|
|
<constructor name="new" c:identifier="g_mapped_file_new" version="2.8" throws="1">
|
|
<doc xml:space="preserve">Maps a file into memory. On UNIX, this is using the mmap() function.
|
|
|
|
If @writable is %TRUE, the mapped buffer may be modified, otherwise
|
|
it is an error to modify the mapped buffer. Modifications to the buffer
|
|
are not visible to other processes mapping the same file, and are not
|
|
written back to the file.
|
|
|
|
Note that modifications of the underlying file might affect the contents
|
|
of the #GMappedFile. Therefore, mapping should only be used if the file
|
|
will not be modified, or if all modifications of the file are done
|
|
atomically (e.g. using g_file_set_contents()).
|
|
|
|
If @filename is the name of an empty, regular file, the function
|
|
will successfully return an empty #GMappedFile. In other cases of
|
|
size 0 (e.g. device files such as /dev/null), @error will be set
|
|
to the #GFileError value #G_FILE_ERROR_INVAL.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated #GMappedFile which must be unref'd
|
|
with g_mapped_file_unref(), or %NULL if the mapping failed.</doc>
|
|
<type name="MappedFile" c:type="GMappedFile*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="filename" transfer-ownership="none">
|
|
<doc xml:space="preserve">The path of the file to load, in the GLib
|
|
filename encoding</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="writable" transfer-ownership="none">
|
|
<doc xml:space="preserve">whether the mapping should be writable</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_from_fd" c:identifier="g_mapped_file_new_from_fd" version="2.32" throws="1">
|
|
<doc xml:space="preserve">Maps a file into memory. On UNIX, this is using the mmap() function.
|
|
|
|
If @writable is %TRUE, the mapped buffer may be modified, otherwise
|
|
it is an error to modify the mapped buffer. Modifications to the buffer
|
|
are not visible to other processes mapping the same file, and are not
|
|
written back to the file.
|
|
|
|
Note that modifications of the underlying file might affect the contents
|
|
of the #GMappedFile. Therefore, mapping should only be used if the file
|
|
will not be modified, or if all modifications of the file are done
|
|
atomically (e.g. using g_file_set_contents()).</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated #GMappedFile which must be unref'd
|
|
with g_mapped_file_unref(), or %NULL if the mapping failed.</doc>
|
|
<type name="MappedFile" c:type="GMappedFile*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">The file descriptor of the file to load</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="writable" transfer-ownership="none">
|
|
<doc xml:space="preserve">whether the mapping should be writable</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<method name="free" c:identifier="g_mapped_file_free" version="2.8" deprecated="1" deprecated-version="2.22">
|
|
<doc xml:space="preserve">This call existed before #GMappedFile had refcounting and is currently
|
|
exactly the same as g_mapped_file_unref().</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_mapped_file_unref() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMappedFile</doc>
|
|
<type name="MappedFile" c:type="GMappedFile*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_bytes" c:identifier="g_mapped_file_get_bytes" version="2.34">
|
|
<doc xml:space="preserve">Creates a new #GBytes which references the data mapped from @file.
|
|
The mapped contents of the file must not be modified after creating this
|
|
bytes object, because a #GBytes should be immutable.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">A newly allocated #GBytes referencing data
|
|
from @file</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMappedFile</doc>
|
|
<type name="MappedFile" c:type="GMappedFile*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_contents" c:identifier="g_mapped_file_get_contents" version="2.8">
|
|
<doc xml:space="preserve">Returns the contents of a #GMappedFile.
|
|
|
|
Note that the contents may not be zero-terminated,
|
|
even if the #GMappedFile is backed by a text file.
|
|
|
|
If the file is empty then %NULL is returned.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the contents of @file, or %NULL.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMappedFile</doc>
|
|
<type name="MappedFile" c:type="GMappedFile*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_length" c:identifier="g_mapped_file_get_length" version="2.8">
|
|
<doc xml:space="preserve">Returns the length of the contents of a #GMappedFile.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the contents of @file.</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMappedFile</doc>
|
|
<type name="MappedFile" c:type="GMappedFile*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_mapped_file_ref" version="2.22">
|
|
<doc xml:space="preserve">Increments the reference count of @file by one. It is safe to call
|
|
this function from any thread.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the passed in #GMappedFile.</doc>
|
|
<type name="MappedFile" c:type="GMappedFile*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMappedFile</doc>
|
|
<type name="MappedFile" c:type="GMappedFile*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_mapped_file_unref">
|
|
<doc xml:space="preserve">Decrements the reference count of @file by one. If the reference count
|
|
drops to 0, unmaps the buffer of @file and frees it.
|
|
|
|
It is safe to call this function from any thread.
|
|
|
|
Since 2.22</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="file" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMappedFile</doc>
|
|
<type name="MappedFile" c:type="GMappedFile*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<bitfield name="MarkupCollectType" c:type="GMarkupCollectType">
|
|
<doc xml:space="preserve">A mixed enumerated type and flags field. You must specify one type
|
|
(string, strdup, boolean, tristate). Additionally, you may optionally
|
|
bitwise OR the type with the flag %G_MARKUP_COLLECT_OPTIONAL.
|
|
|
|
It is likely that this enum will be extended in the future to
|
|
support other types.</doc>
|
|
<member name="invalid" value="0" c:identifier="G_MARKUP_COLLECT_INVALID">
|
|
<doc xml:space="preserve">used to terminate the list of attributes
|
|
to collect</doc>
|
|
</member>
|
|
<member name="string" value="1" c:identifier="G_MARKUP_COLLECT_STRING">
|
|
<doc xml:space="preserve">collect the string pointer directly from
|
|
the attribute_values[] array. Expects a parameter of type (const
|
|
char **). If %G_MARKUP_COLLECT_OPTIONAL is specified and the
|
|
attribute isn't present then the pointer will be set to %NULL</doc>
|
|
</member>
|
|
<member name="strdup" value="2" c:identifier="G_MARKUP_COLLECT_STRDUP">
|
|
<doc xml:space="preserve">as with %G_MARKUP_COLLECT_STRING, but
|
|
expects a parameter of type (char **) and g_strdup()s the
|
|
returned pointer. The pointer must be freed with g_free()</doc>
|
|
</member>
|
|
<member name="boolean" value="3" c:identifier="G_MARKUP_COLLECT_BOOLEAN">
|
|
<doc xml:space="preserve">expects a parameter of type (gboolean *)
|
|
and parses the attribute value as a boolean. Sets %FALSE if the
|
|
attribute isn't present. Valid boolean values consist of
|
|
(case-insensitive) "false", "f", "no", "n", "0" and "true", "t",
|
|
"yes", "y", "1"</doc>
|
|
</member>
|
|
<member name="tristate" value="4" c:identifier="G_MARKUP_COLLECT_TRISTATE">
|
|
<doc xml:space="preserve">as with %G_MARKUP_COLLECT_BOOLEAN, but
|
|
in the case of a missing attribute a value is set that compares
|
|
equal to neither %FALSE nor %TRUE G_MARKUP_COLLECT_OPTIONAL is
|
|
implied</doc>
|
|
</member>
|
|
<member name="optional" value="65536" c:identifier="G_MARKUP_COLLECT_OPTIONAL">
|
|
<doc xml:space="preserve">can be bitwise ORed with the other fields.
|
|
If present, allows the attribute not to appear. A default value
|
|
is set depending on what value type is used</doc>
|
|
</member>
|
|
</bitfield>
|
|
<enumeration name="MarkupError" c:type="GMarkupError" glib:error-domain="g-markup-error-quark">
|
|
<doc xml:space="preserve">Error codes returned by markup parsing.</doc>
|
|
<member name="bad_utf8" value="0" c:identifier="G_MARKUP_ERROR_BAD_UTF8">
|
|
<doc xml:space="preserve">text being parsed was not valid UTF-8</doc>
|
|
</member>
|
|
<member name="empty" value="1" c:identifier="G_MARKUP_ERROR_EMPTY">
|
|
<doc xml:space="preserve">document contained nothing, or only whitespace</doc>
|
|
</member>
|
|
<member name="parse" value="2" c:identifier="G_MARKUP_ERROR_PARSE">
|
|
<doc xml:space="preserve">document was ill-formed</doc>
|
|
</member>
|
|
<member name="unknown_element" value="3" c:identifier="G_MARKUP_ERROR_UNKNOWN_ELEMENT">
|
|
<doc xml:space="preserve">error should be set by #GMarkupParser
|
|
functions; element wasn't known</doc>
|
|
</member>
|
|
<member name="unknown_attribute" value="4" c:identifier="G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE">
|
|
<doc xml:space="preserve">error should be set by #GMarkupParser
|
|
functions; attribute wasn't known</doc>
|
|
</member>
|
|
<member name="invalid_content" value="5" c:identifier="G_MARKUP_ERROR_INVALID_CONTENT">
|
|
<doc xml:space="preserve">error should be set by #GMarkupParser
|
|
functions; content was invalid</doc>
|
|
</member>
|
|
<member name="missing_attribute" value="6" c:identifier="G_MARKUP_ERROR_MISSING_ATTRIBUTE">
|
|
<doc xml:space="preserve">error should be set by #GMarkupParser
|
|
functions; a required attribute was missing</doc>
|
|
</member>
|
|
</enumeration>
|
|
<record name="MarkupParseContext" c:type="GMarkupParseContext" glib:type-name="GMarkupParseContext" glib:get-type="g_markup_parse_context_get_type" c:symbol-prefix="markup_parse_context">
|
|
<doc xml:space="preserve">A parse context is used to parse a stream of bytes that
|
|
you expect to contain marked-up text.
|
|
|
|
See g_markup_parse_context_new(), #GMarkupParser, and so
|
|
on for more details.</doc>
|
|
<constructor name="new" c:identifier="g_markup_parse_context_new">
|
|
<doc xml:space="preserve">Creates a new parse context. A parse context is used to parse
|
|
marked-up documents. You can feed any number of documents into
|
|
a context, as long as no errors occur; once an error occurs,
|
|
the parse context can't continue to parse text (you have to
|
|
free it and create a new parse context).</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GMarkupParseContext</doc>
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="parser" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMarkupParser</doc>
|
|
<type name="MarkupParser" c:type="const GMarkupParser*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">one or more #GMarkupParseFlags</doc>
|
|
<type name="MarkupParseFlags" c:type="GMarkupParseFlags"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to #GMarkupParser functions</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="user_data_dnotify" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">user data destroy notifier called when
|
|
the parse context is freed</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<method name="end_parse" c:identifier="g_markup_parse_context_end_parse" throws="1">
|
|
<doc xml:space="preserve">Signals to the #GMarkupParseContext that all data has been
|
|
fed into the parse context with g_markup_parse_context_parse().
|
|
|
|
This function reports an error if the document isn't complete,
|
|
for example if elements are still open.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on success, %FALSE if an error was set</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMarkupParseContext</doc>
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free" c:identifier="g_markup_parse_context_free">
|
|
<doc xml:space="preserve">Frees a #GMarkupParseContext.
|
|
|
|
This function can't be called from inside one of the
|
|
#GMarkupParser functions or while a subparser is pushed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMarkupParseContext</doc>
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_element" c:identifier="g_markup_parse_context_get_element" version="2.2">
|
|
<doc xml:space="preserve">Retrieves the name of the currently open element.
|
|
|
|
If called from the start_element or end_element handlers this will
|
|
give the element_name as passed to those functions. For the parent
|
|
elements, see g_markup_parse_context_get_element_stack().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the name of the currently open element, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMarkupParseContext</doc>
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_element_stack" c:identifier="g_markup_parse_context_get_element_stack" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Retrieves the element stack from the internal state of the parser.
|
|
|
|
The returned #GSList is a list of strings where the first item is
|
|
the currently open tag (as would be returned by
|
|
g_markup_parse_context_get_element()) and the next item is its
|
|
immediate parent.
|
|
|
|
This function is intended to be used in the start_element and
|
|
end_element handlers where g_markup_parse_context_get_element()
|
|
would merely return the name of the element that is being
|
|
processed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the element stack, which must not be modified</doc>
|
|
<type name="GLib.SList" c:type="const GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMarkupParseContext</doc>
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_position" c:identifier="g_markup_parse_context_get_position">
|
|
<doc xml:space="preserve">Retrieves the current line number and the number of the character on
|
|
that line. Intended for use in error messages; there are no strict
|
|
semantics for what constitutes the "current" line number other than
|
|
"the best number we could come up with for error messages."</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMarkupParseContext</doc>
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="line_number" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for a line number, or %NULL</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="char_number" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for a char-on-line number, or %NULL</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_user_data" c:identifier="g_markup_parse_context_get_user_data" version="2.18">
|
|
<doc xml:space="preserve">Returns the user_data associated with @context.
|
|
|
|
This will either be the user_data that was provided to
|
|
g_markup_parse_context_new() or to the most recent call
|
|
of g_markup_parse_context_push().</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the provided user_data. The returned data belongs to
|
|
the markup context and will be freed when
|
|
g_markup_parse_context_free() is called.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMarkupParseContext</doc>
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="parse" c:identifier="g_markup_parse_context_parse" throws="1">
|
|
<doc xml:space="preserve">Feed some data to the #GMarkupParseContext.
|
|
|
|
The data need not be valid UTF-8; an error will be signaled if
|
|
it's invalid. The data need not be an entire document; you can
|
|
feed a document into the parser incrementally, via multiple calls
|
|
to this function. Typically, as you receive data from a network
|
|
connection or file, you feed each received chunk of data into this
|
|
function, aborting the process if an error occurs. Once an error
|
|
is reported, no further data may be fed to the #GMarkupParseContext;
|
|
all errors are fatal.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%FALSE if an error occurred, %TRUE on success</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMarkupParseContext</doc>
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="text" transfer-ownership="none">
|
|
<doc xml:space="preserve">chunk of text to parse</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="text_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @text in bytes</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="pop" c:identifier="g_markup_parse_context_pop" version="2.18">
|
|
<doc xml:space="preserve">Completes the process of a temporary sub-parser redirection.
|
|
|
|
This function exists to collect the user_data allocated by a
|
|
matching call to g_markup_parse_context_push(). It must be called
|
|
in the end_element handler corresponding to the start_element
|
|
handler during which g_markup_parse_context_push() was called.
|
|
You must not call this function from the error callback -- the
|
|
@user_data is provided directly to the callback in that case.
|
|
|
|
This function is not intended to be directly called by users
|
|
interested in invoking subparsers. Instead, it is intended to
|
|
be used by the subparsers themselves to implement a higher-level
|
|
interface.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the user data passed to g_markup_parse_context_push()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMarkupParseContext</doc>
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="push" c:identifier="g_markup_parse_context_push" version="2.18">
|
|
<doc xml:space="preserve">Temporarily redirects markup data to a sub-parser.
|
|
|
|
This function may only be called from the start_element handler of
|
|
a #GMarkupParser. It must be matched with a corresponding call to
|
|
g_markup_parse_context_pop() in the matching end_element handler
|
|
(except in the case that the parser aborts due to an error).
|
|
|
|
All tags, text and other data between the matching tags is
|
|
redirected to the subparser given by @parser. @user_data is used
|
|
as the user_data for that parser. @user_data is also passed to the
|
|
error callback in the event that an error occurs. This includes
|
|
errors that occur in subparsers of the subparser.
|
|
|
|
The end tag matching the start tag for which this call was made is
|
|
handled by the previous parser (which is given its own user_data)
|
|
which is why g_markup_parse_context_pop() is provided to allow "one
|
|
last access" to the @user_data provided to this function. In the
|
|
case of error, the @user_data provided here is passed directly to
|
|
the error callback of the subparser and g_markup_parse_context_pop()
|
|
should not be called. In either case, if @user_data was allocated
|
|
then it ought to be freed from both of these locations.
|
|
|
|
This function is not intended to be directly called by users
|
|
interested in invoking subparsers. Instead, it is intended to be
|
|
used by the subparsers themselves to implement a higher-level
|
|
interface.
|
|
|
|
As an example, see the following implementation of a simple
|
|
parser that counts the number of tags encountered.
|
|
|
|
|[<!-- language="C" -->
|
|
typedef struct
|
|
{
|
|
gint tag_count;
|
|
} CounterData;
|
|
|
|
static void
|
|
counter_start_element (GMarkupParseContext *context,
|
|
const gchar *element_name,
|
|
const gchar **attribute_names,
|
|
const gchar **attribute_values,
|
|
gpointer user_data,
|
|
GError **error)
|
|
{
|
|
CounterData *data = user_data;
|
|
|
|
data->tag_count++;
|
|
}
|
|
|
|
static void
|
|
counter_error (GMarkupParseContext *context,
|
|
GError *error,
|
|
gpointer user_data)
|
|
{
|
|
CounterData *data = user_data;
|
|
|
|
g_slice_free (CounterData, data);
|
|
}
|
|
|
|
static GMarkupParser counter_subparser =
|
|
{
|
|
counter_start_element,
|
|
NULL,
|
|
NULL,
|
|
NULL,
|
|
counter_error
|
|
};
|
|
]|
|
|
|
|
In order to allow this parser to be easily used as a subparser, the
|
|
following interface is provided:
|
|
|
|
|[<!-- language="C" -->
|
|
void
|
|
start_counting (GMarkupParseContext *context)
|
|
{
|
|
CounterData *data = g_slice_new (CounterData);
|
|
|
|
data->tag_count = 0;
|
|
g_markup_parse_context_push (context, &counter_subparser, data);
|
|
}
|
|
|
|
gint
|
|
end_counting (GMarkupParseContext *context)
|
|
{
|
|
CounterData *data = g_markup_parse_context_pop (context);
|
|
int result;
|
|
|
|
result = data->tag_count;
|
|
g_slice_free (CounterData, data);
|
|
|
|
return result;
|
|
}
|
|
]|
|
|
|
|
The subparser would then be used as follows:
|
|
|
|
|[<!-- language="C" -->
|
|
static void start_element (context, element_name, ...)
|
|
{
|
|
if (strcmp (element_name, "count-these") == 0)
|
|
start_counting (context);
|
|
|
|
// else, handle other tags...
|
|
}
|
|
|
|
static void end_element (context, element_name, ...)
|
|
{
|
|
if (strcmp (element_name, "count-these") == 0)
|
|
g_print ("Counted %d tags\n", end_counting (context));
|
|
|
|
// else, handle other tags...
|
|
}
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMarkupParseContext</doc>
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="parser" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMarkupParser</doc>
|
|
<type name="MarkupParser" c:type="const GMarkupParser*"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to #GMarkupParser functions</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_markup_parse_context_ref" version="2.36">
|
|
<doc xml:space="preserve">Increases the reference count of @context.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the same @context</doc>
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMarkupParseContext</doc>
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_markup_parse_context_unref" version="2.36">
|
|
<doc xml:space="preserve">Decreases the reference count of @context. When its reference count
|
|
drops to 0, it is freed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMarkupParseContext</doc>
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<bitfield name="MarkupParseFlags" c:type="GMarkupParseFlags">
|
|
<doc xml:space="preserve">Flags that affect the behaviour of the parser.</doc>
|
|
<member name="do_not_use_this_unsupported_flag" value="1" c:identifier="G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG">
|
|
<doc xml:space="preserve">flag you should not use</doc>
|
|
</member>
|
|
<member name="treat_cdata_as_text" value="2" c:identifier="G_MARKUP_TREAT_CDATA_AS_TEXT">
|
|
<doc xml:space="preserve">When this flag is set, CDATA marked
|
|
sections are not passed literally to the @passthrough function of
|
|
the parser. Instead, the content of the section (without the
|
|
`<![CDATA[` and `]]>`) is
|
|
passed to the @text function. This flag was added in GLib 2.12</doc>
|
|
</member>
|
|
<member name="prefix_error_position" value="4" c:identifier="G_MARKUP_PREFIX_ERROR_POSITION">
|
|
<doc xml:space="preserve">Normally errors caught by GMarkup
|
|
itself have line/column information prefixed to them to let the
|
|
caller know the location of the error. When this flag is set the
|
|
location information is also prefixed to errors generated by the
|
|
#GMarkupParser implementation functions</doc>
|
|
</member>
|
|
<member name="ignore_qualified" value="8" c:identifier="G_MARKUP_IGNORE_QUALIFIED">
|
|
<doc xml:space="preserve">Ignore (don't report) qualified
|
|
attributes and tags, along with their contents. A qualified
|
|
attribute or tag is one that contains ':' in its name (ie: is in
|
|
another namespace). Since: 2.40.</doc>
|
|
</member>
|
|
</bitfield>
|
|
<record name="MarkupParser" c:type="GMarkupParser">
|
|
<doc xml:space="preserve">Any of the fields in #GMarkupParser can be %NULL, in which case they
|
|
will be ignored. Except for the @error function, any of these callbacks
|
|
can set an error; in particular the %G_MARKUP_ERROR_UNKNOWN_ELEMENT,
|
|
%G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, and %G_MARKUP_ERROR_INVALID_CONTENT
|
|
errors are intended to be set from these callbacks. If you set an error
|
|
from a callback, g_markup_parse_context_parse() will report that error
|
|
back to its caller.</doc>
|
|
<field name="start_element">
|
|
<callback name="start_element" throws="1">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="context" transfer-ownership="none">
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</parameter>
|
|
<parameter name="element_name" transfer-ownership="none">
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="attribute_names" transfer-ownership="none">
|
|
<type name="utf8" c:type="const gchar**"/>
|
|
</parameter>
|
|
<parameter name="attribute_values" transfer-ownership="none">
|
|
<type name="utf8" c:type="const gchar**"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="4">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="end_element">
|
|
<callback name="end_element" throws="1">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="context" transfer-ownership="none">
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</parameter>
|
|
<parameter name="element_name" transfer-ownership="none">
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="text">
|
|
<callback name="text" throws="1">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="context" transfer-ownership="none">
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</parameter>
|
|
<parameter name="text" transfer-ownership="none">
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="text_len" transfer-ownership="none">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="passthrough">
|
|
<callback name="passthrough" throws="1">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="context" transfer-ownership="none">
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</parameter>
|
|
<parameter name="passthrough_text" transfer-ownership="none">
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="text_len" transfer-ownership="none">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="error">
|
|
<callback name="error">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="context" transfer-ownership="none">
|
|
<type name="MarkupParseContext" c:type="GMarkupParseContext*"/>
|
|
</parameter>
|
|
<parameter name="error" transfer-ownership="none">
|
|
<type name="Error" c:type="GError*"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
</record>
|
|
<record name="MatchInfo" c:type="GMatchInfo" glib:type-name="GMatchInfo" glib:get-type="g_match_info_get_type" c:symbol-prefix="match_info">
|
|
<doc xml:space="preserve">A GMatchInfo is an opaque struct used to return information about
|
|
matches.</doc>
|
|
<method name="expand_references" c:identifier="g_match_info_expand_references" version="2.14" throws="1">
|
|
<doc xml:space="preserve">Returns a new string containing the text in @string_to_expand with
|
|
references and escape sequences expanded. References refer to the last
|
|
match done with @string against @regex and have the same syntax used by
|
|
g_regex_replace().
|
|
|
|
The @string_to_expand must be UTF-8 encoded even if #G_REGEX_RAW was
|
|
passed to g_regex_new().
|
|
|
|
The backreferences are extracted from the string passed to the match
|
|
function, so you cannot call this function after freeing the string.
|
|
|
|
@match_info may be %NULL in which case @string_to_expand must not
|
|
contain references. For instance "foo\n" does not refer to an actual
|
|
pattern and '\n' merely will be replaced with \n character,
|
|
while to expand "\0" (whole match) one needs the result of a match.
|
|
Use g_regex_check_replacement() to find out whether @string_to_expand
|
|
contains references.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the expanded string, or %NULL if an error occurred</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="match_info" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GMatchInfo or %NULL</doc>
|
|
<type name="MatchInfo" c:type="const GMatchInfo*"/>
|
|
</instance-parameter>
|
|
<parameter name="string_to_expand" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to expand</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="fetch" c:identifier="g_match_info_fetch" version="2.14">
|
|
<doc xml:space="preserve">Retrieves the text matching the @match_num'th capturing
|
|
parentheses. 0 is the full text of the match, 1 is the first paren
|
|
set, 2 the second, and so on.
|
|
|
|
If @match_num is a valid sub pattern but it didn't match anything
|
|
(e.g. sub pattern 1, matching "b" against "(a)?b") then an empty
|
|
string is returned.
|
|
|
|
If the match was obtained using the DFA algorithm, that is using
|
|
g_regex_match_all() or g_regex_match_all_full(), the retrieved
|
|
string is not that of a set of parentheses but that of a matched
|
|
substring. Substrings are matched in reverse order of length, so
|
|
0 is the longest match.
|
|
|
|
The string is fetched from the string passed to the match function,
|
|
so you cannot call this function after freeing the string.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">The matched substring, or %NULL if an error
|
|
occurred. You have to free the string yourself</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="match_info" transfer-ownership="none">
|
|
<doc xml:space="preserve">#GMatchInfo structure</doc>
|
|
<type name="MatchInfo" c:type="const GMatchInfo*"/>
|
|
</instance-parameter>
|
|
<parameter name="match_num" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of the sub expression</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="fetch_all" c:identifier="g_match_info_fetch_all" version="2.14">
|
|
<doc xml:space="preserve">Bundles up pointers to each of the matching substrings from a match
|
|
and stores them in an array of gchar pointers. The first element in
|
|
the returned array is the match number 0, i.e. the entire matched
|
|
text.
|
|
|
|
If a sub pattern didn't match anything (e.g. sub pattern 1, matching
|
|
"b" against "(a)?b") then an empty string is inserted.
|
|
|
|
If the last match was obtained using the DFA algorithm, that is using
|
|
g_regex_match_all() or g_regex_match_all_full(), the retrieved
|
|
strings are not that matched by sets of parentheses but that of the
|
|
matched substring. Substrings are matched in reverse order of length,
|
|
so the first one is the longest match.
|
|
|
|
The strings are fetched from the string passed to the match function,
|
|
so you cannot call this function after freeing the string.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a %NULL-terminated array of gchar *
|
|
pointers. It must be freed using g_strfreev(). If the previous
|
|
match failed %NULL is returned</doc>
|
|
<array c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="match_info" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMatchInfo structure</doc>
|
|
<type name="MatchInfo" c:type="const GMatchInfo*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="fetch_named" c:identifier="g_match_info_fetch_named" version="2.14">
|
|
<doc xml:space="preserve">Retrieves the text matching the capturing parentheses named @name.
|
|
|
|
If @name is a valid sub pattern name but it didn't match anything
|
|
(e.g. sub pattern "X", matching "b" against "(?P<X>a)?b")
|
|
then an empty string is returned.
|
|
|
|
The string is fetched from the string passed to the match function,
|
|
so you cannot call this function after freeing the string.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">The matched substring, or %NULL if an error
|
|
occurred. You have to free the string yourself</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="match_info" transfer-ownership="none">
|
|
<doc xml:space="preserve">#GMatchInfo structure</doc>
|
|
<type name="MatchInfo" c:type="const GMatchInfo*"/>
|
|
</instance-parameter>
|
|
<parameter name="name" transfer-ownership="none">
|
|
<doc xml:space="preserve">name of the subexpression</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="fetch_named_pos" c:identifier="g_match_info_fetch_named_pos" version="2.14">
|
|
<doc xml:space="preserve">Retrieves the position in bytes of the capturing parentheses named @name.
|
|
|
|
If @name is a valid sub pattern name but it didn't match anything
|
|
(e.g. sub pattern "X", matching "b" against "(?P<X>a)?b")
|
|
then @start_pos and @end_pos are set to -1 and %TRUE is returned.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the position was fetched, %FALSE otherwise.
|
|
If the position cannot be fetched, @start_pos and @end_pos
|
|
are left unchanged.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="match_info" transfer-ownership="none">
|
|
<doc xml:space="preserve">#GMatchInfo structure</doc>
|
|
<type name="MatchInfo" c:type="const GMatchInfo*"/>
|
|
</instance-parameter>
|
|
<parameter name="name" transfer-ownership="none">
|
|
<doc xml:space="preserve">name of the subexpression</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="start_pos" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">pointer to location where to store
|
|
the start position, or %NULL</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="end_pos" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">pointer to location where to store
|
|
the end position, or %NULL</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="fetch_pos" c:identifier="g_match_info_fetch_pos" version="2.14">
|
|
<doc xml:space="preserve">Retrieves the position in bytes of the @match_num'th capturing
|
|
parentheses. 0 is the full text of the match, 1 is the first
|
|
paren set, 2 the second, and so on.
|
|
|
|
If @match_num is a valid sub pattern but it didn't match anything
|
|
(e.g. sub pattern 1, matching "b" against "(a)?b") then @start_pos
|
|
and @end_pos are set to -1 and %TRUE is returned.
|
|
|
|
If the match was obtained using the DFA algorithm, that is using
|
|
g_regex_match_all() or g_regex_match_all_full(), the retrieved
|
|
position is not that of a set of parentheses but that of a matched
|
|
substring. Substrings are matched in reverse order of length, so
|
|
0 is the longest match.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the position was fetched, %FALSE otherwise. If
|
|
the position cannot be fetched, @start_pos and @end_pos are left
|
|
unchanged</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="match_info" transfer-ownership="none">
|
|
<doc xml:space="preserve">#GMatchInfo structure</doc>
|
|
<type name="MatchInfo" c:type="const GMatchInfo*"/>
|
|
</instance-parameter>
|
|
<parameter name="match_num" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of the sub expression</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="start_pos" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">pointer to location where to store
|
|
the start position, or %NULL</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="end_pos" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">pointer to location where to store
|
|
the end position, or %NULL</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free" c:identifier="g_match_info_free" version="2.14">
|
|
<doc xml:space="preserve">If @match_info is not %NULL, calls g_match_info_unref(); otherwise does
|
|
nothing.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="match_info" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GMatchInfo, or %NULL</doc>
|
|
<type name="MatchInfo" c:type="GMatchInfo*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_match_count" c:identifier="g_match_info_get_match_count" version="2.14">
|
|
<doc xml:space="preserve">Retrieves the number of matched substrings (including substring 0,
|
|
that is the whole matched text), so 1 is returned if the pattern
|
|
has no substrings in it and 0 is returned if the match failed.
|
|
|
|
If the last match was obtained using the DFA algorithm, that is
|
|
using g_regex_match_all() or g_regex_match_all_full(), the retrieved
|
|
count is not that of the number of capturing parentheses but that of
|
|
the number of matched substrings.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">Number of matched substrings, or -1 if an error occurred</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="match_info" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMatchInfo structure</doc>
|
|
<type name="MatchInfo" c:type="const GMatchInfo*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_regex" c:identifier="g_match_info_get_regex" version="2.14">
|
|
<doc xml:space="preserve">Returns #GRegex object used in @match_info. It belongs to Glib
|
|
and must not be freed. Use g_regex_ref() if you need to keep it
|
|
after you free @match_info object.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">#GRegex object used in @match_info</doc>
|
|
<type name="Regex" c:type="GRegex*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="match_info" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMatchInfo</doc>
|
|
<type name="MatchInfo" c:type="const GMatchInfo*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_string" c:identifier="g_match_info_get_string" version="2.14">
|
|
<doc xml:space="preserve">Returns the string searched with @match_info. This is the
|
|
string passed to g_regex_match() or g_regex_replace() so
|
|
you may not free it before calling this function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the string searched with @match_info</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="match_info" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMatchInfo</doc>
|
|
<type name="MatchInfo" c:type="const GMatchInfo*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_partial_match" c:identifier="g_match_info_is_partial_match" version="2.14">
|
|
<doc xml:space="preserve">Usually if the string passed to g_regex_match*() matches as far as
|
|
it goes, but is too short to match the entire pattern, %FALSE is
|
|
returned. There are circumstances where it might be helpful to
|
|
distinguish this case from other cases in which there is no match.
|
|
|
|
Consider, for example, an application where a human is required to
|
|
type in data for a field with specific formatting requirements. An
|
|
example might be a date in the form ddmmmyy, defined by the pattern
|
|
"^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$".
|
|
If the application sees the user’s keystrokes one by one, and can
|
|
check that what has been typed so far is potentially valid, it is
|
|
able to raise an error as soon as a mistake is made.
|
|
|
|
GRegex supports the concept of partial matching by means of the
|
|
#G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD flags.
|
|
When they are used, the return code for
|
|
g_regex_match() or g_regex_match_full() is, as usual, %TRUE
|
|
for a complete match, %FALSE otherwise. But, when these functions
|
|
return %FALSE, you can check if the match was partial calling
|
|
g_match_info_is_partial_match().
|
|
|
|
The difference between #G_REGEX_MATCH_PARTIAL_SOFT and
|
|
#G_REGEX_MATCH_PARTIAL_HARD is that when a partial match is encountered
|
|
with #G_REGEX_MATCH_PARTIAL_SOFT, matching continues to search for a
|
|
possible complete match, while with #G_REGEX_MATCH_PARTIAL_HARD matching
|
|
stops at the partial match.
|
|
When both #G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD
|
|
are set, the latter takes precedence.
|
|
|
|
There were formerly some restrictions on the pattern for partial matching.
|
|
The restrictions no longer apply.
|
|
|
|
See pcrepartial(3) for more information on partial matching.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the match was partial, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="match_info" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMatchInfo structure</doc>
|
|
<type name="MatchInfo" c:type="const GMatchInfo*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="matches" c:identifier="g_match_info_matches" version="2.14">
|
|
<doc xml:space="preserve">Returns whether the previous match operation succeeded.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the previous match operation succeeded,
|
|
%FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="match_info" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMatchInfo structure</doc>
|
|
<type name="MatchInfo" c:type="const GMatchInfo*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="next" c:identifier="g_match_info_next" version="2.14" throws="1">
|
|
<doc xml:space="preserve">Scans for the next match using the same parameters of the previous
|
|
call to g_regex_match_full() or g_regex_match() that returned
|
|
@match_info.
|
|
|
|
The match is done on the string passed to the match function, so you
|
|
cannot free it before calling this function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE is the string matched, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="match_info" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMatchInfo structure</doc>
|
|
<type name="MatchInfo" c:type="GMatchInfo*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_match_info_ref" version="2.30">
|
|
<doc xml:space="preserve">Increases reference count of @match_info by 1.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">@match_info</doc>
|
|
<type name="MatchInfo" c:type="GMatchInfo*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="match_info" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMatchInfo</doc>
|
|
<type name="MatchInfo" c:type="GMatchInfo*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_match_info_unref" version="2.30">
|
|
<doc xml:space="preserve">Decreases reference count of @match_info by 1. When reference count drops
|
|
to zero, it frees all the memory associated with the match_info structure.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="match_info" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMatchInfo</doc>
|
|
<type name="MatchInfo" c:type="GMatchInfo*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<record name="MemVTable" c:type="GMemVTable">
|
|
<doc xml:space="preserve">A set of functions used to perform memory allocation. The same #GMemVTable must
|
|
be used for all allocations in the same program; a call to g_mem_set_vtable(),
|
|
if it exists, should be prior to any use of GLib.
|
|
|
|
This functions related to this has been deprecated in 2.46, and no longer work.</doc>
|
|
<field name="malloc">
|
|
<callback name="malloc">
|
|
<return-value transfer-ownership="none">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="n_bytes" transfer-ownership="none">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="realloc">
|
|
<callback name="realloc">
|
|
<return-value transfer-ownership="none">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mem" transfer-ownership="none">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="n_bytes" transfer-ownership="none">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="free">
|
|
<callback name="free">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mem" transfer-ownership="none">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="calloc">
|
|
<callback name="calloc">
|
|
<return-value transfer-ownership="none">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="n_blocks" transfer-ownership="none">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="n_block_bytes" transfer-ownership="none">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="try_malloc">
|
|
<callback name="try_malloc">
|
|
<return-value transfer-ownership="none">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="n_bytes" transfer-ownership="none">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="try_realloc">
|
|
<callback name="try_realloc">
|
|
<return-value transfer-ownership="none">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mem" transfer-ownership="none">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="n_bytes" transfer-ownership="none">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
</record>
|
|
<union name="Mutex" c:type="GMutex">
|
|
<doc xml:space="preserve">The #GMutex struct is an opaque data structure to represent a mutex
|
|
(mutual exclusion). It can be used to protect data against shared
|
|
access.
|
|
|
|
Take for example the following function:
|
|
|[<!-- language="C" -->
|
|
int
|
|
give_me_next_number (void)
|
|
{
|
|
static int current_number = 0;
|
|
|
|
// now do a very complicated calculation to calculate the new
|
|
// number, this might for example be a random number generator
|
|
current_number = calc_next_number (current_number);
|
|
|
|
return current_number;
|
|
}
|
|
]|
|
|
It is easy to see that this won't work in a multi-threaded
|
|
application. There current_number must be protected against shared
|
|
access. A #GMutex can be used as a solution to this problem:
|
|
|[<!-- language="C" -->
|
|
int
|
|
give_me_next_number (void)
|
|
{
|
|
static GMutex mutex;
|
|
static int current_number = 0;
|
|
int ret_val;
|
|
|
|
g_mutex_lock (&mutex);
|
|
ret_val = current_number = calc_next_number (current_number);
|
|
g_mutex_unlock (&mutex);
|
|
|
|
return ret_val;
|
|
}
|
|
]|
|
|
Notice that the #GMutex is not initialised to any particular value.
|
|
Its placement in static storage ensures that it will be initialised
|
|
to all-zeros, which is appropriate.
|
|
|
|
If a #GMutex is placed in other contexts (eg: embedded in a struct)
|
|
then it must be explicitly initialised using g_mutex_init().
|
|
|
|
A #GMutex should only be accessed via g_mutex_ functions.</doc>
|
|
<field name="p" readable="0" private="1">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="i" readable="0" private="1">
|
|
<array zero-terminated="0" fixed-size="2">
|
|
<type name="guint" c:type="guint"/>
|
|
</array>
|
|
</field>
|
|
<method name="clear" c:identifier="g_mutex_clear">
|
|
<doc xml:space="preserve">Frees the resources allocated to a mutex with g_mutex_init().
|
|
|
|
This function should not be used with a #GMutex that has been
|
|
statically allocated.
|
|
|
|
Calling g_mutex_clear() on a locked mutex leads to undefined
|
|
behaviour.
|
|
|
|
Sine: 2.32</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="mutex" transfer-ownership="none">
|
|
<doc xml:space="preserve">an initialized #GMutex</doc>
|
|
<type name="Mutex" c:type="GMutex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="init" c:identifier="g_mutex_init" version="2.32">
|
|
<doc xml:space="preserve">Initializes a #GMutex so that it can be used.
|
|
|
|
This function is useful to initialize a mutex that has been
|
|
allocated on the stack, or as part of a larger structure.
|
|
It is not necessary to initialize a mutex that has been
|
|
statically allocated.
|
|
|
|
|[<!-- language="C" -->
|
|
typedef struct {
|
|
GMutex m;
|
|
...
|
|
} Blob;
|
|
|
|
Blob *b;
|
|
|
|
b = g_new (Blob, 1);
|
|
g_mutex_init (&b->m);
|
|
]|
|
|
|
|
To undo the effect of g_mutex_init() when a mutex is no longer
|
|
needed, use g_mutex_clear().
|
|
|
|
Calling g_mutex_init() on an already initialized #GMutex leads
|
|
to undefined behaviour.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="mutex" transfer-ownership="none">
|
|
<doc xml:space="preserve">an uninitialized #GMutex</doc>
|
|
<type name="Mutex" c:type="GMutex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="lock" c:identifier="g_mutex_lock">
|
|
<doc xml:space="preserve">Locks @mutex. If @mutex is already locked by another thread, the
|
|
current thread will block until @mutex is unlocked by the other
|
|
thread.
|
|
|
|
#GMutex is neither guaranteed to be recursive nor to be
|
|
non-recursive. As such, calling g_mutex_lock() on a #GMutex that has
|
|
already been locked by the same thread results in undefined behaviour
|
|
(including but not limited to deadlocks).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="mutex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMutex</doc>
|
|
<type name="Mutex" c:type="GMutex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="trylock" c:identifier="g_mutex_trylock">
|
|
<doc xml:space="preserve">Tries to lock @mutex. If @mutex is already locked by another thread,
|
|
it immediately returns %FALSE. Otherwise it locks @mutex and returns
|
|
%TRUE.
|
|
|
|
#GMutex is neither guaranteed to be recursive nor to be
|
|
non-recursive. As such, calling g_mutex_lock() on a #GMutex that has
|
|
already been locked by the same thread results in undefined behaviour
|
|
(including but not limited to deadlocks or arbitrary return values).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @mutex could be locked</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="mutex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMutex</doc>
|
|
<type name="Mutex" c:type="GMutex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unlock" c:identifier="g_mutex_unlock">
|
|
<doc xml:space="preserve">Unlocks @mutex. If another thread is blocked in a g_mutex_lock()
|
|
call for @mutex, it will become unblocked and can lock @mutex itself.
|
|
|
|
Calling g_mutex_unlock() on a mutex that is not locked by the
|
|
current thread leads to undefined behaviour.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="mutex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GMutex</doc>
|
|
<type name="Mutex" c:type="GMutex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
</union>
|
|
<function-macro name="NODE_IS_LEAF" c:identifier="G_NODE_IS_LEAF" introspectable="0">
|
|
<doc xml:space="preserve">Returns %TRUE if a #GNode is a leaf node.</doc>
|
|
<parameters>
|
|
<parameter name="node">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="NODE_IS_ROOT" c:identifier="G_NODE_IS_ROOT" introspectable="0">
|
|
<doc xml:space="preserve">Returns %TRUE if a #GNode is the root of a tree.</doc>
|
|
<parameters>
|
|
<parameter name="node">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="N_ELEMENTS" c:identifier="G_N_ELEMENTS" introspectable="0">
|
|
<doc xml:space="preserve">Determines the number of elements in an array. The array must be
|
|
declared so the compiler knows its size at compile-time; this
|
|
macro will not work on an array allocated on the heap, only static
|
|
arrays or arrays on the stack.</doc>
|
|
<parameters>
|
|
<parameter name="arr">
|
|
<doc xml:space="preserve">the array</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<record name="Node" c:type="GNode">
|
|
<doc xml:space="preserve">The #GNode struct represents one node in a [n-ary tree][glib-N-ary-Trees].</doc>
|
|
<field name="data" writable="1">
|
|
<doc xml:space="preserve">contains the actual data of the node.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="next" writable="1">
|
|
<doc xml:space="preserve">points to the node's next sibling (a sibling is another
|
|
#GNode with the same parent).</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</field>
|
|
<field name="prev" writable="1">
|
|
<doc xml:space="preserve">points to the node's previous sibling.</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</field>
|
|
<field name="parent" writable="1">
|
|
<doc xml:space="preserve">points to the parent of the #GNode, or is %NULL if the
|
|
#GNode is the root of the tree.</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</field>
|
|
<field name="children" writable="1">
|
|
<doc xml:space="preserve">points to the first child of the #GNode. The other
|
|
children are accessed by using the @next pointer of each
|
|
child.</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</field>
|
|
<method name="child_index" c:identifier="g_node_child_index">
|
|
<doc xml:space="preserve">Gets the position of the first child of a #GNode
|
|
which contains the given data.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the child of @node which contains
|
|
@data, or -1 if the data is not found</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to find</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="child_position" c:identifier="g_node_child_position">
|
|
<doc xml:space="preserve">Gets the position of a #GNode with respect to its siblings.
|
|
@child must be a child of @node. The first child is numbered 0,
|
|
the second 1, and so on.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the position of @child with respect to its siblings</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
<parameter name="child" transfer-ownership="none">
|
|
<doc xml:space="preserve">a child of @node</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="children_foreach" c:identifier="g_node_children_foreach" introspectable="0">
|
|
<doc xml:space="preserve">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.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">which types of children are to be visited, one of
|
|
%G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES</doc>
|
|
<type name="TraverseFlags" c:type="GTraverseFlags"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function to call for each visited node</doc>
|
|
<type name="NodeForeachFunc" c:type="GNodeForeachFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to the function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="copy" c:identifier="g_node_copy" introspectable="0">
|
|
<doc xml:space="preserve">Recursively copies a #GNode (but does not deep-copy the data inside the
|
|
nodes, see g_node_copy_deep() if you need that).</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a new #GNode containing the same data pointers</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="copy_deep" c:identifier="g_node_copy_deep" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Recursively copies a #GNode and its data.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a new #GNode containing copies of the data in @node.</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
<parameter name="copy_func" transfer-ownership="none" closure="1">
|
|
<doc xml:space="preserve">the function which is called to copy the data inside each node,
|
|
or %NULL to use the original data.</doc>
|
|
<type name="CopyFunc" c:type="GCopyFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @copy_func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="depth" c:identifier="g_node_depth">
|
|
<doc xml:space="preserve">Gets the depth of a #GNode.
|
|
|
|
If @node is %NULL the depth is 0. The root node has a depth of 1.
|
|
For the children of the root node the depth is 2. And so on.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the depth of the #GNode</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="destroy" c:identifier="g_node_destroy">
|
|
<doc xml:space="preserve">Removes @root and its children from the tree, freeing any memory
|
|
allocated.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="root" transfer-ownership="none">
|
|
<doc xml:space="preserve">the root of the tree/subtree to destroy</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="find" c:identifier="g_node_find" introspectable="0">
|
|
<doc xml:space="preserve">Finds a #GNode in a tree.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the found #GNode, or %NULL if the data is not found</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="root" transfer-ownership="none">
|
|
<doc xml:space="preserve">the root #GNode of the tree to search</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
<parameter name="order" transfer-ownership="none">
|
|
<doc xml:space="preserve">the order in which nodes are visited - %G_IN_ORDER,
|
|
%G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER</doc>
|
|
<type name="TraverseType" c:type="GTraverseType"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">which types of children are to be searched, one of
|
|
%G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES</doc>
|
|
<type name="TraverseFlags" c:type="GTraverseFlags"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to find</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="find_child" c:identifier="g_node_find_child" introspectable="0">
|
|
<doc xml:space="preserve">Finds the first child of a #GNode with the given data.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the found child #GNode, or %NULL if the data is not found</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">which types of children are to be searched, one of
|
|
%G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES</doc>
|
|
<type name="TraverseFlags" c:type="GTraverseFlags"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to find</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="first_sibling" c:identifier="g_node_first_sibling" introspectable="0">
|
|
<doc xml:space="preserve">Gets the first sibling of a #GNode.
|
|
This could possibly be the node itself.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the first sibling of @node</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_root" c:identifier="g_node_get_root" introspectable="0">
|
|
<doc xml:space="preserve">Gets the root of a tree.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the root of the tree</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert" c:identifier="g_node_insert" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a #GNode beneath the parent at the given position.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the inserted #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="parent" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GNode to place @node under</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
<parameter name="position" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position to place @node at, with respect to its siblings
|
|
If position is -1, @node is inserted as the last child of @parent</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GNode to insert</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert_after" c:identifier="g_node_insert_after" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a #GNode beneath the parent after the given sibling.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the inserted #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="parent" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GNode to place @node under</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
<parameter name="sibling" transfer-ownership="none">
|
|
<doc xml:space="preserve">the sibling #GNode to place @node after.
|
|
If sibling is %NULL, the node is inserted as the first child of @parent.</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</parameter>
|
|
<parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GNode to insert</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert_before" c:identifier="g_node_insert_before" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a #GNode beneath the parent before the given sibling.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the inserted #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="parent" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GNode to place @node under</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
<parameter name="sibling" transfer-ownership="none">
|
|
<doc xml:space="preserve">the sibling #GNode to place @node before.
|
|
If sibling is %NULL, the node is inserted as the last child of @parent.</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</parameter>
|
|
<parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GNode to insert</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_ancestor" c:identifier="g_node_is_ancestor">
|
|
<doc xml:space="preserve">Returns %TRUE if @node is an ancestor of @descendant.
|
|
This is true if node is the parent of @descendant,
|
|
or if node is the grandparent of @descendant etc.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @node is an ancestor of @descendant</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
<parameter name="descendant" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="last_child" c:identifier="g_node_last_child" introspectable="0">
|
|
<doc xml:space="preserve">Gets the last child of a #GNode.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the last child of @node, or %NULL if @node has no children</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode (must not be %NULL)</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="last_sibling" c:identifier="g_node_last_sibling" introspectable="0">
|
|
<doc xml:space="preserve">Gets the last sibling of a #GNode.
|
|
This could possibly be the node itself.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the last sibling of @node</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="max_height" c:identifier="g_node_max_height">
|
|
<doc xml:space="preserve">Gets the maximum height of all branches beneath a #GNode.
|
|
This is the maximum distance from the #GNode to all leaf nodes.
|
|
|
|
If @root is %NULL, 0 is returned. If @root has no children,
|
|
1 is returned. If @root has children, 2 is returned. And so on.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum height of the tree beneath @root</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="root" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="n_children" c:identifier="g_node_n_children">
|
|
<doc xml:space="preserve">Gets the number of children of a #GNode.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of children of @node</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="n_nodes" c:identifier="g_node_n_nodes">
|
|
<doc xml:space="preserve">Gets the number of nodes in a tree.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of nodes in the tree</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="root" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">which types of children are to be counted, one of
|
|
%G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES</doc>
|
|
<type name="TraverseFlags" c:type="GTraverseFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="nth_child" c:identifier="g_node_nth_child" introspectable="0">
|
|
<doc xml:space="preserve">Gets a child of a #GNode, using the given index.
|
|
The first child is at index 0. If the index is
|
|
too big, %NULL is returned.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the child of @node at index @n</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the desired child</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="prepend" c:identifier="g_node_prepend" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a #GNode as the first child of the given parent.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the inserted #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="parent" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GNode to place the new #GNode under</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
<parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GNode to insert</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="reverse_children" c:identifier="g_node_reverse_children">
|
|
<doc xml:space="preserve">Reverses the order of the children of a #GNode.
|
|
(It doesn't change the order of the grandchildren.)</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode.</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="traverse" c:identifier="g_node_traverse" introspectable="0">
|
|
<doc xml:space="preserve">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.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="root" transfer-ownership="none">
|
|
<doc xml:space="preserve">the root #GNode of the tree to traverse</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
<parameter name="order" transfer-ownership="none">
|
|
<doc xml:space="preserve">the order in which nodes are visited - %G_IN_ORDER,
|
|
%G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER.</doc>
|
|
<type name="TraverseType" c:type="GTraverseType"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">which types of children are to be visited, one of
|
|
%G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES</doc>
|
|
<type name="TraverseFlags" c:type="GTraverseFlags"/>
|
|
</parameter>
|
|
<parameter name="max_depth" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum depth of the traversal. Nodes below this
|
|
depth will not be visited. If max_depth is -1 all nodes in
|
|
the tree are visited. If depth is 1, only the root is visited.
|
|
If depth is 2, the root and its children are visited. And so on.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="4">
|
|
<doc xml:space="preserve">the function to call for each visited #GNode</doc>
|
|
<type name="NodeTraverseFunc" c:type="GNodeTraverseFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to the function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unlink" c:identifier="g_node_unlink">
|
|
<doc xml:space="preserve">Unlinks a #GNode from a tree, resulting in two separate trees.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GNode to unlink, which becomes the root of a new tree</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="new" c:identifier="g_node_new" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GNode containing the given data.
|
|
Used to create the first node in a tree.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a new #GNode</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data of the new node</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<callback name="NodeForeachFunc" c:type="GNodeForeachFunc">
|
|
<doc xml:space="preserve">Specifies the type of function passed to g_node_children_foreach().
|
|
The function is called with each child node, together with the user
|
|
data passed to g_node_children_foreach().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode.</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to g_node_children_foreach().</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<callback name="NodeTraverseFunc" c:type="GNodeTraverseFunc">
|
|
<doc xml:space="preserve">Specifies the type of function passed to g_node_traverse(). The
|
|
function is called with each of the nodes visited, together with the
|
|
user data passed to g_node_traverse(). If the function returns
|
|
%TRUE, then the traversal is stopped.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE to stop the traversal.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="node" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GNode.</doc>
|
|
<type name="Node" c:type="GNode*"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to g_node_traverse().</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<enumeration name="NormalizeMode" c:type="GNormalizeMode">
|
|
<doc xml:space="preserve">Defines how a Unicode string is transformed in a canonical
|
|
form, standardizing such issues as whether a character with
|
|
an accent is represented as a base character and combining
|
|
accent or as a single precomposed character. Unicode strings
|
|
should generally be normalized before comparing them.</doc>
|
|
<member name="default" value="0" c:identifier="G_NORMALIZE_DEFAULT">
|
|
<doc xml:space="preserve">standardize differences that do not affect the
|
|
text content, such as the above-mentioned accent representation</doc>
|
|
</member>
|
|
<member name="nfd" value="0" c:identifier="G_NORMALIZE_NFD">
|
|
<doc xml:space="preserve">another name for %G_NORMALIZE_DEFAULT</doc>
|
|
</member>
|
|
<member name="default_compose" value="1" c:identifier="G_NORMALIZE_DEFAULT_COMPOSE">
|
|
<doc xml:space="preserve">like %G_NORMALIZE_DEFAULT, but with
|
|
composed forms rather than a maximally decomposed form</doc>
|
|
</member>
|
|
<member name="nfc" value="1" c:identifier="G_NORMALIZE_NFC">
|
|
<doc xml:space="preserve">another name for %G_NORMALIZE_DEFAULT_COMPOSE</doc>
|
|
</member>
|
|
<member name="all" value="2" c:identifier="G_NORMALIZE_ALL">
|
|
<doc xml:space="preserve">beyond %G_NORMALIZE_DEFAULT also standardize the
|
|
"compatibility" characters in Unicode, such as SUPERSCRIPT THREE
|
|
to the standard forms (in this case DIGIT THREE). Formatting
|
|
information may be lost but for most text operations such
|
|
characters should be considered the same</doc>
|
|
</member>
|
|
<member name="nfkd" value="2" c:identifier="G_NORMALIZE_NFKD">
|
|
<doc xml:space="preserve">another name for %G_NORMALIZE_ALL</doc>
|
|
</member>
|
|
<member name="all_compose" value="3" c:identifier="G_NORMALIZE_ALL_COMPOSE">
|
|
<doc xml:space="preserve">like %G_NORMALIZE_ALL, but with composed
|
|
forms rather than a maximally decomposed form</doc>
|
|
</member>
|
|
<member name="nfkc" value="3" c:identifier="G_NORMALIZE_NFKC">
|
|
<doc xml:space="preserve">another name for %G_NORMALIZE_ALL_COMPOSE</doc>
|
|
</member>
|
|
</enumeration>
|
|
<enumeration name="NumberParserError" version="2.54" c:type="GNumberParserError" glib:error-domain="g-number-parser-error-quark">
|
|
<doc xml:space="preserve">Error codes returned by functions converting a string to a number.</doc>
|
|
<member name="invalid" value="0" c:identifier="G_NUMBER_PARSER_ERROR_INVALID">
|
|
<doc xml:space="preserve">String was not a valid number.</doc>
|
|
</member>
|
|
<member name="out_of_bounds" value="1" c:identifier="G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS">
|
|
<doc xml:space="preserve">String was a number, but out of bounds.</doc>
|
|
</member>
|
|
</enumeration>
|
|
<constant name="OPTION_REMAINING" value="" c:type="G_OPTION_REMAINING" version="2.6">
|
|
<doc xml:space="preserve">If a long option in the main group has this name, it is not treated as a
|
|
regular option. Instead it collects all non-option arguments which would
|
|
otherwise be left in `argv`. The option must be of type
|
|
%G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY
|
|
or %G_OPTION_ARG_FILENAME_ARRAY.
|
|
|
|
|
|
Using #G_OPTION_REMAINING instead of simply scanning `argv`
|
|
for leftover arguments has the advantage that GOption takes care of
|
|
necessary encoding conversions for strings or filenames.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<record name="Once" c:type="GOnce" version="2.4">
|
|
<doc xml:space="preserve">A #GOnce struct controls a one-time initialization function. Any
|
|
one-time initialization function must have its own unique #GOnce
|
|
struct.</doc>
|
|
<field name="status" writable="1">
|
|
<doc xml:space="preserve">the status of the #GOnce</doc>
|
|
<type name="OnceStatus" c:type="volatile GOnceStatus"/>
|
|
</field>
|
|
<field name="retval" writable="1">
|
|
<doc xml:space="preserve">the value returned by the call to the function, if @status
|
|
is %G_ONCE_STATUS_READY</doc>
|
|
<type name="gpointer" c:type="volatile gpointer"/>
|
|
</field>
|
|
<method name="impl" c:identifier="g_once_impl" introspectable="0">
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="once" transfer-ownership="none">
|
|
<type name="Once" c:type="GOnce*"/>
|
|
</instance-parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<type name="ThreadFunc" c:type="GThreadFunc"/>
|
|
</parameter>
|
|
<parameter name="arg" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="init_enter" c:identifier="g_once_init_enter" version="2.14">
|
|
<doc xml:space="preserve">Function to be called when starting a critical initialization
|
|
section. The argument @location must point to a static
|
|
0-initialized variable that will be set to a value other than 0 at
|
|
the end of the initialization section. In combination with
|
|
g_once_init_leave() and the unique address @value_location, it can
|
|
be ensured that an initialization section will be executed only once
|
|
during a program's life time, and that concurrent threads are
|
|
blocked until initialization completed. To be used in constructs
|
|
like this:
|
|
|
|
|[<!-- language="C" -->
|
|
static gsize initialization_value = 0;
|
|
|
|
if (g_once_init_enter (&initialization_value))
|
|
{
|
|
gsize setup_value = 42; // initialization code here
|
|
|
|
g_once_init_leave (&initialization_value, setup_value);
|
|
}
|
|
|
|
// use initialization_value here
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the initialization section should be entered,
|
|
%FALSE and blocks otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="location" transfer-ownership="none">
|
|
<doc xml:space="preserve">location of a static initializable variable
|
|
containing 0</doc>
|
|
<type name="gpointer" c:type="void*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="init_leave" c:identifier="g_once_init_leave" version="2.14">
|
|
<doc xml:space="preserve">Counterpart to g_once_init_enter(). Expects a location of a static
|
|
0-initialized initialization variable, and an initialization value
|
|
other than 0. Sets the variable to the initialization value, and
|
|
releases concurrent threads blocking in g_once_init_enter() on this
|
|
initialization variable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="location" transfer-ownership="none">
|
|
<doc xml:space="preserve">location of a static initializable variable
|
|
containing 0</doc>
|
|
<type name="gpointer" c:type="void*"/>
|
|
</parameter>
|
|
<parameter name="result" transfer-ownership="none">
|
|
<doc xml:space="preserve">new non-0 value for *@value_location</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<enumeration name="OnceStatus" version="2.4" c:type="GOnceStatus">
|
|
<doc xml:space="preserve">The possible statuses of a one-time initialization function
|
|
controlled by a #GOnce struct.</doc>
|
|
<member name="notcalled" value="0" c:identifier="G_ONCE_STATUS_NOTCALLED">
|
|
<doc xml:space="preserve">the function has not been called yet.</doc>
|
|
</member>
|
|
<member name="progress" value="1" c:identifier="G_ONCE_STATUS_PROGRESS">
|
|
<doc xml:space="preserve">the function call is currently in progress.</doc>
|
|
</member>
|
|
<member name="ready" value="2" c:identifier="G_ONCE_STATUS_READY">
|
|
<doc xml:space="preserve">the function has been called.</doc>
|
|
</member>
|
|
</enumeration>
|
|
<enumeration name="OptionArg" c:type="GOptionArg">
|
|
<doc xml:space="preserve">The #GOptionArg enum values determine which type of extra argument the
|
|
options expect to find. If an option expects an extra argument, it can
|
|
be specified in several ways; with a short option: `-x arg`, with a long
|
|
option: `--name arg` or combined in a single argument: `--name=arg`.</doc>
|
|
<member name="none" value="0" c:identifier="G_OPTION_ARG_NONE">
|
|
<doc xml:space="preserve">No extra argument. This is useful for simple flags.</doc>
|
|
</member>
|
|
<member name="string" value="1" c:identifier="G_OPTION_ARG_STRING">
|
|
<doc xml:space="preserve">The option takes a UTF-8 string argument.</doc>
|
|
</member>
|
|
<member name="int" value="2" c:identifier="G_OPTION_ARG_INT">
|
|
<doc xml:space="preserve">The option takes an integer argument.</doc>
|
|
</member>
|
|
<member name="callback" value="3" c:identifier="G_OPTION_ARG_CALLBACK">
|
|
<doc xml:space="preserve">The option provides a callback (of type
|
|
#GOptionArgFunc) to parse the extra argument.</doc>
|
|
</member>
|
|
<member name="filename" value="4" c:identifier="G_OPTION_ARG_FILENAME">
|
|
<doc xml:space="preserve">The option takes a filename as argument, which will
|
|
be in the GLib filename encoding rather than UTF-8.</doc>
|
|
</member>
|
|
<member name="string_array" value="5" c:identifier="G_OPTION_ARG_STRING_ARRAY">
|
|
<doc xml:space="preserve">The option takes a string argument, multiple
|
|
uses of the option are collected into an array of strings.</doc>
|
|
</member>
|
|
<member name="filename_array" value="6" c:identifier="G_OPTION_ARG_FILENAME_ARRAY">
|
|
<doc xml:space="preserve">The option takes a filename as argument,
|
|
multiple uses of the option are collected into an array of strings.</doc>
|
|
</member>
|
|
<member name="double" value="7" c:identifier="G_OPTION_ARG_DOUBLE">
|
|
<doc xml:space="preserve">The option takes a double argument. The argument
|
|
can be formatted either for the user's locale or for the "C" locale.
|
|
Since 2.12</doc>
|
|
</member>
|
|
<member name="int64" value="8" c:identifier="G_OPTION_ARG_INT64">
|
|
<doc xml:space="preserve">The option takes a 64-bit integer. Like
|
|
%G_OPTION_ARG_INT but for larger numbers. The number can be in
|
|
decimal base, or in hexadecimal (when prefixed with `0x`, for
|
|
example, `0xffffffff`). Since 2.12</doc>
|
|
</member>
|
|
</enumeration>
|
|
<callback name="OptionArgFunc" c:type="GOptionArgFunc" throws="1">
|
|
<doc xml:space="preserve">The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
|
|
options.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the option was successfully parsed, %FALSE if an error
|
|
occurred, in which case @error should be set with g_set_error()</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="option_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">The name of the option being parsed. This will be either a
|
|
single dash followed by a single letter (for a short name) or two dashes
|
|
followed by a long option name.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">The value to be parsed.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">User data added to the #GOptionGroup containing the option when it
|
|
was created with g_option_group_new()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<record name="OptionContext" c:type="GOptionContext" disguised="1">
|
|
<doc xml:space="preserve">A `GOptionContext` struct defines which options
|
|
are accepted by the commandline option parser. The struct has only private
|
|
fields and should not be directly accessed.</doc>
|
|
<method name="add_group" c:identifier="g_option_context_add_group" version="2.6">
|
|
<doc xml:space="preserve">Adds a #GOptionGroup to the @context, so that parsing with @context
|
|
will recognize the options in the group. Note that this will take
|
|
ownership of the @group and thus the @group should not be freed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="group" transfer-ownership="full">
|
|
<doc xml:space="preserve">the group to add</doc>
|
|
<type name="OptionGroup" c:type="GOptionGroup*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_main_entries" c:identifier="g_option_context_add_main_entries" version="2.6">
|
|
<doc xml:space="preserve">A convenience function which creates a main group if it doesn't
|
|
exist, adds the @entries to it and sets the translation domain.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="entries" transfer-ownership="none">
|
|
<doc xml:space="preserve">a %NULL-terminated array of #GOptionEntrys</doc>
|
|
<array c:type="const GOptionEntry*">
|
|
<type name="OptionEntry" c:type="GOptionEntry"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="translation_domain" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a translation domain to use for translating
|
|
the `--help` output for the options in @entries
|
|
with gettext(), or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free" c:identifier="g_option_context_free" version="2.6">
|
|
<doc xml:space="preserve">Frees context and all the groups which have been
|
|
added to it.
|
|
|
|
Please note that parsed arguments need to be freed separately (see
|
|
#GOptionEntry).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_description" c:identifier="g_option_context_get_description" version="2.12">
|
|
<doc xml:space="preserve">Returns the description. See g_option_context_set_description().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the description</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_help" c:identifier="g_option_context_get_help" version="2.14">
|
|
<doc xml:space="preserve">Returns a formatted, translated help text for the given context.
|
|
To obtain the text produced by `--help`, call
|
|
`g_option_context_get_help (context, TRUE, NULL)`.
|
|
To obtain the text produced by `--help-all`, call
|
|
`g_option_context_get_help (context, FALSE, NULL)`.
|
|
To obtain the help text for an option group, call
|
|
`g_option_context_get_help (context, FALSE, group)`.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">A newly allocated string containing the help text</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="main_help" transfer-ownership="none">
|
|
<doc xml:space="preserve">if %TRUE, only include the main group</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
<parameter name="group" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the #GOptionGroup to create help for, or %NULL</doc>
|
|
<type name="OptionGroup" c:type="GOptionGroup*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_help_enabled" c:identifier="g_option_context_get_help_enabled" version="2.6">
|
|
<doc xml:space="preserve">Returns whether automatic `--help` generation
|
|
is turned on for @context. See g_option_context_set_help_enabled().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if automatic help generation is turned on.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_ignore_unknown_options" c:identifier="g_option_context_get_ignore_unknown_options" version="2.6">
|
|
<doc xml:space="preserve">Returns whether unknown options are ignored or not. See
|
|
g_option_context_set_ignore_unknown_options().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if unknown options are ignored.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_main_group" c:identifier="g_option_context_get_main_group" version="2.6">
|
|
<doc xml:space="preserve">Returns a pointer to the main group of @context.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the main group of @context, or %NULL if
|
|
@context doesn't have a main group. Note that group belongs to
|
|
@context and should not be modified or freed.</doc>
|
|
<type name="OptionGroup" c:type="GOptionGroup*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_strict_posix" c:identifier="g_option_context_get_strict_posix" version="2.44">
|
|
<doc xml:space="preserve">Returns whether strict POSIX code is enabled.
|
|
|
|
See g_option_context_set_strict_posix() for more information.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if strict POSIX is enabled, %FALSE otherwise.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_summary" c:identifier="g_option_context_get_summary" version="2.12">
|
|
<doc xml:space="preserve">Returns the summary. See g_option_context_set_summary().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the summary</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="parse" c:identifier="g_option_context_parse" version="2.6" throws="1">
|
|
<doc xml:space="preserve">Parses the command line arguments, recognizing options
|
|
which have been added to @context. A side-effect of
|
|
calling this function is that g_set_prgname() will be
|
|
called.
|
|
|
|
If the parsing is successful, any parsed arguments are
|
|
removed from the array and @argc and @argv are updated
|
|
accordingly. A '--' option is stripped from @argv
|
|
unless there are unparsed options before and after it,
|
|
or some of the options after it start with '-'. In case
|
|
of an error, @argc and @argv are left unmodified.
|
|
|
|
If automatic `--help` support is enabled
|
|
(see g_option_context_set_help_enabled()), and the
|
|
@argv array contains one of the recognized help options,
|
|
this function will produce help output to stdout and
|
|
call `exit (0)`.
|
|
|
|
Note that function depends on the [current locale][setlocale] for
|
|
automatic character set conversion of string and filename
|
|
arguments.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the parsing was successful,
|
|
%FALSE if an error occurred</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="argc" direction="inout" caller-allocates="0" transfer-ownership="full" optional="1">
|
|
<doc xml:space="preserve">a pointer to the number of command line arguments</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="argv" direction="inout" caller-allocates="0" transfer-ownership="full" optional="1">
|
|
<doc xml:space="preserve">a pointer to the array of command line arguments</doc>
|
|
<array length="0" zero-terminated="0" c:type="gchar***">
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="parse_strv" c:identifier="g_option_context_parse_strv" version="2.40" throws="1">
|
|
<doc xml:space="preserve">Parses the command line arguments.
|
|
|
|
This function is similar to g_option_context_parse() except that it
|
|
respects the normal memory rules when dealing with a strv instead of
|
|
assuming that the passed-in array is the argv of the main function.
|
|
|
|
In particular, strings that are removed from the arguments list will
|
|
be freed using g_free().
|
|
|
|
On Windows, the strings are expected to be in UTF-8. This is in
|
|
contrast to g_option_context_parse() which expects them to be in the
|
|
system codepage, which is how they are passed as @argv to main().
|
|
See g_win32_get_command_line() for a solution.
|
|
|
|
This function is useful if you are trying to use #GOptionContext with
|
|
#GApplication.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the parsing was successful,
|
|
%FALSE if an error occurred</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="arguments" direction="inout" caller-allocates="0" transfer-ownership="full" optional="1">
|
|
<doc xml:space="preserve">a pointer
|
|
to the command line arguments (which must be in UTF-8 on Windows).
|
|
Starting with GLib 2.62, @arguments can be %NULL, which matches
|
|
g_option_context_parse().</doc>
|
|
<array zero-terminated="0" c:type="gchar***">
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_description" c:identifier="g_option_context_set_description" version="2.12">
|
|
<doc xml:space="preserve">Adds a string to be displayed in `--help` output after the list
|
|
of options. This text often includes a bug reporting address.
|
|
|
|
Note that the summary is translated (see
|
|
g_option_context_set_translate_func()).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="description" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string to be shown in `--help` output
|
|
after the list of options, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_help_enabled" c:identifier="g_option_context_set_help_enabled" version="2.6">
|
|
<doc xml:space="preserve">Enables or disables automatic generation of `--help` output.
|
|
By default, g_option_context_parse() recognizes `--help`, `-h`,
|
|
`-?`, `--help-all` and `--help-groupname` and creates suitable
|
|
output to stdout.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="help_enabled" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE to enable `--help`, %FALSE to disable it</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_ignore_unknown_options" c:identifier="g_option_context_set_ignore_unknown_options" version="2.6">
|
|
<doc xml:space="preserve">Sets whether to ignore unknown options or not. If an argument is
|
|
ignored, it is left in the @argv array after parsing. By default,
|
|
g_option_context_parse() treats unknown options as error.
|
|
|
|
This setting does not affect non-option arguments (i.e. arguments
|
|
which don't start with a dash). But note that GOption cannot reliably
|
|
determine whether a non-option belongs to a preceding unknown option.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="ignore_unknown" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE to ignore unknown options, %FALSE to produce
|
|
an error when unknown options are met</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_main_group" c:identifier="g_option_context_set_main_group" version="2.6">
|
|
<doc xml:space="preserve">Sets a #GOptionGroup as main group of the @context.
|
|
This has the same effect as calling g_option_context_add_group(),
|
|
the only difference is that the options in the main group are
|
|
treated differently when generating `--help` output.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="group" transfer-ownership="full">
|
|
<doc xml:space="preserve">the group to set as main group</doc>
|
|
<type name="OptionGroup" c:type="GOptionGroup*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_strict_posix" c:identifier="g_option_context_set_strict_posix" version="2.44">
|
|
<doc xml:space="preserve">Sets strict POSIX mode.
|
|
|
|
By default, this mode is disabled.
|
|
|
|
In strict POSIX mode, the first non-argument parameter encountered
|
|
(eg: filename) terminates argument processing. Remaining arguments
|
|
are treated as non-options and are not attempted to be parsed.
|
|
|
|
If strict POSIX mode is disabled then parsing is done in the GNU way
|
|
where option arguments can be freely mixed with non-options.
|
|
|
|
As an example, consider "ls foo -l". With GNU style parsing, this
|
|
will list "foo" in long mode. In strict POSIX style, this will list
|
|
the files named "foo" and "-l".
|
|
|
|
It may be useful to force strict POSIX mode when creating "verb
|
|
style" command line tools. For example, the "gsettings" command line
|
|
tool supports the global option "--schemadir" as well as many
|
|
subcommands ("get", "set", etc.) which each have their own set of
|
|
arguments. Using strict POSIX mode will allow parsing the global
|
|
options up to the verb name while leaving the remaining options to be
|
|
parsed by the relevant subcommand (which can be determined by
|
|
examining the verb name, which should be present in argv[1] after
|
|
parsing).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="strict_posix" transfer-ownership="none">
|
|
<doc xml:space="preserve">the new value</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_summary" c:identifier="g_option_context_set_summary" version="2.12">
|
|
<doc xml:space="preserve">Adds a string to be displayed in `--help` output before the list
|
|
of options. This is typically a summary of the program functionality.
|
|
|
|
Note that the summary is translated (see
|
|
g_option_context_set_translate_func() and
|
|
g_option_context_set_translation_domain()).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="summary" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string to be shown in `--help` output
|
|
before the list of options, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_translate_func" c:identifier="g_option_context_set_translate_func" version="2.12">
|
|
<doc xml:space="preserve">Sets the function which is used to translate the contexts
|
|
user-visible strings, for `--help` output. If @func is %NULL,
|
|
strings are not translated.
|
|
|
|
Note that option groups have their own translation functions,
|
|
this function only affects the @parameter_string (see g_option_context_new()),
|
|
the summary (see g_option_context_set_summary()) and the description
|
|
(see g_option_context_set_description()).
|
|
|
|
If you are using gettext(), you only need to set the translation
|
|
domain, see g_option_context_set_translation_domain().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="func" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="1" destroy="2">
|
|
<doc xml:space="preserve">the #GTranslateFunc, or %NULL</doc>
|
|
<type name="TranslateFunc" c:type="GTranslateFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to @func, or %NULL</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="destroy_notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">a function which gets called to free @data, or %NULL</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_translation_domain" c:identifier="g_option_context_set_translation_domain" version="2.12">
|
|
<doc xml:space="preserve">A convenience function to use gettext() for translating
|
|
user-visible strings.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</instance-parameter>
|
|
<parameter name="domain" transfer-ownership="none">
|
|
<doc xml:space="preserve">the domain to use</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="new" c:identifier="g_option_context_new" version="2.6" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new option context.
|
|
|
|
The @parameter_string can serve multiple purposes. It can be used
|
|
to add descriptions for "rest" arguments, which are not parsed by
|
|
the #GOptionContext, typically something like "FILES" or
|
|
"FILE1 FILE2...". If you are using #G_OPTION_REMAINING for
|
|
collecting "rest" arguments, GLib handles this automatically by
|
|
using the @arg_description of the corresponding #GOptionEntry in
|
|
the usage summary.
|
|
|
|
Another usage is to give a short summary of the program
|
|
functionality, like " - frob the strings", which will be displayed
|
|
in the same line as the usage. For a longer description of the
|
|
program functionality that should be displayed as a paragraph
|
|
below the usage line, use g_option_context_set_summary().
|
|
|
|
Note that the @parameter_string is translated using the
|
|
function set with g_option_context_set_translate_func(), so
|
|
it should normally be passed untranslated.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a newly created #GOptionContext, which must be
|
|
freed with g_option_context_free() after use.</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="parameter_string" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string which is displayed in
|
|
the first line of `--help` output, after the usage summary
|
|
`programname [OPTION...]`</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<record name="OptionEntry" c:type="GOptionEntry">
|
|
<doc xml:space="preserve">A GOptionEntry struct defines a single option. To have an effect, they
|
|
must be added to a #GOptionGroup with g_option_context_add_main_entries()
|
|
or g_option_group_add_entries().</doc>
|
|
<field name="long_name" writable="1">
|
|
<doc xml:space="preserve">The long name of an option can be used to specify it
|
|
in a commandline as `--long_name`. Every option must have a
|
|
long name. To resolve conflicts if multiple option groups contain
|
|
the same long name, it is also possible to specify the option as
|
|
`--groupname-long_name`.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</field>
|
|
<field name="short_name" writable="1">
|
|
<doc xml:space="preserve">If an option has a short name, it can be specified
|
|
`-short_name` in a commandline. @short_name must be a printable
|
|
ASCII character different from '-', or zero if the option has no
|
|
short name.</doc>
|
|
<type name="gchar" c:type="gchar"/>
|
|
</field>
|
|
<field name="flags" writable="1">
|
|
<doc xml:space="preserve">Flags from #GOptionFlags</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</field>
|
|
<field name="arg" writable="1">
|
|
<doc xml:space="preserve">The type of the option, as a #GOptionArg</doc>
|
|
<type name="OptionArg" c:type="GOptionArg"/>
|
|
</field>
|
|
<field name="arg_data" writable="1">
|
|
<doc xml:space="preserve">If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data
|
|
must point to a #GOptionArgFunc callback function, which will be
|
|
called to handle the extra argument. Otherwise, @arg_data is a
|
|
pointer to a location to store the value, the required type of
|
|
the location depends on the @arg type:
|
|
- %G_OPTION_ARG_NONE: %gboolean
|
|
- %G_OPTION_ARG_STRING: %gchar*
|
|
- %G_OPTION_ARG_INT: %gint
|
|
- %G_OPTION_ARG_FILENAME: %gchar*
|
|
- %G_OPTION_ARG_STRING_ARRAY: %gchar**
|
|
- %G_OPTION_ARG_FILENAME_ARRAY: %gchar**
|
|
- %G_OPTION_ARG_DOUBLE: %gdouble
|
|
If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME,
|
|
the location will contain a newly allocated string if the option
|
|
was given. That string needs to be freed by the callee using g_free().
|
|
Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or
|
|
%G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev().</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="description" writable="1">
|
|
<doc xml:space="preserve">the description for the option in `--help`
|
|
output. The @description is translated using the @translate_func
|
|
of the group, see g_option_group_set_translation_domain().</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</field>
|
|
<field name="arg_description" writable="1">
|
|
<doc xml:space="preserve">The placeholder to use for the extra argument parsed
|
|
by the option in `--help` output. The @arg_description is translated
|
|
using the @translate_func of the group, see
|
|
g_option_group_set_translation_domain().</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</field>
|
|
</record>
|
|
<enumeration name="OptionError" c:type="GOptionError" glib:error-domain="g-option-error-quark">
|
|
<doc xml:space="preserve">Error codes returned by option parsing.</doc>
|
|
<member name="unknown_option" value="0" c:identifier="G_OPTION_ERROR_UNKNOWN_OPTION">
|
|
<doc xml:space="preserve">An option was not known to the parser.
|
|
This error will only be reported, if the parser hasn't been instructed
|
|
to ignore unknown options, see g_option_context_set_ignore_unknown_options().</doc>
|
|
</member>
|
|
<member name="bad_value" value="1" c:identifier="G_OPTION_ERROR_BAD_VALUE">
|
|
<doc xml:space="preserve">A value couldn't be parsed.</doc>
|
|
</member>
|
|
<member name="failed" value="2" c:identifier="G_OPTION_ERROR_FAILED">
|
|
<doc xml:space="preserve">A #GOptionArgFunc callback failed.</doc>
|
|
</member>
|
|
</enumeration>
|
|
<callback name="OptionErrorFunc" c:type="GOptionErrorFunc" throws="1">
|
|
<doc xml:space="preserve">The type of function to be used as callback when a parse error occurs.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">The active #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</parameter>
|
|
<parameter name="group" transfer-ownership="none">
|
|
<doc xml:space="preserve">The group to which the function belongs</doc>
|
|
<type name="OptionGroup" c:type="GOptionGroup*"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">User data added to the #GOptionGroup containing the option when it
|
|
was created with g_option_group_new()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<bitfield name="OptionFlags" c:type="GOptionFlags">
|
|
<doc xml:space="preserve">Flags which modify individual options.</doc>
|
|
<member name="none" value="0" c:identifier="G_OPTION_FLAG_NONE">
|
|
<doc xml:space="preserve">No flags. Since: 2.42.</doc>
|
|
</member>
|
|
<member name="hidden" value="1" c:identifier="G_OPTION_FLAG_HIDDEN">
|
|
<doc xml:space="preserve">The option doesn't appear in `--help` output.</doc>
|
|
</member>
|
|
<member name="in_main" value="2" c:identifier="G_OPTION_FLAG_IN_MAIN">
|
|
<doc xml:space="preserve">The option appears in the main section of the
|
|
`--help` output, even if it is defined in a group.</doc>
|
|
</member>
|
|
<member name="reverse" value="4" c:identifier="G_OPTION_FLAG_REVERSE">
|
|
<doc xml:space="preserve">For options of the %G_OPTION_ARG_NONE kind, this
|
|
flag indicates that the sense of the option is reversed.</doc>
|
|
</member>
|
|
<member name="no_arg" value="8" c:identifier="G_OPTION_FLAG_NO_ARG">
|
|
<doc xml:space="preserve">For options of the %G_OPTION_ARG_CALLBACK kind,
|
|
this flag indicates that the callback does not take any argument
|
|
(like a %G_OPTION_ARG_NONE option). Since 2.8</doc>
|
|
</member>
|
|
<member name="filename" value="16" c:identifier="G_OPTION_FLAG_FILENAME">
|
|
<doc xml:space="preserve">For options of the %G_OPTION_ARG_CALLBACK
|
|
kind, this flag indicates that the argument should be passed to the
|
|
callback in the GLib filename encoding rather than UTF-8. Since 2.8</doc>
|
|
</member>
|
|
<member name="optional_arg" value="32" c:identifier="G_OPTION_FLAG_OPTIONAL_ARG">
|
|
<doc xml:space="preserve">For options of the %G_OPTION_ARG_CALLBACK
|
|
kind, this flag indicates that the argument supply is optional.
|
|
If no argument is given then data of %GOptionParseFunc will be
|
|
set to NULL. Since 2.8</doc>
|
|
</member>
|
|
<member name="noalias" value="64" c:identifier="G_OPTION_FLAG_NOALIAS">
|
|
<doc xml:space="preserve">This flag turns off the automatic conflict
|
|
resolution which prefixes long option names with `groupname-` if
|
|
there is a conflict. This option should only be used in situations
|
|
where aliasing is necessary to model some legacy commandline interface.
|
|
It is not safe to use this option, unless all option groups are under
|
|
your direct control. Since 2.8.</doc>
|
|
</member>
|
|
</bitfield>
|
|
<record name="OptionGroup" c:type="GOptionGroup" glib:type-name="GOptionGroup" glib:get-type="g_option_group_get_type" c:symbol-prefix="option_group">
|
|
<doc xml:space="preserve">A `GOptionGroup` struct defines the options in a single
|
|
group. The struct has only private fields and should not be directly accessed.
|
|
|
|
All options in a group share the same translation function. Libraries which
|
|
need to parse commandline options are expected to provide a function for
|
|
getting a `GOptionGroup` holding their options, which
|
|
the application can then add to its #GOptionContext.</doc>
|
|
<constructor name="new" c:identifier="g_option_group_new" version="2.6">
|
|
<doc xml:space="preserve">Creates a new #GOptionGroup.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly created option group. It should be added
|
|
to a #GOptionContext or freed with g_option_group_unref().</doc>
|
|
<type name="OptionGroup" c:type="GOptionGroup*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="name" transfer-ownership="none">
|
|
<doc xml:space="preserve">the name for the option group, this is used to provide
|
|
help for the options in this group with `--help-`@name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="description" transfer-ownership="none">
|
|
<doc xml:space="preserve">a description for this group to be shown in
|
|
`--help`. This string is translated using the translation
|
|
domain or translation function of the group</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="help_description" transfer-ownership="none">
|
|
<doc xml:space="preserve">a description for the `--help-`@name option.
|
|
This string is translated using the translation domain or translation function
|
|
of the group</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data that will be passed to the pre- and post-parse hooks,
|
|
the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">a function that will be called to free @user_data, or %NULL</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<method name="add_entries" c:identifier="g_option_group_add_entries" version="2.6">
|
|
<doc xml:space="preserve">Adds the options specified in @entries to @group.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="group" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionGroup</doc>
|
|
<type name="OptionGroup" c:type="GOptionGroup*"/>
|
|
</instance-parameter>
|
|
<parameter name="entries" transfer-ownership="none">
|
|
<doc xml:space="preserve">a %NULL-terminated array of #GOptionEntrys</doc>
|
|
<array c:type="const GOptionEntry*">
|
|
<type name="OptionEntry" c:type="GOptionEntry"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free" c:identifier="g_option_group_free" version="2.6" deprecated="1" deprecated-version="2.44">
|
|
<doc xml:space="preserve">Frees a #GOptionGroup. Note that you must not free groups
|
|
which have been added to a #GOptionContext.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_option_group_unref() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="group" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionGroup</doc>
|
|
<type name="OptionGroup" c:type="GOptionGroup*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_option_group_ref" version="2.44">
|
|
<doc xml:space="preserve">Increments the reference count of @group by one.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a #GOptionGroup</doc>
|
|
<type name="OptionGroup" c:type="GOptionGroup*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="group" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionGroup</doc>
|
|
<type name="OptionGroup" c:type="GOptionGroup*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_error_hook" c:identifier="g_option_group_set_error_hook" version="2.6" introspectable="0">
|
|
<doc xml:space="preserve">Associates a function with @group which will be called
|
|
from g_option_context_parse() when an error occurs.
|
|
|
|
Note that the user data to be passed to @error_func can be
|
|
specified when constructing the group with g_option_group_new().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="group" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionGroup</doc>
|
|
<type name="OptionGroup" c:type="GOptionGroup*"/>
|
|
</instance-parameter>
|
|
<parameter name="error_func" transfer-ownership="none">
|
|
<doc xml:space="preserve">a function to call when an error occurs</doc>
|
|
<type name="OptionErrorFunc" c:type="GOptionErrorFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_parse_hooks" c:identifier="g_option_group_set_parse_hooks" version="2.6" introspectable="0">
|
|
<doc xml:space="preserve">Associates two functions with @group which will be called
|
|
from g_option_context_parse() before the first option is parsed
|
|
and after the last option has been parsed, respectively.
|
|
|
|
Note that the user data to be passed to @pre_parse_func and
|
|
@post_parse_func can be specified when constructing the group
|
|
with g_option_group_new().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="group" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionGroup</doc>
|
|
<type name="OptionGroup" c:type="GOptionGroup*"/>
|
|
</instance-parameter>
|
|
<parameter name="pre_parse_func" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a function to call before parsing, or %NULL</doc>
|
|
<type name="OptionParseFunc" c:type="GOptionParseFunc"/>
|
|
</parameter>
|
|
<parameter name="post_parse_func" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a function to call after parsing, or %NULL</doc>
|
|
<type name="OptionParseFunc" c:type="GOptionParseFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_translate_func" c:identifier="g_option_group_set_translate_func" version="2.6">
|
|
<doc xml:space="preserve">Sets the function which is used to translate user-visible strings,
|
|
for `--help` output. Different groups can use different
|
|
#GTranslateFuncs. If @func is %NULL, strings are not translated.
|
|
|
|
If you are using gettext(), you only need to set the translation
|
|
domain, see g_option_group_set_translation_domain().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="group" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionGroup</doc>
|
|
<type name="OptionGroup" c:type="GOptionGroup*"/>
|
|
</instance-parameter>
|
|
<parameter name="func" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="1" destroy="2">
|
|
<doc xml:space="preserve">the #GTranslateFunc, or %NULL</doc>
|
|
<type name="TranslateFunc" c:type="GTranslateFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to @func, or %NULL</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="destroy_notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">a function which gets called to free @data, or %NULL</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_translation_domain" c:identifier="g_option_group_set_translation_domain" version="2.6">
|
|
<doc xml:space="preserve">A convenience function to use gettext() for translating
|
|
user-visible strings.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="group" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionGroup</doc>
|
|
<type name="OptionGroup" c:type="GOptionGroup*"/>
|
|
</instance-parameter>
|
|
<parameter name="domain" transfer-ownership="none">
|
|
<doc xml:space="preserve">the domain to use</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_option_group_unref" version="2.44">
|
|
<doc xml:space="preserve">Decrements the reference count of @group by one.
|
|
If the reference count drops to 0, the @group will be freed.
|
|
and all memory allocated by the @group is released.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="group" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GOptionGroup</doc>
|
|
<type name="OptionGroup" c:type="GOptionGroup*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<callback name="OptionParseFunc" c:type="GOptionParseFunc" throws="1">
|
|
<doc xml:space="preserve">The type of function that can be called before and after parsing.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the function completed successfully, %FALSE if an error
|
|
occurred, in which case @error should be set with g_set_error()</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">The active #GOptionContext</doc>
|
|
<type name="OptionContext" c:type="GOptionContext*"/>
|
|
</parameter>
|
|
<parameter name="group" transfer-ownership="none">
|
|
<doc xml:space="preserve">The group to which the function belongs</doc>
|
|
<type name="OptionGroup" c:type="GOptionGroup*"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">User data added to the #GOptionGroup containing the option when it
|
|
was created with g_option_group_new()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<constant name="PDP_ENDIAN" value="3412" c:type="G_PDP_ENDIAN">
|
|
<doc xml:space="preserve">Specifies one of the possible types of byte order
|
|
(currently unused). See #G_BYTE_ORDER.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="PI" value="3.141593" c:type="G_PI">
|
|
<doc xml:space="preserve">The value of pi (ratio of circle's circumference to its diameter).</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</constant>
|
|
<constant name="PID_FORMAT" value="i" c:type="G_PID_FORMAT" version="2.50">
|
|
<doc xml:space="preserve">A format specifier that can be used in printf()-style format strings
|
|
when printing a #GPid.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="PI_2" value="1.570796" c:type="G_PI_2">
|
|
<doc xml:space="preserve">Pi divided by 2.</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</constant>
|
|
<constant name="PI_4" value="0.785398" c:type="G_PI_4">
|
|
<doc xml:space="preserve">Pi divided by 4.</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</constant>
|
|
<constant name="POLLFD_FORMAT" value="%d" c:type="G_POLLFD_FORMAT">
|
|
<doc xml:space="preserve">A format specifier that can be used in printf()-style format strings
|
|
when printing the @fd member of a #GPollFD.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="PRIORITY_DEFAULT" value="0" c:type="G_PRIORITY_DEFAULT">
|
|
<doc xml:space="preserve">Use this for default priority event sources.
|
|
|
|
In GLib this priority is used when adding timeout functions
|
|
with g_timeout_add(). In GDK this priority is used for events
|
|
from the X server.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="PRIORITY_DEFAULT_IDLE" value="200" c:type="G_PRIORITY_DEFAULT_IDLE">
|
|
<doc xml:space="preserve">Use this for default priority idle functions.
|
|
|
|
In GLib this priority is used when adding idle functions with
|
|
g_idle_add().</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="PRIORITY_HIGH" value="-100" c:type="G_PRIORITY_HIGH">
|
|
<doc xml:space="preserve">Use this for high priority event sources.
|
|
|
|
It is not used within GLib or GTK+.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="PRIORITY_HIGH_IDLE" value="100" c:type="G_PRIORITY_HIGH_IDLE">
|
|
<doc xml:space="preserve">Use this for high priority idle functions.
|
|
|
|
GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations,
|
|
and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is
|
|
done to ensure that any pending resizes are processed before any
|
|
pending redraws, so that widgets are not redrawn twice unnecessarily.)</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="PRIORITY_LOW" value="300" c:type="G_PRIORITY_LOW">
|
|
<doc xml:space="preserve">Use this for very low priority background tasks.
|
|
|
|
It is not used within GLib or GTK+.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<function-macro name="PRIVATE_INIT" c:identifier="G_PRIVATE_INIT" version="2.32" introspectable="0">
|
|
<doc xml:space="preserve">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 with the key. This is needed when the key will be
|
|
used to point at memory that should be deallocated when the thread
|
|
exits.
|
|
|
|
Additionally, the #GDestroyNotify will also be called on the previous
|
|
value stored in the key when g_private_replace() is used.
|
|
|
|
If no #GDestroyNotify is needed, then use of this macro is not
|
|
required -- if the #GPrivate is declared in static scope then it will
|
|
be properly initialised by default (ie: to all zeros). See the
|
|
examples below.
|
|
|
|
|[<!-- language="C" -->
|
|
static GPrivate name_key = G_PRIVATE_INIT (g_free);
|
|
|
|
// return value should not be freed
|
|
const gchar *
|
|
get_local_name (void)
|
|
{
|
|
return g_private_get (&name_key);
|
|
}
|
|
|
|
void
|
|
set_local_name (const gchar *name)
|
|
{
|
|
g_private_replace (&name_key, g_strdup (name));
|
|
}
|
|
|
|
|
|
static GPrivate count_key; // no free function
|
|
|
|
gint
|
|
get_local_count (void)
|
|
{
|
|
return GPOINTER_TO_INT (g_private_get (&count_key));
|
|
}
|
|
|
|
void
|
|
set_local_count (gint count)
|
|
{
|
|
g_private_set (&count_key, GINT_TO_POINTER (count));
|
|
}
|
|
]|</doc>
|
|
<parameters>
|
|
<parameter name="notify">
|
|
<doc xml:space="preserve">a #GDestroyNotify</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<record name="PatternSpec" c:type="GPatternSpec" disguised="1">
|
|
<doc xml:space="preserve">A GPatternSpec struct is the 'compiled' form of a pattern. This
|
|
structure is opaque and its fields cannot be accessed directly.</doc>
|
|
<method name="equal" c:identifier="g_pattern_spec_equal">
|
|
<doc xml:space="preserve">Compares two compiled pattern specs and returns whether they will
|
|
match the same set of strings.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">Whether the compiled patterns are equal</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="pspec1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPatternSpec</doc>
|
|
<type name="PatternSpec" c:type="GPatternSpec*"/>
|
|
</instance-parameter>
|
|
<parameter name="pspec2" transfer-ownership="none">
|
|
<doc xml:space="preserve">another #GPatternSpec</doc>
|
|
<type name="PatternSpec" c:type="GPatternSpec*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free" c:identifier="g_pattern_spec_free">
|
|
<doc xml:space="preserve">Frees the memory allocated for the #GPatternSpec.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="pspec" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPatternSpec</doc>
|
|
<type name="PatternSpec" c:type="GPatternSpec*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="new" c:identifier="g_pattern_spec_new" introspectable="0">
|
|
<doc xml:space="preserve">Compiles a pattern to a #GPatternSpec.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a newly-allocated #GPatternSpec</doc>
|
|
<type name="PatternSpec" c:type="GPatternSpec*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="pattern" transfer-ownership="none">
|
|
<doc xml:space="preserve">a zero-terminated UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<record name="PollFD" c:type="GPollFD" glib:type-name="GPollFD" glib:get-type="g_pollfd_get_type" c:symbol-prefix="pollfd">
|
|
<doc xml:space="preserve">Represents a file descriptor, which events to poll for, and which events
|
|
occurred.</doc>
|
|
<field name="fd" writable="1">
|
|
<doc xml:space="preserve">the file descriptor to poll (or a HANDLE on Win32)</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</field>
|
|
<field name="events" writable="1">
|
|
<doc xml:space="preserve">a bitwise combination from #GIOCondition, specifying which
|
|
events should be polled for. Typically for reading from a file
|
|
descriptor you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and
|
|
for writing you would use %G_IO_OUT | %G_IO_ERR.</doc>
|
|
<type name="gushort" c:type="gushort"/>
|
|
</field>
|
|
<field name="revents" writable="1">
|
|
<doc xml:space="preserve">a bitwise combination of flags from #GIOCondition, returned
|
|
from the poll() function to indicate which events occurred.</doc>
|
|
<type name="gushort" c:type="gushort"/>
|
|
</field>
|
|
</record>
|
|
<callback name="PollFunc" c:type="GPollFunc">
|
|
<doc xml:space="preserve">Specifies the type of function passed to g_main_context_set_poll_func().
|
|
The semantics of the function should match those of the poll() system call.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of #GPollFD elements which have events or errors
|
|
reported, or -1 if an error occurred.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="ufds" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array of #GPollFD elements</doc>
|
|
<type name="PollFD" c:type="GPollFD*"/>
|
|
</parameter>
|
|
<parameter name="nfsd" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of elements in @ufds</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="timeout_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum time to wait for an event of the file descriptors.
|
|
A negative value indicates an infinite timeout.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<callback name="PrintFunc" c:type="GPrintFunc">
|
|
<doc xml:space="preserve">Specifies the type of the print handler functions.
|
|
These are called with the complete formatted string to output.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the message to output</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<record name="Private" c:type="GPrivate">
|
|
<doc xml:space="preserve">The #GPrivate struct is an opaque data structure to represent a
|
|
thread-local data key. It is approximately equivalent to the
|
|
pthread_setspecific()/pthread_getspecific() APIs on POSIX and to
|
|
TlsSetValue()/TlsGetValue() on Windows.
|
|
|
|
If you don't already know why you might want this functionality,
|
|
then you probably don't need it.
|
|
|
|
#GPrivate is a very limited resource (as far as 128 per program,
|
|
shared between all libraries). It is also not possible to destroy a
|
|
#GPrivate after it has been used. As such, it is only ever acceptable
|
|
to use #GPrivate in static scope, and even then sparingly so.
|
|
|
|
See G_PRIVATE_INIT() for a couple of examples.
|
|
|
|
The #GPrivate structure should be considered opaque. It should only
|
|
be accessed via the g_private_ functions.</doc>
|
|
<field name="p" readable="0" private="1">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="notify" readable="0" private="1">
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</field>
|
|
<field name="future" readable="0" private="1">
|
|
<array zero-terminated="0" fixed-size="2">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</field>
|
|
<method name="get" c:identifier="g_private_get">
|
|
<doc xml:space="preserve">Returns the current value of the thread local variable @key.
|
|
|
|
If the value has not yet been set in this thread, %NULL is returned.
|
|
Values are never copied between threads (when a new thread is
|
|
created, for example).</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the thread-local value</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPrivate</doc>
|
|
<type name="Private" c:type="GPrivate*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="replace" c:identifier="g_private_replace" version="2.32">
|
|
<doc xml:space="preserve">Sets the thread local variable @key to have the value @value in the
|
|
current thread.
|
|
|
|
This function differs from g_private_set() in the following way: if
|
|
the previous value was non-%NULL then the #GDestroyNotify handler for
|
|
@key is run on it.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPrivate</doc>
|
|
<type name="Private" c:type="GPrivate*"/>
|
|
</instance-parameter>
|
|
<parameter name="value" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the new value</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set" c:identifier="g_private_set">
|
|
<doc xml:space="preserve">Sets the thread local variable @key to have the value @value in the
|
|
current thread.
|
|
|
|
This function differs from g_private_replace() in the following way:
|
|
the #GDestroyNotify for @key is not called on the old value.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPrivate</doc>
|
|
<type name="Private" c:type="GPrivate*"/>
|
|
</instance-parameter>
|
|
<parameter name="value" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the new value</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<record name="PtrArray" c:type="GPtrArray" glib:type-name="GPtrArray" glib:get-type="g_ptr_array_get_type" c:symbol-prefix="ptr_array">
|
|
<doc xml:space="preserve">Contains the public fields of a pointer array.</doc>
|
|
<field name="pdata" writable="1">
|
|
<doc xml:space="preserve">points to the array of pointers, which may be moved when the
|
|
array grows</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</field>
|
|
<field name="len" writable="1">
|
|
<doc xml:space="preserve">number of pointers in the array</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<function name="add" c:identifier="g_ptr_array_add" introspectable="0">
|
|
<doc xml:space="preserve">Adds a pointer to the end of the pointer array. The array will grow
|
|
in size automatically if necessary.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the pointer to add</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="copy" c:identifier="g_ptr_array_copy" version="2.62" introspectable="0">
|
|
<doc xml:space="preserve">Makes a full (deep) copy of a #GPtrArray.
|
|
|
|
@func, as a #GCopyFunc, takes two arguments, the data to be copied
|
|
and a @user_data pointer. On common processor architectures, it's safe to
|
|
pass %NULL as @user_data if the copy function takes only one argument. You
|
|
may get compiler warnings from this though if compiling with GCC’s
|
|
`-Wcast-function-type` warning.
|
|
|
|
If @func is %NULL, then only the pointers (and not what they are
|
|
pointing to) are copied to the new #GPtrArray.
|
|
|
|
The copy of @array will have the same #GDestroyNotify for its elements as
|
|
@array.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a deep copy of the initial #GPtrArray.</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">#GPtrArray to duplicate</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" nullable="1" allow-none="1" closure="2">
|
|
<doc xml:space="preserve">a copy function used to copy every element in the array</doc>
|
|
<type name="CopyFunc" c:type="GCopyFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to the copy function @func, or %NULL</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="extend" c:identifier="g_ptr_array_extend" version="2.62" introspectable="0">
|
|
<doc xml:space="preserve">Adds all pointers of @array to the end of the array @array_to_extend.
|
|
The array will grow in size automatically if needed. @array_to_extend is
|
|
modified in-place.
|
|
|
|
@func, as a #GCopyFunc, takes two arguments, the data to be copied
|
|
and a @user_data pointer. On common processor architectures, it's safe to
|
|
pass %NULL as @user_data if the copy function takes only one argument. You
|
|
may get compiler warnings from this though if compiling with GCC’s
|
|
`-Wcast-function-type` warning.
|
|
|
|
If @func is %NULL, then only the pointers (and not what they are
|
|
pointing to) are copied to the new #GPtrArray.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array_to_extend" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray.</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray to add to the end of @array_to_extend.</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" nullable="1" allow-none="1" closure="3">
|
|
<doc xml:space="preserve">a copy function used to copy every element in the array</doc>
|
|
<type name="CopyFunc" c:type="GCopyFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to the copy function @func, or %NULL</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="extend_and_steal" c:identifier="g_ptr_array_extend_and_steal" version="2.62" introspectable="0">
|
|
<doc xml:space="preserve">Adds all the pointers in @array to the end of @array_to_extend, transferring
|
|
ownership of each element from @array to @array_to_extend and modifying
|
|
@array_to_extend in-place. @array is then freed.
|
|
|
|
As with g_ptr_array_free(), @array will be destroyed if its reference count
|
|
is 1. If its reference count is higher, it will be decremented and the
|
|
length of @array set to zero.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array_to_extend" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray.</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="array" transfer-ownership="container">
|
|
<doc xml:space="preserve">a #GPtrArray to add to the end of
|
|
@array_to_extend.</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="find" c:identifier="g_ptr_array_find" version="2.54" introspectable="0">
|
|
<doc xml:space="preserve">Checks whether @needle exists in @haystack. If the element is found, %TRUE is
|
|
returned and the element’s index is returned in @index_ (if non-%NULL).
|
|
Otherwise, %FALSE is returned and @index_ is undefined. If @needle exists
|
|
multiple times in @haystack, the index of the first instance is returned.
|
|
|
|
This does pointer comparisons only. If you want to use more complex equality
|
|
checks, such as string comparisons, use g_ptr_array_find_with_equal_func().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @needle is one of the elements of @haystack</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="haystack" transfer-ownership="none">
|
|
<doc xml:space="preserve">pointer array to be searched</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="needle" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">pointer to look for</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="index_" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the index of
|
|
the element, if found</doc>
|
|
<type name="guint" c:type="guint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="find_with_equal_func" c:identifier="g_ptr_array_find_with_equal_func" version="2.54" introspectable="0">
|
|
<doc xml:space="preserve">Checks whether @needle exists in @haystack, using the given @equal_func.
|
|
If the element is found, %TRUE is returned and the element’s index is
|
|
returned in @index_ (if non-%NULL). Otherwise, %FALSE is returned and @index_
|
|
is undefined. If @needle exists multiple times in @haystack, the index of
|
|
the first instance is returned.
|
|
|
|
@equal_func is called with the element from the array as its first parameter,
|
|
and @needle as its second parameter. If @equal_func is %NULL, pointer
|
|
equality is used.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @needle is one of the elements of @haystack</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="haystack" transfer-ownership="none">
|
|
<doc xml:space="preserve">pointer array to be searched</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="needle" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">pointer to look for</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="equal_func" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the function to call for each element, which should
|
|
return %TRUE when the desired element is found; or %NULL to use pointer
|
|
equality</doc>
|
|
<type name="EqualFunc" c:type="GEqualFunc"/>
|
|
</parameter>
|
|
<parameter name="index_" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the index of
|
|
the element, if found</doc>
|
|
<type name="guint" c:type="guint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="foreach" c:identifier="g_ptr_array_foreach" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Calls a function for each element of a #GPtrArray. @func must not
|
|
add elements to or remove elements from the array.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function to call for each array element</doc>
|
|
<type name="Func" c:type="GFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to the function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="free" c:identifier="g_ptr_array_free" introspectable="0">
|
|
<doc xml:space="preserve">Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE
|
|
it frees the memory block holding the elements as well. Pass %FALSE
|
|
if you want to free the #GPtrArray wrapper but preserve the
|
|
underlying array for use elsewhere. If the reference count of @array
|
|
is greater than one, the #GPtrArray wrapper is preserved but the
|
|
size of @array will be set to zero.
|
|
|
|
If array contents point to dynamically-allocated memory, they should
|
|
be freed separately if @free_seg is %TRUE and no #GDestroyNotify
|
|
function has been set for @array.
|
|
|
|
This function is not thread-safe. If using a #GPtrArray from multiple
|
|
threads, use only the atomic g_ptr_array_ref() and g_ptr_array_unref()
|
|
functions.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the pointer array if @free_seg is %FALSE, otherwise %NULL.
|
|
The pointer array should be freed using g_free().</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="free_seg" transfer-ownership="none">
|
|
<doc xml:space="preserve">if %TRUE the actual pointer array is freed as well</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="insert" c:identifier="g_ptr_array_insert" version="2.40" introspectable="0">
|
|
<doc xml:space="preserve">Inserts an element into the pointer array at the given index. The
|
|
array will grow in size automatically if necessary.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="index_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index to place the new element at, or -1 to append</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the pointer to add.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="new" c:identifier="g_ptr_array_new" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GPtrArray with a reference count of 1.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
</function>
|
|
<function name="new_full" c:identifier="g_ptr_array_new_full" version="2.30" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GPtrArray with @reserved_size pointers preallocated
|
|
and a reference count of 1. This avoids frequent reallocation, if
|
|
you are going to add many pointers to the array. Note however that
|
|
the size of the array is still 0. It also set @element_free_func
|
|
for freeing each element when the array is destroyed either via
|
|
g_ptr_array_unref(), when g_ptr_array_free() is called with
|
|
@free_segment set to %TRUE or when removing elements.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">A new #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="reserved_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of pointers preallocated</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="element_free_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">A function to free elements with
|
|
destroy @array or %NULL</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="new_with_free_func" c:identifier="g_ptr_array_new_with_free_func" version="2.22" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GPtrArray with a reference count of 1 and use
|
|
@element_free_func for freeing each element when the array is destroyed
|
|
either via g_ptr_array_unref(), when g_ptr_array_free() is called with
|
|
@free_segment set to %TRUE or when removing elements.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">A new #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="element_free_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">A function to free elements with
|
|
destroy @array or %NULL</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ref" c:identifier="g_ptr_array_ref" version="2.22" introspectable="0">
|
|
<doc xml:space="preserve">Atomically increments the reference count of @array by one.
|
|
This function is thread-safe and may be called from any thread.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">The passed in #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove" c:identifier="g_ptr_array_remove" introspectable="0">
|
|
<doc xml:space="preserve">Removes the first occurrence of the given pointer from the pointer
|
|
array. The following elements are moved down one place. If @array
|
|
has a non-%NULL #GDestroyNotify function it is called for the
|
|
removed element.
|
|
|
|
It returns %TRUE if the pointer was removed, or %FALSE if the
|
|
pointer was not found.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the pointer is removed, %FALSE if the pointer
|
|
is not found in the array</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the pointer to remove</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_fast" c:identifier="g_ptr_array_remove_fast" introspectable="0">
|
|
<doc xml:space="preserve">Removes the first occurrence of the given pointer from the pointer
|
|
array. The last element in the array is used to fill in the space,
|
|
so this function does not preserve the order of the array. But it
|
|
is faster than g_ptr_array_remove(). If @array has a non-%NULL
|
|
#GDestroyNotify function it is called for the removed element.
|
|
|
|
It returns %TRUE if the pointer was removed, or %FALSE if the
|
|
pointer was not found.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the pointer was found in the array</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the pointer to remove</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_index" c:identifier="g_ptr_array_remove_index" introspectable="0">
|
|
<doc xml:space="preserve">Removes the pointer at the given index from the pointer array.
|
|
The following elements are moved down one place. If @array has
|
|
a non-%NULL #GDestroyNotify function it is called for the removed
|
|
element. If so, the return value from this function will potentially point
|
|
to freed memory (depending on the #GDestroyNotify implementation).</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the pointer which was removed</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="index_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the pointer to remove</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_index_fast" c:identifier="g_ptr_array_remove_index_fast" introspectable="0">
|
|
<doc xml:space="preserve">Removes the pointer at the given index from the pointer array.
|
|
The last element in the array is used to fill in the space, so
|
|
this function does not preserve the order of the array. But it
|
|
is faster than g_ptr_array_remove_index(). If @array has a non-%NULL
|
|
#GDestroyNotify function it is called for the removed element. If so, the
|
|
return value from this function will potentially point to freed memory
|
|
(depending on the #GDestroyNotify implementation).</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the pointer which was removed</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="index_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the pointer to remove</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_range" c:identifier="g_ptr_array_remove_range" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Removes the given number of pointers starting at the given index
|
|
from a #GPtrArray. The following elements are moved to close the
|
|
gap. If @array has a non-%NULL #GDestroyNotify function it is
|
|
called for the removed elements.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the @array</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a @GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="index_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the first pointer to remove</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of pointers to remove</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="set_free_func" c:identifier="g_ptr_array_set_free_func" version="2.22" introspectable="0">
|
|
<doc xml:space="preserve">Sets a function for freeing each element when @array is destroyed
|
|
either via g_ptr_array_unref(), when g_ptr_array_free() is called
|
|
with @free_segment set to %TRUE or when removing elements.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="element_free_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">A function to free elements with
|
|
destroy @array or %NULL</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="set_size" c:identifier="g_ptr_array_set_size" introspectable="0">
|
|
<doc xml:space="preserve">Sets the size of the array. When making the array larger,
|
|
newly-added elements will be set to %NULL. When making it smaller,
|
|
if @array has a non-%NULL #GDestroyNotify function then it will be
|
|
called for the removed elements.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the new length of the pointer array</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sized_new" c:identifier="g_ptr_array_sized_new" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GPtrArray with @reserved_size pointers preallocated
|
|
and a reference count of 1. This avoids frequent reallocation, if
|
|
you are going to add many pointers to the array. Note however that
|
|
the size of the array is still 0.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="reserved_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of pointers preallocated</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sort" c:identifier="g_ptr_array_sort" introspectable="0">
|
|
<doc xml:space="preserve">Sorts the array, using @compare_func which should be a qsort()-style
|
|
comparison function (returns less than zero for first arg is less
|
|
than second arg, zero for equal, greater than zero if irst arg is
|
|
greater than second arg).
|
|
|
|
Note that the comparison function for g_ptr_array_sort() doesn't
|
|
take the pointers from the array as arguments, it takes pointers to
|
|
the pointers in the array. Here is a full example of usage:
|
|
|
|
|[<!-- language="C" -->
|
|
typedef struct
|
|
{
|
|
gchar *name;
|
|
gint size;
|
|
} FileListEntry;
|
|
|
|
static gint
|
|
sort_filelist (gconstpointer a, gconstpointer b)
|
|
{
|
|
const FileListEntry *entry1 = *((FileListEntry **) a);
|
|
const FileListEntry *entry2 = *((FileListEntry **) b);
|
|
|
|
return g_ascii_strcasecmp (entry1->name, entry2->name);
|
|
}
|
|
|
|
…
|
|
g_autoptr (GPtrArray) file_list = NULL;
|
|
|
|
// initialize file_list array and load with many FileListEntry entries
|
|
...
|
|
// now sort it with
|
|
g_ptr_array_sort (file_list, sort_filelist);
|
|
]|
|
|
|
|
This is guaranteed to be a stable sort since version 2.32.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="compare_func" transfer-ownership="none">
|
|
<doc xml:space="preserve">comparison function</doc>
|
|
<type name="CompareFunc" c:type="GCompareFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sort_with_data" c:identifier="g_ptr_array_sort_with_data" introspectable="0">
|
|
<doc xml:space="preserve">Like g_ptr_array_sort(), but the comparison function has an extra
|
|
user data argument.
|
|
|
|
Note that the comparison function for g_ptr_array_sort_with_data()
|
|
doesn't take the pointers from the array as arguments, it takes
|
|
pointers to the pointers in the array. Here is a full example of use:
|
|
|
|
|[<!-- language="C" -->
|
|
typedef enum { SORT_NAME, SORT_SIZE } SortMode;
|
|
|
|
typedef struct
|
|
{
|
|
gchar *name;
|
|
gint size;
|
|
} FileListEntry;
|
|
|
|
static gint
|
|
sort_filelist (gconstpointer a, gconstpointer b, gpointer user_data)
|
|
{
|
|
gint order;
|
|
const SortMode sort_mode = GPOINTER_TO_INT (user_data);
|
|
const FileListEntry *entry1 = *((FileListEntry **) a);
|
|
const FileListEntry *entry2 = *((FileListEntry **) b);
|
|
|
|
switch (sort_mode)
|
|
{
|
|
case SORT_NAME:
|
|
order = g_ascii_strcasecmp (entry1->name, entry2->name);
|
|
break;
|
|
case SORT_SIZE:
|
|
order = entry1->size - entry2->size;
|
|
break;
|
|
default:
|
|
order = 0;
|
|
break;
|
|
}
|
|
return order;
|
|
}
|
|
|
|
...
|
|
g_autoptr (GPtrArray) file_list = NULL;
|
|
SortMode sort_mode;
|
|
|
|
// initialize file_list array and load with many FileListEntry entries
|
|
...
|
|
// now sort it with
|
|
sort_mode = SORT_NAME;
|
|
g_ptr_array_sort_with_data (file_list,
|
|
sort_filelist,
|
|
GINT_TO_POINTER (sort_mode));
|
|
]|
|
|
|
|
This is guaranteed to be a stable sort since version 2.32.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="compare_func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">comparison function</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @compare_func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="steal" c:identifier="g_ptr_array_steal" version="2.64" introspectable="0">
|
|
<doc xml:space="preserve">Frees the data in the array and resets the size to zero, while
|
|
the underlying array is preserved for use elsewhere and returned
|
|
to the caller.
|
|
|
|
Even if set, the #GDestroyNotify function will never be called
|
|
on the current contents of the array and the caller is
|
|
responsible for freeing the array elements.
|
|
|
|
An example of use:
|
|
|[<!-- language="C" -->
|
|
g_autoptr(GPtrArray) chunk_buffer = g_ptr_array_new_with_free_func (g_bytes_unref);
|
|
|
|
// Some part of your application appends a number of chunks to the pointer array.
|
|
g_ptr_array_add (chunk_buffer, g_bytes_new_static ("hello", 5));
|
|
g_ptr_array_add (chunk_buffer, g_bytes_new_static ("world", 5));
|
|
|
|
…
|
|
|
|
// Periodically, the chunks need to be sent as an array-and-length to some
|
|
// other part of the program.
|
|
GBytes **chunks;
|
|
gsize n_chunks;
|
|
|
|
chunks = g_ptr_array_steal (chunk_buffer, &n_chunks);
|
|
for (gsize i = 0; i < n_chunks; i++)
|
|
{
|
|
// Do something with each chunk here, and then free them, since
|
|
// g_ptr_array_steal() transfers ownership of all the elements and the
|
|
// array to the caller.
|
|
…
|
|
|
|
g_bytes_unref (chunks[i]);
|
|
}
|
|
|
|
g_free (chunks);
|
|
|
|
// After calling g_ptr_array_steal(), the pointer array can be reused for the
|
|
// next set of chunks.
|
|
g_assert (chunk_buffer->len == 0);
|
|
]|</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the element data, which should be
|
|
freed using g_free().</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray.</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="len" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">pointer to retrieve the number of
|
|
elements of the original array</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="steal_index" c:identifier="g_ptr_array_steal_index" version="2.58" introspectable="0">
|
|
<doc xml:space="preserve">Removes the pointer at the given index from the pointer array.
|
|
The following elements are moved down one place. The #GDestroyNotify for
|
|
@array is *not* called on the removed element; ownership is transferred to
|
|
the caller of this function.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the pointer which was removed</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="index_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the pointer to steal</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="steal_index_fast" c:identifier="g_ptr_array_steal_index_fast" version="2.58" introspectable="0">
|
|
<doc xml:space="preserve">Removes the pointer at the given index from the pointer array.
|
|
The last element in the array is used to fill in the space, so
|
|
this function does not preserve the order of the array. But it
|
|
is faster than g_ptr_array_steal_index(). The #GDestroyNotify for @array is
|
|
*not* called on the removed element; ownership is transferred to the caller
|
|
of this function.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the pointer which was removed</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="index_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the pointer to steal</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unref" c:identifier="g_ptr_array_unref" version="2.22" introspectable="0">
|
|
<doc xml:space="preserve">Atomically decrements the reference count of @array by one. If the
|
|
reference count drops to 0, the effect is the same as calling
|
|
g_ptr_array_free() with @free_segment set to %TRUE. This function
|
|
is thread-safe and may be called from any thread.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GPtrArray</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<record name="Queue" c:type="GQueue">
|
|
<doc xml:space="preserve">Contains the public fields of a
|
|
[Queue][glib-Double-ended-Queues].</doc>
|
|
<field name="head" writable="1">
|
|
<doc xml:space="preserve">a pointer to the first element of the queue</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</field>
|
|
<field name="tail" writable="1">
|
|
<doc xml:space="preserve">a pointer to the last element of the queue</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</field>
|
|
<field name="length" writable="1">
|
|
<doc xml:space="preserve">the number of elements in the queue</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<method name="clear" c:identifier="g_queue_clear" version="2.14">
|
|
<doc xml:space="preserve">Removes all the elements in @queue. If queue elements contain
|
|
dynamically-allocated memory, they should be freed first.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="clear_full" c:identifier="g_queue_clear_full" version="2.60">
|
|
<doc xml:space="preserve">Convenience method, which frees all the memory used by a #GQueue,
|
|
and calls the provided @free_func on each item in the #GQueue.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="free_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">the function to be called to free memory allocated</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="copy" c:identifier="g_queue_copy" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Copies a @queue. Note that is a shallow copy. If the elements in the
|
|
queue consist of pointers to data, the pointers are copied, but the
|
|
actual data is not.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a copy of @queue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="delete_link" c:identifier="g_queue_delete_link" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Removes @link_ from @queue and frees it.
|
|
|
|
@link_ must be part of @queue.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="link_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList link that must be part of @queue</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="find" c:identifier="g_queue_find" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Finds the first link in @queue which contains @data.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the first link in @queue which contains @data</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to find</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="find_custom" c:identifier="g_queue_find_custom" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Finds an element in a #GQueue, using a supplied function to find the
|
|
desired element. It iterates over the queue, calling the given function
|
|
which should return 0 when the desired element is found. The function
|
|
takes two gconstpointer arguments, the #GQueue element's data as the
|
|
first argument and the given user data as the second argument.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the found link, or %NULL if it wasn't found</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @func</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GCompareFunc to call for each element. It should return 0
|
|
when the desired element is found</doc>
|
|
<type name="CompareFunc" c:type="GCompareFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="foreach" c:identifier="g_queue_foreach" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">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.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="1">
|
|
<doc xml:space="preserve">the function to call for each element's data</doc>
|
|
<type name="Func" c:type="GFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to @func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free" c:identifier="g_queue_free">
|
|
<doc xml:space="preserve">Frees the memory allocated for the #GQueue. Only call this function
|
|
if @queue was created with g_queue_new(). If queue elements contain
|
|
dynamically-allocated memory, they should be freed first.
|
|
|
|
If queue elements contain dynamically-allocated memory, you should
|
|
either use g_queue_free_full() or free them manually first.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free_full" c:identifier="g_queue_free_full" version="2.32">
|
|
<doc xml:space="preserve">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).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="free_func" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">the function to be called to free each element's data</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_length" c:identifier="g_queue_get_length" version="2.4">
|
|
<doc xml:space="preserve">Returns the number of items in @queue.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of items in @queue</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="index" c:identifier="g_queue_index" version="2.4">
|
|
<doc xml:space="preserve">Returns the position of the first element in @queue which contains @data.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the position of the first element in @queue which
|
|
contains @data, or -1 if no element in @queue contains @data</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to find</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="init" c:identifier="g_queue_init" version="2.14">
|
|
<doc xml:space="preserve">A statically-allocated #GQueue must be initialized with this function
|
|
before it can be used. Alternatively you can initialize it with
|
|
#G_QUEUE_INIT. It is not necessary to initialize queues created with
|
|
g_queue_new().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">an uninitialized #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert_after" c:identifier="g_queue_insert_after" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Inserts @data into @queue after @sibling.
|
|
|
|
@sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the
|
|
data at the head of the queue.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="sibling" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GList link that must be part of @queue, or %NULL to
|
|
push at the head of the queue.</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to insert</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert_after_link" c:identifier="g_queue_insert_after_link" version="2.62" introspectable="0">
|
|
<doc xml:space="preserve">Inserts @link_ into @queue after @sibling.
|
|
|
|
@sibling must be part of @queue.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="sibling" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GList link that must be part of @queue, or %NULL to
|
|
push at the head of the queue.</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="link_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList link to insert which must not be part of any other list.</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert_before" c:identifier="g_queue_insert_before" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Inserts @data into @queue before @sibling.
|
|
|
|
@sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the
|
|
data at the tail of the queue.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="sibling" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GList link that must be part of @queue, or %NULL to
|
|
push at the tail of the queue.</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to insert</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert_before_link" c:identifier="g_queue_insert_before_link" version="2.62" introspectable="0">
|
|
<doc xml:space="preserve">Inserts @link_ into @queue before @sibling.
|
|
|
|
@sibling must be part of @queue.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="sibling" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GList link that must be part of @queue, or %NULL to
|
|
push at the tail of the queue.</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="link_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList link to insert which must not be part of any other list.</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert_sorted" c:identifier="g_queue_insert_sorted" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Inserts @data into @queue using @func to determine the new position.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to insert</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the #GCompareDataFunc used to compare elements in the queue. It is
|
|
called with two elements of the @queue and @user_data. It should
|
|
return 0 if the elements are equal, a negative value if the first
|
|
element comes before the second, and a positive value if the second
|
|
element comes before the first.</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_empty" c:identifier="g_queue_is_empty">
|
|
<doc xml:space="preserve">Returns %TRUE if the queue is empty.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the queue is empty</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue.</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="link_index" c:identifier="g_queue_link_index" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Returns the position of @link_ in @queue.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the position of @link_, or -1 if the link is
|
|
not part of @queue</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="link_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList link</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="peek_head" c:identifier="g_queue_peek_head">
|
|
<doc xml:space="preserve">Returns the first element of the queue.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the data of the first element in the queue, or %NULL
|
|
if the queue is empty</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="peek_head_link" c:identifier="g_queue_peek_head_link" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Returns the first link in @queue.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the first link in @queue, or %NULL if @queue is empty</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="peek_nth" c:identifier="g_queue_peek_nth" version="2.4">
|
|
<doc xml:space="preserve">Returns the @n'th element of @queue.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the data for the @n'th element of @queue,
|
|
or %NULL if @n is off the end of @queue</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position of the element</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="peek_nth_link" c:identifier="g_queue_peek_nth_link" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Returns the link at the given position</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the link at the @n'th position, or %NULL
|
|
if @n is off the end of the list</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position of the link</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="peek_tail" c:identifier="g_queue_peek_tail">
|
|
<doc xml:space="preserve">Returns the last element of the queue.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the data of the last element in the queue, or %NULL
|
|
if the queue is empty</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="peek_tail_link" c:identifier="g_queue_peek_tail_link" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Returns the last link in @queue.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the last link in @queue, or %NULL if @queue is empty</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="pop_head" c:identifier="g_queue_pop_head">
|
|
<doc xml:space="preserve">Removes the first element of the queue and returns its data.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the data of the first element in the queue, or %NULL
|
|
if the queue is empty</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="pop_head_link" c:identifier="g_queue_pop_head_link" introspectable="0">
|
|
<doc xml:space="preserve">Removes and returns the first element of the queue.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GList element at the head of the queue, or %NULL
|
|
if the queue is empty</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="pop_nth" c:identifier="g_queue_pop_nth" version="2.4">
|
|
<doc xml:space="preserve">Removes the @n'th element of @queue and returns its data.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the element's data, or %NULL if @n is off the end of @queue</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position of the element</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="pop_nth_link" c:identifier="g_queue_pop_nth_link" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Removes and returns the link at the given position.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the @n'th link, or %NULL if @n is off the end of @queue</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">the link's position</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="pop_tail" c:identifier="g_queue_pop_tail">
|
|
<doc xml:space="preserve">Removes the last element of the queue and returns its data.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the data of the last element in the queue, or %NULL
|
|
if the queue is empty</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="pop_tail_link" c:identifier="g_queue_pop_tail_link" introspectable="0">
|
|
<doc xml:space="preserve">Removes and returns the last element of the queue.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the #GList element at the tail of the queue, or %NULL
|
|
if the queue is empty</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="push_head" c:identifier="g_queue_push_head">
|
|
<doc xml:space="preserve">Adds a new element at the head of the queue.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue.</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new element.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="push_head_link" c:identifier="g_queue_push_head_link" introspectable="0">
|
|
<doc xml:space="preserve">Adds a new element at the head of the queue.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="link_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a single #GList element, not a list with more than one element</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="push_nth" c:identifier="g_queue_push_nth" version="2.4">
|
|
<doc xml:space="preserve">Inserts a new element into @queue at the given position.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new element</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position to insert the new element. If @n is negative or
|
|
larger than the number of elements in the @queue, the element is
|
|
added to the end of the queue.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="push_nth_link" c:identifier="g_queue_push_nth_link" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Inserts @link into @queue at the given position.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position to insert the link. If this is negative or larger than
|
|
the number of elements in @queue, the link is added to the end of
|
|
@queue.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="link_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the link to add to @queue</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="push_tail" c:identifier="g_queue_push_tail">
|
|
<doc xml:space="preserve">Adds a new element at the tail of the queue.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new element</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="push_tail_link" c:identifier="g_queue_push_tail_link" introspectable="0">
|
|
<doc xml:space="preserve">Adds a new element at the tail of the queue.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="link_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a single #GList element, not a list with more than one element</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="remove" c:identifier="g_queue_remove" version="2.4">
|
|
<doc xml:space="preserve">Removes the first element in @queue that contains @data.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @data was found and removed from @queue</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to remove</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="remove_all" c:identifier="g_queue_remove_all" version="2.4">
|
|
<doc xml:space="preserve">Remove all elements whose data equals @data from @queue.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of elements removed from @queue</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to remove</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="reverse" c:identifier="g_queue_reverse" version="2.4">
|
|
<doc xml:space="preserve">Reverses the order of the items in @queue.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="sort" c:identifier="g_queue_sort" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Sorts @queue using @compare_func.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="compare_func" transfer-ownership="none" closure="1">
|
|
<doc xml:space="preserve">the #GCompareDataFunc used to sort @queue. This function
|
|
is passed two elements of the queue and should return 0 if they are
|
|
equal, a negative value if the first comes before the second, and
|
|
a positive value if the second comes before the first.</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @compare_func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unlink" c:identifier="g_queue_unlink" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Unlinks @link_ so that it will no longer be part of @queue.
|
|
The link is not freed.
|
|
|
|
@link_ must be part of @queue.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="queue" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</instance-parameter>
|
|
<parameter name="link_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList link that must be part of @queue</doc>
|
|
<type name="GLib.List" c:type="GList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="new" c:identifier="g_queue_new" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GQueue.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a newly allocated #GQueue</doc>
|
|
<type name="Queue" c:type="GQueue*"/>
|
|
</return-value>
|
|
</function>
|
|
</record>
|
|
<record name="RWLock" c:type="GRWLock" version="2.32">
|
|
<doc xml:space="preserve">The GRWLock struct is an opaque data structure to represent a
|
|
reader-writer lock. It is similar to a #GMutex in that it allows
|
|
multiple threads to coordinate access to a shared resource.
|
|
|
|
The difference to a mutex is that a reader-writer lock discriminates
|
|
between read-only ('reader') and full ('writer') access. While only
|
|
one thread at a time is allowed write access (by holding the 'writer'
|
|
lock via g_rw_lock_writer_lock()), multiple threads can gain
|
|
simultaneous read-only access (by holding the 'reader' lock via
|
|
g_rw_lock_reader_lock()).
|
|
|
|
It is unspecified whether readers or writers have priority in acquiring the
|
|
lock when a reader already holds the lock and a writer is queued to acquire
|
|
it.
|
|
|
|
Here is an example for an array with access functions:
|
|
|[<!-- language="C" -->
|
|
GRWLock lock;
|
|
GPtrArray *array;
|
|
|
|
gpointer
|
|
my_array_get (guint index)
|
|
{
|
|
gpointer retval = NULL;
|
|
|
|
if (!array)
|
|
return NULL;
|
|
|
|
g_rw_lock_reader_lock (&lock);
|
|
if (index < array->len)
|
|
retval = g_ptr_array_index (array, index);
|
|
g_rw_lock_reader_unlock (&lock);
|
|
|
|
return retval;
|
|
}
|
|
|
|
void
|
|
my_array_set (guint index, gpointer data)
|
|
{
|
|
g_rw_lock_writer_lock (&lock);
|
|
|
|
if (!array)
|
|
array = g_ptr_array_new ();
|
|
|
|
if (index >= array->len)
|
|
g_ptr_array_set_size (array, index+1);
|
|
g_ptr_array_index (array, index) = data;
|
|
|
|
g_rw_lock_writer_unlock (&lock);
|
|
}
|
|
]|
|
|
This example shows an array which can be accessed by many readers
|
|
(the my_array_get() function) simultaneously, whereas the writers
|
|
(the my_array_set() function) will only be allowed one at a time
|
|
and only if no readers currently access the array. This is because
|
|
of the potentially dangerous resizing of the array. Using these
|
|
functions is fully multi-thread safe now.
|
|
|
|
If a #GRWLock is allocated in static storage then it can be used
|
|
without initialisation. Otherwise, you should call
|
|
g_rw_lock_init() on it and g_rw_lock_clear() when done.
|
|
|
|
A GRWLock should only be accessed with the g_rw_lock_ functions.</doc>
|
|
<field name="p" readable="0" private="1">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="i" readable="0" private="1">
|
|
<array zero-terminated="0" fixed-size="2">
|
|
<type name="guint" c:type="guint"/>
|
|
</array>
|
|
</field>
|
|
<method name="clear" c:identifier="g_rw_lock_clear">
|
|
<doc xml:space="preserve">Frees the resources allocated to a lock with g_rw_lock_init().
|
|
|
|
This function should not be used with a #GRWLock that has been
|
|
statically allocated.
|
|
|
|
Calling g_rw_lock_clear() when any thread holds the lock
|
|
leads to undefined behaviour.
|
|
|
|
Sine: 2.32</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rw_lock" transfer-ownership="none">
|
|
<doc xml:space="preserve">an initialized #GRWLock</doc>
|
|
<type name="RWLock" c:type="GRWLock*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="init" c:identifier="g_rw_lock_init" version="2.32">
|
|
<doc xml:space="preserve">Initializes a #GRWLock so that it can be used.
|
|
|
|
This function is useful to initialize a lock that has been
|
|
allocated on the stack, or as part of a larger structure. It is not
|
|
necessary to initialise a reader-writer lock that has been statically
|
|
allocated.
|
|
|
|
|[<!-- language="C" -->
|
|
typedef struct {
|
|
GRWLock l;
|
|
...
|
|
} Blob;
|
|
|
|
Blob *b;
|
|
|
|
b = g_new (Blob, 1);
|
|
g_rw_lock_init (&b->l);
|
|
]|
|
|
|
|
To undo the effect of g_rw_lock_init() when a lock is no longer
|
|
needed, use g_rw_lock_clear().
|
|
|
|
Calling g_rw_lock_init() on an already initialized #GRWLock leads
|
|
to undefined behaviour.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rw_lock" transfer-ownership="none">
|
|
<doc xml:space="preserve">an uninitialized #GRWLock</doc>
|
|
<type name="RWLock" c:type="GRWLock*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="reader_lock" c:identifier="g_rw_lock_reader_lock" version="2.32">
|
|
<doc xml:space="preserve">Obtain a read lock on @rw_lock. If another thread currently holds
|
|
the write lock on @rw_lock, the current thread will block. If another thread
|
|
does not hold the write lock, but is waiting for it, it is implementation
|
|
defined whether the reader or writer will block. Read locks can be taken
|
|
recursively.
|
|
|
|
It is implementation-defined how many threads are allowed to
|
|
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.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rw_lock" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRWLock</doc>
|
|
<type name="RWLock" c:type="GRWLock*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="reader_trylock" c:identifier="g_rw_lock_reader_trylock" version="2.32">
|
|
<doc xml:space="preserve">Tries to obtain a read lock on @rw_lock and returns %TRUE if
|
|
the read lock was successfully obtained. Otherwise it
|
|
returns %FALSE.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @rw_lock could be locked</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rw_lock" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRWLock</doc>
|
|
<type name="RWLock" c:type="GRWLock*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="reader_unlock" c:identifier="g_rw_lock_reader_unlock" version="2.32">
|
|
<doc xml:space="preserve">Release a read lock on @rw_lock.
|
|
|
|
Calling g_rw_lock_reader_unlock() on a lock that is not held
|
|
by the current thread leads to undefined behaviour.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rw_lock" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRWLock</doc>
|
|
<type name="RWLock" c:type="GRWLock*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="writer_lock" c:identifier="g_rw_lock_writer_lock" version="2.32">
|
|
<doc xml:space="preserve">Obtain a write lock on @rw_lock. If any thread already holds
|
|
a read or write lock on @rw_lock, the current thread will block
|
|
until all other threads have dropped their locks on @rw_lock.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rw_lock" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRWLock</doc>
|
|
<type name="RWLock" c:type="GRWLock*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="writer_trylock" c:identifier="g_rw_lock_writer_trylock" version="2.32">
|
|
<doc xml:space="preserve">Tries to obtain a write lock on @rw_lock. If any other thread holds
|
|
a read or write lock on @rw_lock, it immediately returns %FALSE.
|
|
Otherwise it locks @rw_lock and returns %TRUE.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @rw_lock could be locked</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rw_lock" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRWLock</doc>
|
|
<type name="RWLock" c:type="GRWLock*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="writer_unlock" c:identifier="g_rw_lock_writer_unlock" version="2.32">
|
|
<doc xml:space="preserve">Release a write lock on @rw_lock.
|
|
|
|
Calling g_rw_lock_writer_unlock() on a lock that is not held
|
|
by the current thread leads to undefined behaviour.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rw_lock" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRWLock</doc>
|
|
<type name="RWLock" c:type="GRWLock*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<record name="Rand" c:type="GRand" disguised="1">
|
|
<doc xml:space="preserve">The GRand struct is an opaque data structure. It should only be
|
|
accessed through the g_rand_* functions.</doc>
|
|
<method name="copy" c:identifier="g_rand_copy" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Copies a #GRand into a new one with the same exact state as before.
|
|
This way you can take a snapshot of the random number generator for
|
|
replaying later.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new #GRand</doc>
|
|
<type name="Rand" c:type="GRand*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rand_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRand</doc>
|
|
<type name="Rand" c:type="GRand*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="double" c:identifier="g_rand_double">
|
|
<doc xml:space="preserve">Returns the next random #gdouble from @rand_ equally distributed over
|
|
the range [0..1).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a random number</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rand_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRand</doc>
|
|
<type name="Rand" c:type="GRand*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="double_range" c:identifier="g_rand_double_range">
|
|
<doc xml:space="preserve">Returns the next random #gdouble from @rand_ equally distributed over
|
|
the range [@begin..@end).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a random number</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rand_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRand</doc>
|
|
<type name="Rand" c:type="GRand*"/>
|
|
</instance-parameter>
|
|
<parameter name="begin" transfer-ownership="none">
|
|
<doc xml:space="preserve">lower closed bound of the interval</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</parameter>
|
|
<parameter name="end" transfer-ownership="none">
|
|
<doc xml:space="preserve">upper open bound of the interval</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free" c:identifier="g_rand_free">
|
|
<doc xml:space="preserve">Frees the memory allocated for the #GRand.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rand_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRand</doc>
|
|
<type name="Rand" c:type="GRand*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="int" c:identifier="g_rand_int">
|
|
<doc xml:space="preserve">Returns the next random #guint32 from @rand_ equally distributed over
|
|
the range [0..2^32-1].</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a random number</doc>
|
|
<type name="guint32" c:type="guint32"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rand_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRand</doc>
|
|
<type name="Rand" c:type="GRand*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="int_range" c:identifier="g_rand_int_range">
|
|
<doc xml:space="preserve">Returns the next random #gint32 from @rand_ equally distributed over
|
|
the range [@begin..@end-1].</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a random number</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rand_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRand</doc>
|
|
<type name="Rand" c:type="GRand*"/>
|
|
</instance-parameter>
|
|
<parameter name="begin" transfer-ownership="none">
|
|
<doc xml:space="preserve">lower closed bound of the interval</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</parameter>
|
|
<parameter name="end" transfer-ownership="none">
|
|
<doc xml:space="preserve">upper open bound of the interval</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_seed" c:identifier="g_rand_set_seed">
|
|
<doc xml:space="preserve">Sets the seed for the random number generator #GRand to @seed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rand_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRand</doc>
|
|
<type name="Rand" c:type="GRand*"/>
|
|
</instance-parameter>
|
|
<parameter name="seed" transfer-ownership="none">
|
|
<doc xml:space="preserve">a value to reinitialize the random number generator</doc>
|
|
<type name="guint32" c:type="guint32"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_seed_array" c:identifier="g_rand_set_seed_array" version="2.4">
|
|
<doc xml:space="preserve">Initializes the random number generator by an array of longs.
|
|
Array can be of arbitrary size, though only the first 624 values
|
|
are taken. This function is useful if you have many low entropy
|
|
seeds, or if you require more then 32 bits of actual entropy for
|
|
your application.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rand_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRand</doc>
|
|
<type name="Rand" c:type="GRand*"/>
|
|
</instance-parameter>
|
|
<parameter name="seed" transfer-ownership="none">
|
|
<doc xml:space="preserve">array to initialize with</doc>
|
|
<type name="guint32" c:type="const guint32*"/>
|
|
</parameter>
|
|
<parameter name="seed_length" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of array</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="new" c:identifier="g_rand_new" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new random number generator initialized with a seed taken
|
|
either from `/dev/urandom` (if existing) or from the current time
|
|
(as a fallback).
|
|
|
|
On Windows, the seed is taken from rand_s().</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new #GRand</doc>
|
|
<type name="Rand" c:type="GRand*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="new_with_seed" c:identifier="g_rand_new_with_seed" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new random number generator initialized with @seed.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new #GRand</doc>
|
|
<type name="Rand" c:type="GRand*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="seed" transfer-ownership="none">
|
|
<doc xml:space="preserve">a value to initialize the random number generator</doc>
|
|
<type name="guint32" c:type="guint32"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="new_with_seed_array" c:identifier="g_rand_new_with_seed_array" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new random number generator initialized with @seed.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new #GRand</doc>
|
|
<type name="Rand" c:type="GRand*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="seed" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array of seeds to initialize the random number generator</doc>
|
|
<type name="guint32" c:type="const guint32*"/>
|
|
</parameter>
|
|
<parameter name="seed_length" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array of seeds to initialize the random number
|
|
generator</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<record name="RecMutex" c:type="GRecMutex" version="2.32">
|
|
<doc xml:space="preserve">The GRecMutex struct is an opaque data structure to represent a
|
|
recursive mutex. It is similar to a #GMutex with the difference
|
|
that it is possible to lock a GRecMutex multiple times in the same
|
|
thread without deadlock. When doing so, care has to be taken to
|
|
unlock the recursive mutex as often as it has been locked.
|
|
|
|
If a #GRecMutex is allocated in static storage then it can be used
|
|
without initialisation. Otherwise, you should call
|
|
g_rec_mutex_init() on it and g_rec_mutex_clear() when done.
|
|
|
|
A GRecMutex should only be accessed with the
|
|
g_rec_mutex_ functions.</doc>
|
|
<field name="p" readable="0" private="1">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="i" readable="0" private="1">
|
|
<array zero-terminated="0" fixed-size="2">
|
|
<type name="guint" c:type="guint"/>
|
|
</array>
|
|
</field>
|
|
<method name="clear" c:identifier="g_rec_mutex_clear">
|
|
<doc xml:space="preserve">Frees the resources allocated to a recursive mutex with
|
|
g_rec_mutex_init().
|
|
|
|
This function should not be used with a #GRecMutex that has been
|
|
statically allocated.
|
|
|
|
Calling g_rec_mutex_clear() on a locked recursive mutex leads
|
|
to undefined behaviour.
|
|
|
|
Sine: 2.32</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rec_mutex" transfer-ownership="none">
|
|
<doc xml:space="preserve">an initialized #GRecMutex</doc>
|
|
<type name="RecMutex" c:type="GRecMutex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="init" c:identifier="g_rec_mutex_init" version="2.32">
|
|
<doc xml:space="preserve">Initializes a #GRecMutex so that it can be used.
|
|
|
|
This function is useful to initialize a recursive mutex
|
|
that has been allocated on the stack, or as part of a larger
|
|
structure.
|
|
|
|
It is not necessary to initialise a recursive mutex that has been
|
|
statically allocated.
|
|
|
|
|[<!-- language="C" -->
|
|
typedef struct {
|
|
GRecMutex m;
|
|
...
|
|
} Blob;
|
|
|
|
Blob *b;
|
|
|
|
b = g_new (Blob, 1);
|
|
g_rec_mutex_init (&b->m);
|
|
]|
|
|
|
|
Calling g_rec_mutex_init() on an already initialized #GRecMutex
|
|
leads to undefined behaviour.
|
|
|
|
To undo the effect of g_rec_mutex_init() when a recursive mutex
|
|
is no longer needed, use g_rec_mutex_clear().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rec_mutex" transfer-ownership="none">
|
|
<doc xml:space="preserve">an uninitialized #GRecMutex</doc>
|
|
<type name="RecMutex" c:type="GRecMutex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="lock" c:identifier="g_rec_mutex_lock" version="2.32">
|
|
<doc xml:space="preserve">Locks @rec_mutex. If @rec_mutex is already locked by another
|
|
thread, the current thread will block until @rec_mutex is
|
|
unlocked by the other thread. If @rec_mutex is already locked
|
|
by the current thread, the 'lock count' of @rec_mutex is increased.
|
|
The mutex will only become available again when it is unlocked
|
|
as many times as it has been locked.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rec_mutex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRecMutex</doc>
|
|
<type name="RecMutex" c:type="GRecMutex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="trylock" c:identifier="g_rec_mutex_trylock" version="2.32">
|
|
<doc xml:space="preserve">Tries to lock @rec_mutex. If @rec_mutex is already locked
|
|
by another thread, it immediately returns %FALSE. Otherwise
|
|
it locks @rec_mutex and returns %TRUE.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @rec_mutex could be locked</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rec_mutex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRecMutex</doc>
|
|
<type name="RecMutex" c:type="GRecMutex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unlock" c:identifier="g_rec_mutex_unlock" version="2.32">
|
|
<doc xml:space="preserve">Unlocks @rec_mutex. If another thread is blocked in a
|
|
g_rec_mutex_lock() call for @rec_mutex, it will become unblocked
|
|
and can lock @rec_mutex itself.
|
|
|
|
Calling g_rec_mutex_unlock() on a recursive mutex that is not
|
|
locked by the current thread leads to undefined behaviour.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="rec_mutex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRecMutex</doc>
|
|
<type name="RecMutex" c:type="GRecMutex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<record name="Regex" c:type="GRegex" version="2.14" glib:type-name="GRegex" glib:get-type="g_regex_get_type" c:symbol-prefix="regex">
|
|
<doc xml:space="preserve">The g_regex_*() functions implement regular
|
|
expression pattern matching using syntax and semantics similar to
|
|
Perl regular expression.
|
|
|
|
Some functions accept a @start_position argument, setting it differs
|
|
from just passing over a shortened string and setting #G_REGEX_MATCH_NOTBOL
|
|
in the case of a pattern that begins with any kind of lookbehind assertion.
|
|
For example, consider the pattern "\Biss\B" which finds occurrences of "iss"
|
|
in the middle of words. ("\B" matches only if the current position in the
|
|
subject is not a word boundary.) When applied to the string "Mississipi"
|
|
from the fourth byte, namely "issipi", it does not match, because "\B" is
|
|
always false at the start of the subject, which is deemed to be a word
|
|
boundary. However, if the entire string is passed , but with
|
|
@start_position set to 4, it finds the second occurrence of "iss" because
|
|
it is able to look behind the starting point to discover that it is
|
|
preceded by a letter.
|
|
|
|
Note that, unless you set the #G_REGEX_RAW flag, all the strings passed
|
|
to these functions must be encoded in UTF-8. The lengths and the positions
|
|
inside the strings are in bytes and not in characters, so, for instance,
|
|
"\xc3\xa0" (i.e. "à") is two bytes long but it is treated as a
|
|
single character. If you set #G_REGEX_RAW the strings can be non-valid
|
|
UTF-8 strings and a byte is treated as a character, so "\xc3\xa0" is two
|
|
bytes and two characters long.
|
|
|
|
When matching a pattern, "\n" matches only against a "\n" character in
|
|
the string, and "\r" matches only a "\r" character. To match any newline
|
|
sequence use "\R". This particular group matches either the two-character
|
|
sequence CR + LF ("\r\n"), or one of the single characters LF (linefeed,
|
|
U+000A, "\n"), VT vertical tab, U+000B, "\v"), FF (formfeed, U+000C, "\f"),
|
|
CR (carriage return, U+000D, "\r"), NEL (next line, U+0085), LS (line
|
|
separator, U+2028), or PS (paragraph separator, U+2029).
|
|
|
|
The behaviour of the dot, circumflex, and dollar metacharacters are
|
|
affected by newline characters, the default is to recognize any newline
|
|
character (the same characters recognized by "\R"). This can be changed
|
|
with #G_REGEX_NEWLINE_CR, #G_REGEX_NEWLINE_LF and #G_REGEX_NEWLINE_CRLF
|
|
compile options, and with #G_REGEX_MATCH_NEWLINE_ANY,
|
|
#G_REGEX_MATCH_NEWLINE_CR, #G_REGEX_MATCH_NEWLINE_LF and
|
|
#G_REGEX_MATCH_NEWLINE_CRLF match options. These settings are also
|
|
relevant when compiling a pattern if #G_REGEX_EXTENDED is set, and an
|
|
unescaped "#" outside a character class is encountered. This indicates
|
|
a comment that lasts until after the next newline.
|
|
|
|
When setting the %G_REGEX_JAVASCRIPT_COMPAT flag, pattern syntax and pattern
|
|
matching is changed to be compatible with the way that regular expressions
|
|
work in JavaScript. More precisely, a lonely ']' character in the pattern
|
|
is a syntax error; the '\x' escape only allows 0 to 2 hexadecimal digits, and
|
|
you must use the '\u' escape sequence with 4 hex digits to specify a unicode
|
|
codepoint instead of '\x' or 'x{....}'. If '\x' or '\u' are not followed by
|
|
the specified number of hex digits, they match 'x' and 'u' literally; also
|
|
'\U' always matches 'U' instead of being an error in the pattern. Finally,
|
|
pattern matching is modified so that back references to an unset subpattern
|
|
group produces a match with the empty string instead of an error. See
|
|
pcreapi(3) for more information.
|
|
|
|
Creating and manipulating the same #GRegex structure from different
|
|
threads is not a problem as #GRegex does not modify its internal
|
|
state between creation and destruction, on the other hand #GMatchInfo
|
|
is not threadsafe.
|
|
|
|
The regular expressions low-level functionalities are obtained through
|
|
the excellent
|
|
[PCRE](http://www.pcre.org/)
|
|
library written by Philip Hazel.</doc>
|
|
<constructor name="new" c:identifier="g_regex_new" version="2.14" throws="1">
|
|
<doc xml:space="preserve">Compiles the regular expression to an internal form, and does
|
|
the initial setup of the #GRegex structure.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a #GRegex structure or %NULL if an error occurred. Call
|
|
g_regex_unref() when you are done with it</doc>
|
|
<type name="Regex" c:type="GRegex*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="pattern" transfer-ownership="none">
|
|
<doc xml:space="preserve">the regular expression</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="compile_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">compile options for the regular expression, or 0</doc>
|
|
<type name="RegexCompileFlags" c:type="GRegexCompileFlags"/>
|
|
</parameter>
|
|
<parameter name="match_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">match options for the regular expression, or 0</doc>
|
|
<type name="RegexMatchFlags" c:type="GRegexMatchFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<method name="get_capture_count" c:identifier="g_regex_get_capture_count" version="2.14">
|
|
<doc xml:space="preserve">Returns the number of capturing subpatterns in the pattern.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of capturing subpatterns</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex</doc>
|
|
<type name="Regex" c:type="const GRegex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_compile_flags" c:identifier="g_regex_get_compile_flags" version="2.26">
|
|
<doc xml:space="preserve">Returns the compile options that @regex was created with.
|
|
|
|
Depending on the version of PCRE that is used, this may or may not
|
|
include flags set by option expressions such as `(?i)` found at the
|
|
top-level within the compiled pattern.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">flags from #GRegexCompileFlags</doc>
|
|
<type name="RegexCompileFlags" c:type="GRegexCompileFlags"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex</doc>
|
|
<type name="Regex" c:type="const GRegex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_has_cr_or_lf" c:identifier="g_regex_get_has_cr_or_lf" version="2.34">
|
|
<doc xml:space="preserve">Checks whether the pattern contains explicit CR or LF references.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the pattern contains explicit CR or LF references</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex structure</doc>
|
|
<type name="Regex" c:type="const GRegex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_match_flags" c:identifier="g_regex_get_match_flags" version="2.26">
|
|
<doc xml:space="preserve">Returns the match options that @regex was created with.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">flags from #GRegexMatchFlags</doc>
|
|
<type name="RegexMatchFlags" c:type="GRegexMatchFlags"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex</doc>
|
|
<type name="Regex" c:type="const GRegex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_max_backref" c:identifier="g_regex_get_max_backref" version="2.14">
|
|
<doc xml:space="preserve">Returns the number of the highest back reference
|
|
in the pattern, or 0 if the pattern does not contain
|
|
back references.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of the highest back reference</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex</doc>
|
|
<type name="Regex" c:type="const GRegex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_max_lookbehind" c:identifier="g_regex_get_max_lookbehind" version="2.38">
|
|
<doc xml:space="preserve">Gets the number of characters in the longest lookbehind assertion in the
|
|
pattern. This information is useful when doing multi-segment matching using
|
|
the partial matching facilities.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of characters in the longest lookbehind assertion.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex structure</doc>
|
|
<type name="Regex" c:type="const GRegex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_pattern" c:identifier="g_regex_get_pattern" version="2.14">
|
|
<doc xml:space="preserve">Gets the pattern string associated with @regex, i.e. a copy of
|
|
the string passed to g_regex_new().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the pattern of @regex</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex structure</doc>
|
|
<type name="Regex" c:type="const GRegex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_string_number" c:identifier="g_regex_get_string_number" version="2.14">
|
|
<doc xml:space="preserve">Retrieves the number of the subexpression named @name.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">The number of the subexpression or -1 if @name
|
|
does not exists</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">#GRegex structure</doc>
|
|
<type name="Regex" c:type="const GRegex*"/>
|
|
</instance-parameter>
|
|
<parameter name="name" transfer-ownership="none">
|
|
<doc xml:space="preserve">name of the subexpression</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="match" c:identifier="g_regex_match" version="2.14">
|
|
<doc xml:space="preserve">Scans for a match in @string for the pattern in @regex.
|
|
The @match_options are combined with the match options specified
|
|
when the @regex structure was created, letting you have more
|
|
flexibility in reusing #GRegex structures.
|
|
|
|
Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8.
|
|
|
|
A #GMatchInfo structure, used to get information on the match,
|
|
is stored in @match_info if not %NULL. Note that if @match_info
|
|
is not %NULL then it is created even if the function returns %FALSE,
|
|
i.e. you must free it regardless if regular expression actually matched.
|
|
|
|
To retrieve all the non-overlapping matches of the pattern in
|
|
string you can use g_match_info_next().
|
|
|
|
|[<!-- language="C" -->
|
|
static void
|
|
print_uppercase_words (const gchar *string)
|
|
{
|
|
// Print all uppercase-only words.
|
|
GRegex *regex;
|
|
GMatchInfo *match_info;
|
|
|
|
regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
|
|
g_regex_match (regex, string, 0, &match_info);
|
|
while (g_match_info_matches (match_info))
|
|
{
|
|
gchar *word = g_match_info_fetch (match_info, 0);
|
|
g_print ("Found: %s\n", word);
|
|
g_free (word);
|
|
g_match_info_next (match_info, NULL);
|
|
}
|
|
g_match_info_free (match_info);
|
|
g_regex_unref (regex);
|
|
}
|
|
]|
|
|
|
|
@string is not copied and is used in #GMatchInfo internally. If
|
|
you use any #GMatchInfo method (except g_match_info_free()) after
|
|
freeing or modifying @string then the behaviour is undefined.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE is the string matched, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex structure from g_regex_new()</doc>
|
|
<type name="Regex" c:type="const GRegex*"/>
|
|
</instance-parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to scan for matches</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="match_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">match options</doc>
|
|
<type name="RegexMatchFlags" c:type="GRegexMatchFlags"/>
|
|
</parameter>
|
|
<parameter name="match_info" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">pointer to location where to store
|
|
the #GMatchInfo, or %NULL if you do not need it</doc>
|
|
<type name="MatchInfo" c:type="GMatchInfo**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="match_all" c:identifier="g_regex_match_all" version="2.14">
|
|
<doc xml:space="preserve">Using the standard algorithm for regular expression matching only
|
|
the longest match in the string is retrieved. This function uses
|
|
a different algorithm so it can retrieve all the possible matches.
|
|
For more documentation see g_regex_match_all_full().
|
|
|
|
A #GMatchInfo structure, used to get information on the match, is
|
|
stored in @match_info if not %NULL. Note that if @match_info is
|
|
not %NULL then it is created even if the function returns %FALSE,
|
|
i.e. you must free it regardless if regular expression actually
|
|
matched.
|
|
|
|
@string is not copied and is used in #GMatchInfo internally. If
|
|
you use any #GMatchInfo method (except g_match_info_free()) after
|
|
freeing or modifying @string then the behaviour is undefined.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE is the string matched, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex structure from g_regex_new()</doc>
|
|
<type name="Regex" c:type="const GRegex*"/>
|
|
</instance-parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to scan for matches</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="match_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">match options</doc>
|
|
<type name="RegexMatchFlags" c:type="GRegexMatchFlags"/>
|
|
</parameter>
|
|
<parameter name="match_info" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">pointer to location where to store
|
|
the #GMatchInfo, or %NULL if you do not need it</doc>
|
|
<type name="MatchInfo" c:type="GMatchInfo**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="match_all_full" c:identifier="g_regex_match_all_full" version="2.14" throws="1">
|
|
<doc xml:space="preserve">Using the standard algorithm for regular expression matching only
|
|
the longest match in the @string is retrieved, it is not possible
|
|
to obtain all the available matches. For instance matching
|
|
"<a> <b> <c>" against the pattern "<.*>"
|
|
you get "<a> <b> <c>".
|
|
|
|
This function uses a different algorithm (called DFA, i.e. deterministic
|
|
finite automaton), so it can retrieve all the possible matches, all
|
|
starting at the same point in the string. For instance matching
|
|
"<a> <b> <c>" against the pattern "<.*>;"
|
|
you would obtain three matches: "<a> <b> <c>",
|
|
"<a> <b>" and "<a>".
|
|
|
|
The number of matched strings is retrieved using
|
|
g_match_info_get_match_count(). To obtain the matched strings and
|
|
their position you can use, respectively, g_match_info_fetch() and
|
|
g_match_info_fetch_pos(). Note that the strings are returned in
|
|
reverse order of length; that is, the longest matching string is
|
|
given first.
|
|
|
|
Note that the DFA algorithm is slower than the standard one and it
|
|
is not able to capture substrings, so backreferences do not work.
|
|
|
|
Setting @start_position differs from just passing over a shortened
|
|
string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
|
|
that begins with any kind of lookbehind assertion, such as "\b".
|
|
|
|
Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8.
|
|
|
|
A #GMatchInfo structure, used to get information on the match, is
|
|
stored in @match_info if not %NULL. Note that if @match_info is
|
|
not %NULL then it is created even if the function returns %FALSE,
|
|
i.e. you must free it regardless if regular expression actually
|
|
matched.
|
|
|
|
@string is not copied and is used in #GMatchInfo internally. If
|
|
you use any #GMatchInfo method (except g_match_info_free()) after
|
|
freeing or modifying @string then the behaviour is undefined.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE is the string matched, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex structure from g_regex_new()</doc>
|
|
<type name="Regex" c:type="const GRegex*"/>
|
|
</instance-parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to scan for matches</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar*">
|
|
<type name="utf8" c:type="gchar"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="string_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @string, in bytes, or -1 if @string is nul-terminated</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="start_position" transfer-ownership="none">
|
|
<doc xml:space="preserve">starting index of the string to match, in bytes</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="match_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">match options</doc>
|
|
<type name="RegexMatchFlags" c:type="GRegexMatchFlags"/>
|
|
</parameter>
|
|
<parameter name="match_info" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">pointer to location where to store
|
|
the #GMatchInfo, or %NULL if you do not need it</doc>
|
|
<type name="MatchInfo" c:type="GMatchInfo**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="match_full" c:identifier="g_regex_match_full" version="2.14" throws="1">
|
|
<doc xml:space="preserve">Scans for a match in @string for the pattern in @regex.
|
|
The @match_options are combined with the match options specified
|
|
when the @regex structure was created, letting you have more
|
|
flexibility in reusing #GRegex structures.
|
|
|
|
Setting @start_position differs from just passing over a shortened
|
|
string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
|
|
that begins with any kind of lookbehind assertion, such as "\b".
|
|
|
|
Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8.
|
|
|
|
A #GMatchInfo structure, used to get information on the match, is
|
|
stored in @match_info if not %NULL. Note that if @match_info is
|
|
not %NULL then it is created even if the function returns %FALSE,
|
|
i.e. you must free it regardless if regular expression actually
|
|
matched.
|
|
|
|
@string is not copied and is used in #GMatchInfo internally. If
|
|
you use any #GMatchInfo method (except g_match_info_free()) after
|
|
freeing or modifying @string then the behaviour is undefined.
|
|
|
|
To retrieve all the non-overlapping matches of the pattern in
|
|
string you can use g_match_info_next().
|
|
|
|
|[<!-- language="C" -->
|
|
static void
|
|
print_uppercase_words (const gchar *string)
|
|
{
|
|
// Print all uppercase-only words.
|
|
GRegex *regex;
|
|
GMatchInfo *match_info;
|
|
GError *error = NULL;
|
|
|
|
regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
|
|
g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error);
|
|
while (g_match_info_matches (match_info))
|
|
{
|
|
gchar *word = g_match_info_fetch (match_info, 0);
|
|
g_print ("Found: %s\n", word);
|
|
g_free (word);
|
|
g_match_info_next (match_info, &error);
|
|
}
|
|
g_match_info_free (match_info);
|
|
g_regex_unref (regex);
|
|
if (error != NULL)
|
|
{
|
|
g_printerr ("Error while matching: %s\n", error->message);
|
|
g_error_free (error);
|
|
}
|
|
}
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE is the string matched, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex structure from g_regex_new()</doc>
|
|
<type name="Regex" c:type="const GRegex*"/>
|
|
</instance-parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to scan for matches</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar*">
|
|
<type name="utf8" c:type="gchar"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="string_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @string, in bytes, or -1 if @string is nul-terminated</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="start_position" transfer-ownership="none">
|
|
<doc xml:space="preserve">starting index of the string to match, in bytes</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="match_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">match options</doc>
|
|
<type name="RegexMatchFlags" c:type="GRegexMatchFlags"/>
|
|
</parameter>
|
|
<parameter name="match_info" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">pointer to location where to store
|
|
the #GMatchInfo, or %NULL if you do not need it</doc>
|
|
<type name="MatchInfo" c:type="GMatchInfo**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_regex_ref" version="2.14">
|
|
<doc xml:space="preserve">Increases reference count of @regex by 1.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">@regex</doc>
|
|
<type name="Regex" c:type="GRegex*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex</doc>
|
|
<type name="Regex" c:type="GRegex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="replace" c:identifier="g_regex_replace" version="2.14" throws="1">
|
|
<doc xml:space="preserve">Replaces all occurrences of the pattern in @regex with the
|
|
replacement text. Backreferences of the form '\number' or
|
|
'\g<number>' in the replacement text are interpolated by the
|
|
number-th captured subexpression of the match, '\g<name>' refers
|
|
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 '\\\\'.
|
|
|
|
There are also escapes that changes the case of the following text:
|
|
|
|
- \l: Convert to lower case the next character
|
|
- \u: Convert to upper case the next character
|
|
- \L: Convert to lower case till \E
|
|
- \U: Convert to upper case till \E
|
|
- \E: End case modification
|
|
|
|
If you do not need to use backreferences use g_regex_replace_literal().
|
|
|
|
The @replacement string must be UTF-8 encoded even if #G_REGEX_RAW was
|
|
passed to g_regex_new(). If you want to use not UTF-8 encoded strings
|
|
you can use g_regex_replace_literal().
|
|
|
|
Setting @start_position differs from just passing over a shortened
|
|
string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern that
|
|
begins with any kind of lookbehind assertion, such as "\b".</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string containing the replacements</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex structure</doc>
|
|
<type name="Regex" c:type="const GRegex*"/>
|
|
</instance-parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to perform matches against</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar*">
|
|
<type name="utf8" c:type="gchar"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="string_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @string, in bytes, or -1 if @string is nul-terminated</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="start_position" transfer-ownership="none">
|
|
<doc xml:space="preserve">starting index of the string to match, in bytes</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="replacement" transfer-ownership="none">
|
|
<doc xml:space="preserve">text to replace each match with</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="match_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">options for the match</doc>
|
|
<type name="RegexMatchFlags" c:type="GRegexMatchFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="replace_eval" c:identifier="g_regex_replace_eval" version="2.14" introspectable="0" throws="1">
|
|
<doc xml:space="preserve">Replaces occurrences of the pattern in regex with the output of
|
|
@eval for that occurrence.
|
|
|
|
Setting @start_position differs from just passing over a shortened
|
|
string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
|
|
that begins with any kind of lookbehind assertion, such as "\b".
|
|
|
|
The following example uses g_regex_replace_eval() to replace multiple
|
|
strings at once:
|
|
|[<!-- language="C" -->
|
|
static gboolean
|
|
eval_cb (const GMatchInfo *info,
|
|
GString *res,
|
|
gpointer data)
|
|
{
|
|
gchar *match;
|
|
gchar *r;
|
|
|
|
match = g_match_info_fetch (info, 0);
|
|
r = g_hash_table_lookup ((GHashTable *)data, match);
|
|
g_string_append (res, r);
|
|
g_free (match);
|
|
|
|
return FALSE;
|
|
}
|
|
|
|
...
|
|
|
|
GRegex *reg;
|
|
GHashTable *h;
|
|
gchar *res;
|
|
|
|
h = g_hash_table_new (g_str_hash, g_str_equal);
|
|
|
|
g_hash_table_insert (h, "1", "ONE");
|
|
g_hash_table_insert (h, "2", "TWO");
|
|
g_hash_table_insert (h, "3", "THREE");
|
|
g_hash_table_insert (h, "4", "FOUR");
|
|
|
|
reg = g_regex_new ("1|2|3|4", 0, 0, NULL);
|
|
res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL);
|
|
g_hash_table_destroy (h);
|
|
|
|
...
|
|
]|</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string containing the replacements</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex structure from g_regex_new()</doc>
|
|
<type name="Regex" c:type="const GRegex*"/>
|
|
</instance-parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">string to perform matches against</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar*">
|
|
<type name="utf8" c:type="gchar"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="string_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @string, in bytes, or -1 if @string is nul-terminated</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="start_position" transfer-ownership="none">
|
|
<doc xml:space="preserve">starting index of the string to match, in bytes</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="match_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">options for the match</doc>
|
|
<type name="RegexMatchFlags" c:type="GRegexMatchFlags"/>
|
|
</parameter>
|
|
<parameter name="eval" transfer-ownership="none" closure="5">
|
|
<doc xml:space="preserve">a function to call for each match</doc>
|
|
<type name="RegexEvalCallback" c:type="GRegexEvalCallback"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to the function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="replace_literal" c:identifier="g_regex_replace_literal" version="2.14" throws="1">
|
|
<doc xml:space="preserve">Replaces all occurrences of the pattern in @regex with the
|
|
replacement text. @replacement is replaced literally, to
|
|
include backreferences use g_regex_replace().
|
|
|
|
Setting @start_position differs from just passing over a
|
|
shortened string and setting #G_REGEX_MATCH_NOTBOL in the
|
|
case of a pattern that begins with any kind of lookbehind
|
|
assertion, such as "\b".</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string containing the replacements</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex structure</doc>
|
|
<type name="Regex" c:type="const GRegex*"/>
|
|
</instance-parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to perform matches against</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar*">
|
|
<type name="utf8" c:type="gchar"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="string_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @string, in bytes, or -1 if @string is nul-terminated</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="start_position" transfer-ownership="none">
|
|
<doc xml:space="preserve">starting index of the string to match, in bytes</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="replacement" transfer-ownership="none">
|
|
<doc xml:space="preserve">text to replace each match with</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="match_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">options for the match</doc>
|
|
<type name="RegexMatchFlags" c:type="GRegexMatchFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="split" c:identifier="g_regex_split" version="2.14">
|
|
<doc xml:space="preserve">Breaks the string on the pattern, and returns an array of the tokens.
|
|
If the pattern contains capturing parentheses, then the text for each
|
|
of the substrings will also be returned. If the pattern does not match
|
|
anywhere in the string, then the whole string is returned as the first
|
|
token.
|
|
|
|
As a special case, the result of splitting the empty string "" is an
|
|
empty vector, not a vector containing a single string. The reason for
|
|
this special case is that being able to represent an empty vector is
|
|
typically more useful than consistent handling of empty elements. If
|
|
you do need to represent empty elements, you'll need to check for the
|
|
empty string before calling this function.
|
|
|
|
A pattern that can match empty strings splits @string into separate
|
|
characters wherever it matches the empty string between characters.
|
|
For example splitting "ab c" using as a separator "\s*", you will get
|
|
"a", "b" and "c".</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a %NULL-terminated gchar ** array. Free
|
|
it using g_strfreev()</doc>
|
|
<array c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex structure</doc>
|
|
<type name="Regex" c:type="const GRegex*"/>
|
|
</instance-parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to split with the pattern</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="match_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">match time option flags</doc>
|
|
<type name="RegexMatchFlags" c:type="GRegexMatchFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="split_full" c:identifier="g_regex_split_full" version="2.14" throws="1">
|
|
<doc xml:space="preserve">Breaks the string on the pattern, and returns an array of the tokens.
|
|
If the pattern contains capturing parentheses, then the text for each
|
|
of the substrings will also be returned. If the pattern does not match
|
|
anywhere in the string, then the whole string is returned as the first
|
|
token.
|
|
|
|
As a special case, the result of splitting the empty string "" is an
|
|
empty vector, not a vector containing a single string. The reason for
|
|
this special case is that being able to represent an empty vector is
|
|
typically more useful than consistent handling of empty elements. If
|
|
you do need to represent empty elements, you'll need to check for the
|
|
empty string before calling this function.
|
|
|
|
A pattern that can match empty strings splits @string into separate
|
|
characters wherever it matches the empty string between characters.
|
|
For example splitting "ab c" using as a separator "\s*", you will get
|
|
"a", "b" and "c".
|
|
|
|
Setting @start_position differs from just passing over a shortened
|
|
string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern
|
|
that begins with any kind of lookbehind assertion, such as "\b".</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a %NULL-terminated gchar ** array. Free
|
|
it using g_strfreev()</doc>
|
|
<array c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex structure</doc>
|
|
<type name="Regex" c:type="const GRegex*"/>
|
|
</instance-parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to split with the pattern</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar*">
|
|
<type name="utf8" c:type="gchar"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="string_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @string, in bytes, or -1 if @string is nul-terminated</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="start_position" transfer-ownership="none">
|
|
<doc xml:space="preserve">starting index of the string to match, in bytes</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="match_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">match time option flags</doc>
|
|
<type name="RegexMatchFlags" c:type="GRegexMatchFlags"/>
|
|
</parameter>
|
|
<parameter name="max_tokens" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum number of tokens to split @string into.
|
|
If this is less than 1, the string is split completely</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_regex_unref" version="2.14">
|
|
<doc xml:space="preserve">Decreases reference count of @regex by 1. When reference count drops
|
|
to zero, it frees all the memory associated with the regex structure.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="regex" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GRegex</doc>
|
|
<type name="Regex" c:type="GRegex*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="check_replacement" c:identifier="g_regex_check_replacement" version="2.14" throws="1">
|
|
<doc xml:space="preserve">Checks whether @replacement is a valid replacement string
|
|
(see g_regex_replace()), i.e. that all escape sequences in
|
|
it are valid.
|
|
|
|
If @has_references is not %NULL then @replacement is checked
|
|
for pattern references. For instance, replacement text 'foo\n'
|
|
does not contain references and may be evaluated without information
|
|
about actual match, but '\0\1' (whole match followed by first
|
|
subpattern) requires valid #GMatchInfo object.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">whether @replacement is a valid replacement string</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="replacement" transfer-ownership="none">
|
|
<doc xml:space="preserve">the replacement string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="has_references" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store information about
|
|
references in @replacement or %NULL</doc>
|
|
<type name="gboolean" c:type="gboolean*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="error_quark" c:identifier="g_regex_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="escape_nul" c:identifier="g_regex_escape_nul" version="2.30">
|
|
<doc xml:space="preserve">Escapes the nul characters in @string to "\x00". It can be used
|
|
to compile a regex with embedded nul characters.
|
|
|
|
For completeness, @length can be -1 for a nul-terminated string.
|
|
In this case the output string will be of course equal to @string.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated escaped string</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to escape</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @string</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="escape_string" c:identifier="g_regex_escape_string" version="2.14">
|
|
<doc xml:space="preserve">Escapes the special characters used for regular expressions
|
|
in @string, for instance "a.b*c" becomes "a\.b\*c". This
|
|
function is useful to dynamically generate regular expressions.
|
|
|
|
@string can contain nul characters that are replaced with "\0",
|
|
in this case remember to specify the correct length of @string
|
|
in @length.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated escaped string</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to escape</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar*">
|
|
<type name="utf8" c:type="gchar"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @string, in bytes, or -1 if @string is nul-terminated</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="match_simple" c:identifier="g_regex_match_simple" version="2.14">
|
|
<doc xml:space="preserve">Scans for a match in @string for @pattern.
|
|
|
|
This function is equivalent to g_regex_match() but it does not
|
|
require to compile the pattern with g_regex_new(), avoiding some
|
|
lines of code when you need just to do a match without extracting
|
|
substrings, capture counts, and so on.
|
|
|
|
If this function is to be called on the same @pattern more than
|
|
once, it's more efficient to compile the pattern once with
|
|
g_regex_new() and then use g_regex_match().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the string matched, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="pattern" transfer-ownership="none">
|
|
<doc xml:space="preserve">the regular expression</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to scan for matches</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="compile_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">compile options for the regular expression, or 0</doc>
|
|
<type name="RegexCompileFlags" c:type="GRegexCompileFlags"/>
|
|
</parameter>
|
|
<parameter name="match_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">match options, or 0</doc>
|
|
<type name="RegexMatchFlags" c:type="GRegexMatchFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="split_simple" c:identifier="g_regex_split_simple" version="2.14">
|
|
<doc xml:space="preserve">Breaks the string on the pattern, and returns an array of
|
|
the tokens. If the pattern contains capturing parentheses,
|
|
then the text for each of the substrings will also be returned.
|
|
If the pattern does not match anywhere in the string, then the
|
|
whole string is returned as the first token.
|
|
|
|
This function is equivalent to g_regex_split() but it does
|
|
not require to compile the pattern with g_regex_new(), avoiding
|
|
some lines of code when you need just to do a split without
|
|
extracting substrings, capture counts, and so on.
|
|
|
|
If this function is to be called on the same @pattern more than
|
|
once, it's more efficient to compile the pattern once with
|
|
g_regex_new() and then use g_regex_split().
|
|
|
|
As a special case, the result of splitting the empty string ""
|
|
is an empty vector, not a vector containing a single string.
|
|
The reason for this special case is that being able to represent
|
|
an empty vector is typically more useful than consistent handling
|
|
of empty elements. If you do need to represent empty elements,
|
|
you'll need to check for the empty string before calling this
|
|
function.
|
|
|
|
A pattern that can match empty strings splits @string into
|
|
separate characters wherever it matches the empty string between
|
|
characters. For example splitting "ab c" using as a separator
|
|
"\s*", you will get "a", "b" and "c".</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a %NULL-terminated array of strings. Free
|
|
it using g_strfreev()</doc>
|
|
<array c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="pattern" transfer-ownership="none">
|
|
<doc xml:space="preserve">the regular expression</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to scan for matches</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="compile_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">compile options for the regular expression, or 0</doc>
|
|
<type name="RegexCompileFlags" c:type="GRegexCompileFlags"/>
|
|
</parameter>
|
|
<parameter name="match_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">match options, or 0</doc>
|
|
<type name="RegexMatchFlags" c:type="GRegexMatchFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<bitfield name="RegexCompileFlags" version="2.14" c:type="GRegexCompileFlags">
|
|
<doc xml:space="preserve">Flags specifying compile-time options.</doc>
|
|
<member name="caseless" value="1" c:identifier="G_REGEX_CASELESS">
|
|
<doc xml:space="preserve">Letters in the pattern match both upper- and
|
|
lowercase letters. This option can be changed within a pattern
|
|
by a "(?i)" option setting.</doc>
|
|
</member>
|
|
<member name="multiline" value="2" c:identifier="G_REGEX_MULTILINE">
|
|
<doc xml:space="preserve">By default, GRegex treats the strings as consisting
|
|
of a single line of characters (even if it actually contains
|
|
newlines). The "start of line" metacharacter ("^") matches only
|
|
at the start of the string, while the "end of line" metacharacter
|
|
("$") matches only at the end of the string, or before a terminating
|
|
newline (unless #G_REGEX_DOLLAR_ENDONLY is set). When
|
|
#G_REGEX_MULTILINE is set, the "start of line" and "end of line"
|
|
constructs match immediately following or immediately before any
|
|
newline in the string, respectively, as well as at the very start
|
|
and end. This can be changed within a pattern by a "(?m)" option
|
|
setting.</doc>
|
|
</member>
|
|
<member name="dotall" value="4" c:identifier="G_REGEX_DOTALL">
|
|
<doc xml:space="preserve">A dot metacharacter (".") in the pattern matches all
|
|
characters, including newlines. Without it, newlines are excluded.
|
|
This option can be changed within a pattern by a ("?s") option setting.</doc>
|
|
</member>
|
|
<member name="extended" value="8" c:identifier="G_REGEX_EXTENDED">
|
|
<doc xml:space="preserve">Whitespace data characters in the pattern are
|
|
totally ignored except when escaped or inside a character class.
|
|
Whitespace does not include the VT character (code 11). In addition,
|
|
characters between an unescaped "#" outside a character class and
|
|
the next newline character, inclusive, are also ignored. This can
|
|
be changed within a pattern by a "(?x)" option setting.</doc>
|
|
</member>
|
|
<member name="anchored" value="16" c:identifier="G_REGEX_ANCHORED">
|
|
<doc xml:space="preserve">The pattern is forced to be "anchored", that is,
|
|
it is constrained to match only at the first matching point in the
|
|
string that is being searched. This effect can also be achieved by
|
|
appropriate constructs in the pattern itself such as the "^"
|
|
metacharacter.</doc>
|
|
</member>
|
|
<member name="dollar_endonly" value="32" c:identifier="G_REGEX_DOLLAR_ENDONLY">
|
|
<doc xml:space="preserve">A dollar metacharacter ("$") in the pattern
|
|
matches only at the end of the string. Without this option, a
|
|
dollar also matches immediately before the final character if
|
|
it is a newline (but not before any other newlines). This option
|
|
is ignored if #G_REGEX_MULTILINE is set.</doc>
|
|
</member>
|
|
<member name="ungreedy" value="512" c:identifier="G_REGEX_UNGREEDY">
|
|
<doc xml:space="preserve">Inverts the "greediness" of the quantifiers so that
|
|
they are not greedy by default, but become greedy if followed by "?".
|
|
It can also be set by a "(?U)" option setting within the pattern.</doc>
|
|
</member>
|
|
<member name="raw" value="2048" c:identifier="G_REGEX_RAW">
|
|
<doc xml:space="preserve">Usually strings must be valid UTF-8 strings, using this
|
|
flag they are considered as a raw sequence of bytes.</doc>
|
|
</member>
|
|
<member name="no_auto_capture" value="4096" c:identifier="G_REGEX_NO_AUTO_CAPTURE">
|
|
<doc xml:space="preserve">Disables the use of numbered capturing
|
|
parentheses in the pattern. Any opening parenthesis that is not
|
|
followed by "?" behaves as if it were followed by "?:" but named
|
|
parentheses can still be used for capturing (and they acquire numbers
|
|
in the usual way).</doc>
|
|
</member>
|
|
<member name="optimize" value="8192" c:identifier="G_REGEX_OPTIMIZE">
|
|
<doc xml:space="preserve">Optimize the regular expression. If the pattern will
|
|
be used many times, then it may be worth the effort to optimize it
|
|
to improve the speed of matches.</doc>
|
|
</member>
|
|
<member name="firstline" value="262144" c:identifier="G_REGEX_FIRSTLINE">
|
|
<doc xml:space="preserve">Limits an unanchored pattern to match before (or at) the
|
|
first newline. Since: 2.34</doc>
|
|
</member>
|
|
<member name="dupnames" value="524288" c:identifier="G_REGEX_DUPNAMES">
|
|
<doc xml:space="preserve">Names used to identify capturing subpatterns need not
|
|
be unique. This can be helpful for certain types of pattern when it
|
|
is known that only one instance of the named subpattern can ever be
|
|
matched.</doc>
|
|
</member>
|
|
<member name="newline_cr" value="1048576" c:identifier="G_REGEX_NEWLINE_CR">
|
|
<doc xml:space="preserve">Usually any newline character or character sequence is
|
|
recognized. If this option is set, the only recognized newline character
|
|
is '\r'.</doc>
|
|
</member>
|
|
<member name="newline_lf" value="2097152" c:identifier="G_REGEX_NEWLINE_LF">
|
|
<doc xml:space="preserve">Usually any newline character or character sequence is
|
|
recognized. If this option is set, the only recognized newline character
|
|
is '\n'.</doc>
|
|
</member>
|
|
<member name="newline_crlf" value="3145728" c:identifier="G_REGEX_NEWLINE_CRLF">
|
|
<doc xml:space="preserve">Usually any newline character or character sequence is
|
|
recognized. If this option is set, the only recognized newline character
|
|
sequence is '\r\n'.</doc>
|
|
</member>
|
|
<member name="newline_anycrlf" value="5242880" c:identifier="G_REGEX_NEWLINE_ANYCRLF">
|
|
<doc xml:space="preserve">Usually any newline character or character sequence
|
|
is recognized. If this option is set, the only recognized newline character
|
|
sequences are '\r', '\n', and '\r\n'. Since: 2.34</doc>
|
|
</member>
|
|
<member name="bsr_anycrlf" value="8388608" c:identifier="G_REGEX_BSR_ANYCRLF">
|
|
<doc xml:space="preserve">Usually any newline character or character sequence
|
|
is recognised. If this option is set, then "\R" only recognizes the newline
|
|
characters '\r', '\n' and '\r\n'. Since: 2.34</doc>
|
|
</member>
|
|
<member name="javascript_compat" value="33554432" c:identifier="G_REGEX_JAVASCRIPT_COMPAT">
|
|
<doc xml:space="preserve">Changes behaviour so that it is compatible with
|
|
JavaScript rather than PCRE. Since: 2.34</doc>
|
|
</member>
|
|
</bitfield>
|
|
<enumeration name="RegexError" version="2.14" c:type="GRegexError" glib:error-domain="g-regex-error-quark">
|
|
<doc xml:space="preserve">Error codes returned by regular expressions functions.</doc>
|
|
<member name="compile" value="0" c:identifier="G_REGEX_ERROR_COMPILE">
|
|
<doc xml:space="preserve">Compilation of the regular expression failed.</doc>
|
|
</member>
|
|
<member name="optimize" value="1" c:identifier="G_REGEX_ERROR_OPTIMIZE">
|
|
<doc xml:space="preserve">Optimization of the regular expression failed.</doc>
|
|
</member>
|
|
<member name="replace" value="2" c:identifier="G_REGEX_ERROR_REPLACE">
|
|
<doc xml:space="preserve">Replacement failed due to an ill-formed replacement
|
|
string.</doc>
|
|
</member>
|
|
<member name="match" value="3" c:identifier="G_REGEX_ERROR_MATCH">
|
|
<doc xml:space="preserve">The match process failed.</doc>
|
|
</member>
|
|
<member name="internal" value="4" c:identifier="G_REGEX_ERROR_INTERNAL">
|
|
<doc xml:space="preserve">Internal error of the regular expression engine.
|
|
Since 2.16</doc>
|
|
</member>
|
|
<member name="stray_backslash" value="101" c:identifier="G_REGEX_ERROR_STRAY_BACKSLASH">
|
|
<doc xml:space="preserve">"\\" at end of pattern. Since 2.16</doc>
|
|
</member>
|
|
<member name="missing_control_char" value="102" c:identifier="G_REGEX_ERROR_MISSING_CONTROL_CHAR">
|
|
<doc xml:space="preserve">"\\c" at end of pattern. Since 2.16</doc>
|
|
</member>
|
|
<member name="unrecognized_escape" value="103" c:identifier="G_REGEX_ERROR_UNRECOGNIZED_ESCAPE">
|
|
<doc xml:space="preserve">Unrecognized character follows "\\".
|
|
Since 2.16</doc>
|
|
</member>
|
|
<member name="quantifiers_out_of_order" value="104" c:identifier="G_REGEX_ERROR_QUANTIFIERS_OUT_OF_ORDER">
|
|
<doc xml:space="preserve">Numbers out of order in "{}"
|
|
quantifier. Since 2.16</doc>
|
|
</member>
|
|
<member name="quantifier_too_big" value="105" c:identifier="G_REGEX_ERROR_QUANTIFIER_TOO_BIG">
|
|
<doc xml:space="preserve">Number too big in "{}" quantifier.
|
|
Since 2.16</doc>
|
|
</member>
|
|
<member name="unterminated_character_class" value="106" c:identifier="G_REGEX_ERROR_UNTERMINATED_CHARACTER_CLASS">
|
|
<doc xml:space="preserve">Missing terminating "]" for
|
|
character class. Since 2.16</doc>
|
|
</member>
|
|
<member name="invalid_escape_in_character_class" value="107" c:identifier="G_REGEX_ERROR_INVALID_ESCAPE_IN_CHARACTER_CLASS">
|
|
<doc xml:space="preserve">Invalid escape sequence
|
|
in character class. Since 2.16</doc>
|
|
</member>
|
|
<member name="range_out_of_order" value="108" c:identifier="G_REGEX_ERROR_RANGE_OUT_OF_ORDER">
|
|
<doc xml:space="preserve">Range out of order in character class.
|
|
Since 2.16</doc>
|
|
</member>
|
|
<member name="nothing_to_repeat" value="109" c:identifier="G_REGEX_ERROR_NOTHING_TO_REPEAT">
|
|
<doc xml:space="preserve">Nothing to repeat. Since 2.16</doc>
|
|
</member>
|
|
<member name="unrecognized_character" value="112" c:identifier="G_REGEX_ERROR_UNRECOGNIZED_CHARACTER">
|
|
<doc xml:space="preserve">Unrecognized character after "(?",
|
|
"(?<" or "(?P". Since 2.16</doc>
|
|
</member>
|
|
<member name="posix_named_class_outside_class" value="113" c:identifier="G_REGEX_ERROR_POSIX_NAMED_CLASS_OUTSIDE_CLASS">
|
|
<doc xml:space="preserve">POSIX named classes are
|
|
supported only within a class. Since 2.16</doc>
|
|
</member>
|
|
<member name="unmatched_parenthesis" value="114" c:identifier="G_REGEX_ERROR_UNMATCHED_PARENTHESIS">
|
|
<doc xml:space="preserve">Missing terminating ")" or ")"
|
|
without opening "(". Since 2.16</doc>
|
|
</member>
|
|
<member name="inexistent_subpattern_reference" value="115" c:identifier="G_REGEX_ERROR_INEXISTENT_SUBPATTERN_REFERENCE">
|
|
<doc xml:space="preserve">Reference to non-existent
|
|
subpattern. Since 2.16</doc>
|
|
</member>
|
|
<member name="unterminated_comment" value="118" c:identifier="G_REGEX_ERROR_UNTERMINATED_COMMENT">
|
|
<doc xml:space="preserve">Missing terminating ")" after comment.
|
|
Since 2.16</doc>
|
|
</member>
|
|
<member name="expression_too_large" value="120" c:identifier="G_REGEX_ERROR_EXPRESSION_TOO_LARGE">
|
|
<doc xml:space="preserve">Regular expression too large.
|
|
Since 2.16</doc>
|
|
</member>
|
|
<member name="memory_error" value="121" c:identifier="G_REGEX_ERROR_MEMORY_ERROR">
|
|
<doc xml:space="preserve">Failed to get memory. Since 2.16</doc>
|
|
</member>
|
|
<member name="variable_length_lookbehind" value="125" c:identifier="G_REGEX_ERROR_VARIABLE_LENGTH_LOOKBEHIND">
|
|
<doc xml:space="preserve">Lookbehind assertion is not
|
|
fixed length. Since 2.16</doc>
|
|
</member>
|
|
<member name="malformed_condition" value="126" c:identifier="G_REGEX_ERROR_MALFORMED_CONDITION">
|
|
<doc xml:space="preserve">Malformed number or name after "(?(".
|
|
Since 2.16</doc>
|
|
</member>
|
|
<member name="too_many_conditional_branches" value="127" c:identifier="G_REGEX_ERROR_TOO_MANY_CONDITIONAL_BRANCHES">
|
|
<doc xml:space="preserve">Conditional group contains
|
|
more than two branches. Since 2.16</doc>
|
|
</member>
|
|
<member name="assertion_expected" value="128" c:identifier="G_REGEX_ERROR_ASSERTION_EXPECTED">
|
|
<doc xml:space="preserve">Assertion expected after "(?(".
|
|
Since 2.16</doc>
|
|
</member>
|
|
<member name="unknown_posix_class_name" value="130" c:identifier="G_REGEX_ERROR_UNKNOWN_POSIX_CLASS_NAME">
|
|
<doc xml:space="preserve">Unknown POSIX class name.
|
|
Since 2.16</doc>
|
|
</member>
|
|
<member name="posix_collating_elements_not_supported" value="131" c:identifier="G_REGEX_ERROR_POSIX_COLLATING_ELEMENTS_NOT_SUPPORTED">
|
|
<doc xml:space="preserve">POSIX collating
|
|
elements are not supported. Since 2.16</doc>
|
|
</member>
|
|
<member name="hex_code_too_large" value="134" c:identifier="G_REGEX_ERROR_HEX_CODE_TOO_LARGE">
|
|
<doc xml:space="preserve">Character value in "\\x{...}" sequence
|
|
is too large. Since 2.16</doc>
|
|
</member>
|
|
<member name="invalid_condition" value="135" c:identifier="G_REGEX_ERROR_INVALID_CONDITION">
|
|
<doc xml:space="preserve">Invalid condition "(?(0)". Since 2.16</doc>
|
|
</member>
|
|
<member name="single_byte_match_in_lookbehind" value="136" c:identifier="G_REGEX_ERROR_SINGLE_BYTE_MATCH_IN_LOOKBEHIND">
|
|
<doc xml:space="preserve">\\C not allowed in
|
|
lookbehind assertion. Since 2.16</doc>
|
|
</member>
|
|
<member name="infinite_loop" value="140" c:identifier="G_REGEX_ERROR_INFINITE_LOOP">
|
|
<doc xml:space="preserve">Recursive call could loop indefinitely.
|
|
Since 2.16</doc>
|
|
</member>
|
|
<member name="missing_subpattern_name_terminator" value="142" c:identifier="G_REGEX_ERROR_MISSING_SUBPATTERN_NAME_TERMINATOR">
|
|
<doc xml:space="preserve">Missing terminator
|
|
in subpattern name. Since 2.16</doc>
|
|
</member>
|
|
<member name="duplicate_subpattern_name" value="143" c:identifier="G_REGEX_ERROR_DUPLICATE_SUBPATTERN_NAME">
|
|
<doc xml:space="preserve">Two named subpatterns have
|
|
the same name. Since 2.16</doc>
|
|
</member>
|
|
<member name="malformed_property" value="146" c:identifier="G_REGEX_ERROR_MALFORMED_PROPERTY">
|
|
<doc xml:space="preserve">Malformed "\\P" or "\\p" sequence.
|
|
Since 2.16</doc>
|
|
</member>
|
|
<member name="unknown_property" value="147" c:identifier="G_REGEX_ERROR_UNKNOWN_PROPERTY">
|
|
<doc xml:space="preserve">Unknown property name after "\\P" or
|
|
"\\p". Since 2.16</doc>
|
|
</member>
|
|
<member name="subpattern_name_too_long" value="148" c:identifier="G_REGEX_ERROR_SUBPATTERN_NAME_TOO_LONG">
|
|
<doc xml:space="preserve">Subpattern name is too long
|
|
(maximum 32 characters). Since 2.16</doc>
|
|
</member>
|
|
<member name="too_many_subpatterns" value="149" c:identifier="G_REGEX_ERROR_TOO_MANY_SUBPATTERNS">
|
|
<doc xml:space="preserve">Too many named subpatterns (maximum
|
|
10,000). Since 2.16</doc>
|
|
</member>
|
|
<member name="invalid_octal_value" value="151" c:identifier="G_REGEX_ERROR_INVALID_OCTAL_VALUE">
|
|
<doc xml:space="preserve">Octal value is greater than "\\377".
|
|
Since 2.16</doc>
|
|
</member>
|
|
<member name="too_many_branches_in_define" value="154" c:identifier="G_REGEX_ERROR_TOO_MANY_BRANCHES_IN_DEFINE">
|
|
<doc xml:space="preserve">"DEFINE" group contains more
|
|
than one branch. Since 2.16</doc>
|
|
</member>
|
|
<member name="define_repetion" value="155" c:identifier="G_REGEX_ERROR_DEFINE_REPETION">
|
|
<doc xml:space="preserve">Repeating a "DEFINE" group is not allowed.
|
|
This error is never raised. Since: 2.16 Deprecated: 2.34</doc>
|
|
</member>
|
|
<member name="inconsistent_newline_options" value="156" c:identifier="G_REGEX_ERROR_INCONSISTENT_NEWLINE_OPTIONS">
|
|
<doc xml:space="preserve">Inconsistent newline options.
|
|
Since 2.16</doc>
|
|
</member>
|
|
<member name="missing_back_reference" value="157" c:identifier="G_REGEX_ERROR_MISSING_BACK_REFERENCE">
|
|
<doc xml:space="preserve">"\\g" is not followed by a braced,
|
|
angle-bracketed, or quoted name or number, or by a plain number. Since: 2.16</doc>
|
|
</member>
|
|
<member name="invalid_relative_reference" value="158" c:identifier="G_REGEX_ERROR_INVALID_RELATIVE_REFERENCE">
|
|
<doc xml:space="preserve">relative reference must not be zero. Since: 2.34</doc>
|
|
</member>
|
|
<member name="backtracking_control_verb_argument_forbidden" value="159" c:identifier="G_REGEX_ERROR_BACKTRACKING_CONTROL_VERB_ARGUMENT_FORBIDDEN">
|
|
<doc xml:space="preserve">the backtracing
|
|
control verb used does not allow an argument. Since: 2.34</doc>
|
|
</member>
|
|
<member name="unknown_backtracking_control_verb" value="160" c:identifier="G_REGEX_ERROR_UNKNOWN_BACKTRACKING_CONTROL_VERB">
|
|
<doc xml:space="preserve">unknown backtracing
|
|
control verb. Since: 2.34</doc>
|
|
</member>
|
|
<member name="number_too_big" value="161" c:identifier="G_REGEX_ERROR_NUMBER_TOO_BIG">
|
|
<doc xml:space="preserve">number is too big in escape sequence. Since: 2.34</doc>
|
|
</member>
|
|
<member name="missing_subpattern_name" value="162" c:identifier="G_REGEX_ERROR_MISSING_SUBPATTERN_NAME">
|
|
<doc xml:space="preserve">Missing subpattern name. Since: 2.34</doc>
|
|
</member>
|
|
<member name="missing_digit" value="163" c:identifier="G_REGEX_ERROR_MISSING_DIGIT">
|
|
<doc xml:space="preserve">Missing digit. Since 2.34</doc>
|
|
</member>
|
|
<member name="invalid_data_character" value="164" c:identifier="G_REGEX_ERROR_INVALID_DATA_CHARACTER">
|
|
<doc xml:space="preserve">In JavaScript compatibility mode,
|
|
"[" is an invalid data character. Since: 2.34</doc>
|
|
</member>
|
|
<member name="extra_subpattern_name" value="165" c:identifier="G_REGEX_ERROR_EXTRA_SUBPATTERN_NAME">
|
|
<doc xml:space="preserve">different names for subpatterns of the
|
|
same number are not allowed. Since: 2.34</doc>
|
|
</member>
|
|
<member name="backtracking_control_verb_argument_required" value="166" c:identifier="G_REGEX_ERROR_BACKTRACKING_CONTROL_VERB_ARGUMENT_REQUIRED">
|
|
<doc xml:space="preserve">the backtracing control
|
|
verb requires an argument. Since: 2.34</doc>
|
|
</member>
|
|
<member name="invalid_control_char" value="168" c:identifier="G_REGEX_ERROR_INVALID_CONTROL_CHAR">
|
|
<doc xml:space="preserve">"\\c" must be followed by an ASCII
|
|
character. Since: 2.34</doc>
|
|
</member>
|
|
<member name="missing_name" value="169" c:identifier="G_REGEX_ERROR_MISSING_NAME">
|
|
<doc xml:space="preserve">"\\k" is not followed by a braced, angle-bracketed, or
|
|
quoted name. Since: 2.34</doc>
|
|
</member>
|
|
<member name="not_supported_in_class" value="171" c:identifier="G_REGEX_ERROR_NOT_SUPPORTED_IN_CLASS">
|
|
<doc xml:space="preserve">"\\N" is not supported in a class. Since: 2.34</doc>
|
|
</member>
|
|
<member name="too_many_forward_references" value="172" c:identifier="G_REGEX_ERROR_TOO_MANY_FORWARD_REFERENCES">
|
|
<doc xml:space="preserve">too many forward references. Since: 2.34</doc>
|
|
</member>
|
|
<member name="name_too_long" value="175" c:identifier="G_REGEX_ERROR_NAME_TOO_LONG">
|
|
<doc xml:space="preserve">the name is too long in "(*MARK)", "(*PRUNE)",
|
|
"(*SKIP)", or "(*THEN)". Since: 2.34</doc>
|
|
</member>
|
|
<member name="character_value_too_large" value="176" c:identifier="G_REGEX_ERROR_CHARACTER_VALUE_TOO_LARGE">
|
|
<doc xml:space="preserve">the character value in the \\u sequence is
|
|
too large. Since: 2.34</doc>
|
|
</member>
|
|
</enumeration>
|
|
<callback name="RegexEvalCallback" c:type="GRegexEvalCallback" version="2.14">
|
|
<doc xml:space="preserve">Specifies the type of the function passed to g_regex_replace_eval().
|
|
It is called for each occurrence of the pattern in the string passed
|
|
to g_regex_replace_eval(), and it should append the replacement to
|
|
@result.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%FALSE to continue the replacement process, %TRUE to stop it</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="match_info" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GMatchInfo generated by the match.
|
|
Use g_match_info_get_regex() and g_match_info_get_string() if you
|
|
need the #GRegex or the matched string.</doc>
|
|
<type name="MatchInfo" c:type="const GMatchInfo*"/>
|
|
</parameter>
|
|
<parameter name="result" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString containing the new string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2">
|
|
<doc xml:space="preserve">user data passed to g_regex_replace_eval()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<bitfield name="RegexMatchFlags" version="2.14" c:type="GRegexMatchFlags">
|
|
<doc xml:space="preserve">Flags specifying match-time options.</doc>
|
|
<member name="anchored" value="16" c:identifier="G_REGEX_MATCH_ANCHORED">
|
|
<doc xml:space="preserve">The pattern is forced to be "anchored", that is,
|
|
it is constrained to match only at the first matching point in the
|
|
string that is being searched. This effect can also be achieved by
|
|
appropriate constructs in the pattern itself such as the "^"
|
|
metacharacter.</doc>
|
|
</member>
|
|
<member name="notbol" value="128" c:identifier="G_REGEX_MATCH_NOTBOL">
|
|
<doc xml:space="preserve">Specifies that first character of the string is
|
|
not the beginning of a line, so the circumflex metacharacter should
|
|
not match before it. Setting this without #G_REGEX_MULTILINE (at
|
|
compile time) causes circumflex never to match. This option affects
|
|
only the behaviour of the circumflex metacharacter, it does not
|
|
affect "\A".</doc>
|
|
</member>
|
|
<member name="noteol" value="256" c:identifier="G_REGEX_MATCH_NOTEOL">
|
|
<doc xml:space="preserve">Specifies that the end of the subject string is
|
|
not the end of a line, so the dollar metacharacter should not match
|
|
it nor (except in multiline mode) a newline immediately before it.
|
|
Setting this without #G_REGEX_MULTILINE (at compile time) causes
|
|
dollar never to match. This option affects only the behaviour of
|
|
the dollar metacharacter, it does not affect "\Z" or "\z".</doc>
|
|
</member>
|
|
<member name="notempty" value="1024" c:identifier="G_REGEX_MATCH_NOTEMPTY">
|
|
<doc xml:space="preserve">An empty string is not considered to be a valid
|
|
match if this option is set. If there are alternatives in the pattern,
|
|
they are tried. If all the alternatives match the empty string, the
|
|
entire match fails. For example, if the pattern "a?b?" is applied to
|
|
a string not beginning with "a" or "b", it matches the empty string
|
|
at the start of the string. With this flag set, this match is not
|
|
valid, so GRegex searches further into the string for occurrences
|
|
of "a" or "b".</doc>
|
|
</member>
|
|
<member name="partial" value="32768" c:identifier="G_REGEX_MATCH_PARTIAL">
|
|
<doc xml:space="preserve">Turns on the partial matching feature, for more
|
|
documentation on partial matching see g_match_info_is_partial_match().</doc>
|
|
</member>
|
|
<member name="newline_cr" value="1048576" c:identifier="G_REGEX_MATCH_NEWLINE_CR">
|
|
<doc xml:space="preserve">Overrides the newline definition set when
|
|
creating a new #GRegex, setting the '\r' character as line terminator.</doc>
|
|
</member>
|
|
<member name="newline_lf" value="2097152" c:identifier="G_REGEX_MATCH_NEWLINE_LF">
|
|
<doc xml:space="preserve">Overrides the newline definition set when
|
|
creating a new #GRegex, setting the '\n' character as line terminator.</doc>
|
|
</member>
|
|
<member name="newline_crlf" value="3145728" c:identifier="G_REGEX_MATCH_NEWLINE_CRLF">
|
|
<doc xml:space="preserve">Overrides the newline definition set when
|
|
creating a new #GRegex, setting the '\r\n' characters sequence as line terminator.</doc>
|
|
</member>
|
|
<member name="newline_any" value="4194304" c:identifier="G_REGEX_MATCH_NEWLINE_ANY">
|
|
<doc xml:space="preserve">Overrides the newline definition set when
|
|
creating a new #GRegex, any Unicode newline sequence
|
|
is recognised as a newline. These are '\r', '\n' and '\rn', and the
|
|
single characters U+000B LINE TABULATION, U+000C FORM FEED (FF),
|
|
U+0085 NEXT LINE (NEL), U+2028 LINE SEPARATOR and
|
|
U+2029 PARAGRAPH SEPARATOR.</doc>
|
|
</member>
|
|
<member name="newline_anycrlf" value="5242880" c:identifier="G_REGEX_MATCH_NEWLINE_ANYCRLF">
|
|
<doc xml:space="preserve">Overrides the newline definition set when
|
|
creating a new #GRegex; any '\r', '\n', or '\r\n' character sequence
|
|
is recognized as a newline. Since: 2.34</doc>
|
|
</member>
|
|
<member name="bsr_anycrlf" value="8388608" c:identifier="G_REGEX_MATCH_BSR_ANYCRLF">
|
|
<doc xml:space="preserve">Overrides the newline definition for "\R" set when
|
|
creating a new #GRegex; only '\r', '\n', or '\r\n' character sequences
|
|
are recognized as a newline by "\R". Since: 2.34</doc>
|
|
</member>
|
|
<member name="bsr_any" value="16777216" c:identifier="G_REGEX_MATCH_BSR_ANY">
|
|
<doc xml:space="preserve">Overrides the newline definition for "\R" set when
|
|
creating a new #GRegex; any Unicode newline character or character sequence
|
|
are recognized as a newline by "\R". These are '\r', '\n' and '\rn', and the
|
|
single characters U+000B LINE TABULATION, U+000C FORM FEED (FF),
|
|
U+0085 NEXT LINE (NEL), U+2028 LINE SEPARATOR and
|
|
U+2029 PARAGRAPH SEPARATOR. Since: 2.34</doc>
|
|
</member>
|
|
<member name="partial_soft" value="32768" c:identifier="G_REGEX_MATCH_PARTIAL_SOFT">
|
|
<doc xml:space="preserve">An alias for #G_REGEX_MATCH_PARTIAL. Since: 2.34</doc>
|
|
</member>
|
|
<member name="partial_hard" value="134217728" c:identifier="G_REGEX_MATCH_PARTIAL_HARD">
|
|
<doc xml:space="preserve">Turns on the partial matching feature. In contrast to
|
|
to #G_REGEX_MATCH_PARTIAL_SOFT, this stops matching as soon as a partial match
|
|
is found, without continuing to search for a possible complete match. See
|
|
g_match_info_is_partial_match() for more information. Since: 2.34</doc>
|
|
</member>
|
|
<member name="notempty_atstart" value="268435456" c:identifier="G_REGEX_MATCH_NOTEMPTY_ATSTART">
|
|
<doc xml:space="preserve">Like #G_REGEX_MATCH_NOTEMPTY, but only applied to
|
|
the start of the matched string. For anchored
|
|
patterns this can only happen for pattern containing "\K". Since: 2.34</doc>
|
|
</member>
|
|
</bitfield>
|
|
<constant name="SEARCHPATH_SEPARATOR" value="58" c:type="G_SEARCHPATH_SEPARATOR">
|
|
<doc xml:space="preserve">The search path separator character.
|
|
This is ':' on UNIX machines and ';' under Windows.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="SEARCHPATH_SEPARATOR_S" value=":" c:type="G_SEARCHPATH_SEPARATOR_S">
|
|
<doc xml:space="preserve">The search path separator as a string.
|
|
This is ":" on UNIX machines and ";" under Windows.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="SIZEOF_LONG" value="8" c:type="GLIB_SIZEOF_LONG">
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<function-macro name="SIZEOF_MEMBER" c:identifier="G_SIZEOF_MEMBER" version="2.64" introspectable="0">
|
|
<doc xml:space="preserve">Returns the size of @member in the struct definition without having a
|
|
declared instance of @struct_type.</doc>
|
|
<parameters>
|
|
<parameter name="struct_type">
|
|
<doc xml:space="preserve">a structure type, e.g. #GOutputVector</doc>
|
|
</parameter>
|
|
<parameter name="member">
|
|
<doc xml:space="preserve">a field in the structure, e.g. `size`</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="SIZEOF_SIZE_T" value="8" c:type="GLIB_SIZEOF_SIZE_T">
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="SIZEOF_SSIZE_T" value="8" c:type="GLIB_SIZEOF_SSIZE_T">
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="SIZEOF_VOID_P" value="8" c:type="GLIB_SIZEOF_VOID_P">
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<record name="SList" c:type="GSList">
|
|
<doc xml:space="preserve">The #GSList struct is used for each element in the singly-linked
|
|
list.</doc>
|
|
<field name="data" writable="1">
|
|
<doc xml:space="preserve">holds the element's data, which can be a pointer to any kind
|
|
of data, or any integer value using the
|
|
[Type Conversion Macros][glib-Type-Conversion-Macros]</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="next" writable="1">
|
|
<doc xml:space="preserve">contains the link to the next element in the list.</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</field>
|
|
<function name="alloc" c:identifier="g_slist_alloc" introspectable="0">
|
|
<doc xml:space="preserve">Allocates space for one #GSList element. It is called by the
|
|
g_slist_append(), g_slist_prepend(), g_slist_insert() and
|
|
g_slist_insert_sorted() functions and so is rarely used on its own.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a pointer to the newly-allocated #GSList element.</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
</function>
|
|
<function name="append" c:identifier="g_slist_append" introspectable="0">
|
|
<doc xml:space="preserve">Adds a new element on to the end of the list.
|
|
|
|
The return value is the new start of the list, which may
|
|
have changed, so make sure you store the new value.
|
|
|
|
Note that g_slist_append() has to traverse the entire list
|
|
to find the end, which is inefficient when adding multiple
|
|
elements. A common idiom to avoid the inefficiency is to prepend
|
|
the elements and reverse the list when all elements have been added.
|
|
|
|
|[<!-- language="C" -->
|
|
// Notice that these are initialized to the empty list.
|
|
GSList *list = NULL, *number_list = NULL;
|
|
|
|
// This is a list of strings.
|
|
list = g_slist_append (list, "first");
|
|
list = g_slist_append (list, "second");
|
|
|
|
// This is a list of integers.
|
|
number_list = g_slist_append (number_list, GINT_TO_POINTER (27));
|
|
number_list = g_slist_append (number_list, GINT_TO_POINTER (14));
|
|
]|</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new start of the #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new element</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="concat" c:identifier="g_slist_concat" introspectable="0">
|
|
<doc xml:space="preserve">Adds the second #GSList onto the end of the first #GSList.
|
|
Note that the elements of the second #GSList are not copied.
|
|
They are used directly.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the start of the new #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="list2" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GSList to add to the end of the first #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="copy" c:identifier="g_slist_copy" introspectable="0">
|
|
<doc xml:space="preserve">Copies a #GSList.
|
|
|
|
Note that this is a "shallow" copy. If the list elements
|
|
consist of pointers to data, the pointers are copied but
|
|
the actual data isn't. See g_slist_copy_deep() if you need
|
|
to copy the data as well.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a copy of @list</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="copy_deep" c:identifier="g_slist_copy_deep" version="2.34" introspectable="0">
|
|
<doc xml:space="preserve">Makes a full (deep) copy of a #GSList.
|
|
|
|
In contrast with g_slist_copy(), this function uses @func to make a copy of
|
|
each list element, in addition to copying the list container itself.
|
|
|
|
@func, as a #GCopyFunc, takes two arguments, the data to be copied
|
|
and a @user_data pointer. On common processor architectures, it's safe to
|
|
pass %NULL as @user_data if the copy function takes only one argument. You
|
|
may get compiler warnings from this though if compiling with GCC’s
|
|
`-Wcast-function-type` warning.
|
|
|
|
For instance, if @list holds a list of GObjects, you can do:
|
|
|[<!-- language="C" -->
|
|
another_list = g_slist_copy_deep (list, (GCopyFunc) g_object_ref, NULL);
|
|
]|
|
|
|
|
And, to entirely free the new list, you could do:
|
|
|[<!-- language="C" -->
|
|
g_slist_free_full (another_list, g_object_unref);
|
|
]|</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a full copy of @list, use g_slist_free_full() to free it</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">a copy function used to copy every element in the list</doc>
|
|
<type name="CopyFunc" c:type="GCopyFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to the copy function @func, or #NULL</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="delete_link" c:identifier="g_slist_delete_link" introspectable="0">
|
|
<doc xml:space="preserve">Removes the node link_ from the list and frees it.
|
|
Compare this to g_slist_remove_link() which removes the node
|
|
without freeing it.
|
|
|
|
Removing arbitrary nodes from a singly-linked list requires time
|
|
that is proportional to the length of the list (ie. O(n)). If you
|
|
find yourself using g_slist_delete_link() frequently, you should
|
|
consider a different data structure, such as the doubly-linked
|
|
#GList.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new head of @list</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="link_" transfer-ownership="none">
|
|
<doc xml:space="preserve">node to delete</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="find" c:identifier="g_slist_find" introspectable="0">
|
|
<doc xml:space="preserve">Finds the element in a #GSList which
|
|
contains the given data.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the found #GSList element,
|
|
or %NULL if it is not found</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the element data to find</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="find_custom" c:identifier="g_slist_find_custom" introspectable="0">
|
|
<doc xml:space="preserve">Finds an element in a #GSList, using a supplied function to
|
|
find the desired element. It iterates over the list, calling
|
|
the given function which should return 0 when the desired
|
|
element is found. The function takes two #gconstpointer arguments,
|
|
the #GSList element's data as the first argument and the
|
|
given user data.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the found #GSList element, or %NULL if it is not found</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to the function</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<doc xml:space="preserve">the function to call for each element.
|
|
It should return 0 when the desired element is found</doc>
|
|
<type name="CompareFunc" c:type="GCompareFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="foreach" c:identifier="g_slist_foreach" introspectable="0">
|
|
<doc xml:space="preserve">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.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function to call with each element's data</doc>
|
|
<type name="Func" c:type="GFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to the function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="free" c:identifier="g_slist_free" introspectable="0">
|
|
<doc xml:space="preserve">Frees all of the memory used by a #GSList.
|
|
The freed elements are returned to the slice allocator.
|
|
|
|
If list elements contain dynamically-allocated memory,
|
|
you should either use g_slist_free_full() or free them manually
|
|
first.
|
|
|
|
It can be combined with g_steal_pointer() to ensure the list head pointer
|
|
is not left dangling:
|
|
|[<!-- language="C" -->
|
|
GSList *list_of_borrowed_things = …; /<!-- -->* (transfer container) *<!-- -->/
|
|
g_slist_free (g_steal_pointer (&list_of_borrowed_things));
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="free_1" c:identifier="g_slist_free_1" introspectable="0">
|
|
<doc xml:space="preserve">Frees one #GSList element.
|
|
It is usually used after g_slist_remove_link().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList element</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="free_full" c:identifier="g_slist_free_full" version="2.28" introspectable="0">
|
|
<doc xml:space="preserve">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).
|
|
|
|
It can be combined with g_steal_pointer() to ensure the list head pointer
|
|
is not left dangling ­— this also has the nice property that the head pointer
|
|
is cleared before any of the list elements are freed, to prevent double frees
|
|
from @free_func:
|
|
|[<!-- language="C" -->
|
|
GSList *list_of_owned_things = …; /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/
|
|
g_slist_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref);
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="free_func" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">the function to be called to free each element's data</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="index" c:identifier="g_slist_index" introspectable="0">
|
|
<doc xml:space="preserve">Gets the position of the element containing
|
|
the given data (starting from 0).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the element containing the data,
|
|
or -1 if the data is not found</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to find</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="insert" c:identifier="g_slist_insert" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a new element into the list at the given position.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new start of the #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new element</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="position" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position to insert the element.
|
|
If this is negative, or is larger than the number
|
|
of elements in the list, the new element is added on
|
|
to the end of the list.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="insert_before" c:identifier="g_slist_insert_before" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a node before @sibling containing @data.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new head of the list.</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="slist" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="sibling" transfer-ownership="none">
|
|
<doc xml:space="preserve">node to insert @data before</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to put in the newly-inserted node</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="insert_sorted" c:identifier="g_slist_insert_sorted" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a new element into the list, using the given
|
|
comparison function to determine its position.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new start of the #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new element</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<doc xml:space="preserve">the function to compare elements in the list.
|
|
It should return a number > 0 if the first parameter
|
|
comes after the second parameter in the sort order.</doc>
|
|
<type name="CompareFunc" c:type="GCompareFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="insert_sorted_with_data" c:identifier="g_slist_insert_sorted_with_data" version="2.10" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a new element into the list, using the given
|
|
comparison function to determine its position.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new start of the #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new element</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="3">
|
|
<doc xml:space="preserve">the function to compare elements in the list.
|
|
It should return a number > 0 if the first parameter
|
|
comes after the second parameter in the sort order.</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to comparison function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="last" c:identifier="g_slist_last" introspectable="0">
|
|
<doc xml:space="preserve">Gets the last element in a #GSList.
|
|
|
|
This function iterates over the whole list.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the last element in the #GSList,
|
|
or %NULL if the #GSList has no elements</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="length" c:identifier="g_slist_length" introspectable="0">
|
|
<doc xml:space="preserve">Gets the number of elements in a #GSList.
|
|
|
|
This function iterates over the whole list to
|
|
count its elements. To check whether the list is non-empty, it is faster to
|
|
check @list against %NULL.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of elements in the #GSList</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="nth" c:identifier="g_slist_nth" introspectable="0">
|
|
<doc xml:space="preserve">Gets the element at the given position in a #GSList.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the element, or %NULL if the position is off
|
|
the end of the #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position of the element, counting from 0</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="nth_data" c:identifier="g_slist_nth_data" introspectable="0">
|
|
<doc xml:space="preserve">Gets the data of the element at the given position.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the element's data, or %NULL if the position
|
|
is off the end of the #GSList</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position of the element</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="position" c:identifier="g_slist_position" introspectable="0">
|
|
<doc xml:space="preserve">Gets the position of the given element
|
|
in the #GSList (starting from 0).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the position of the element in the #GSList,
|
|
or -1 if the element is not found</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="llink" transfer-ownership="none">
|
|
<doc xml:space="preserve">an element in the #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="prepend" c:identifier="g_slist_prepend" introspectable="0">
|
|
<doc xml:space="preserve">Adds a new element on to the start of the list.
|
|
|
|
The return value is the new start of the list, which
|
|
may have changed, so make sure you store the new value.
|
|
|
|
|[<!-- language="C" -->
|
|
// Notice that it is initialized to the empty list.
|
|
GSList *list = NULL;
|
|
list = g_slist_prepend (list, "last");
|
|
list = g_slist_prepend (list, "first");
|
|
]|</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new start of the #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new element</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove" c:identifier="g_slist_remove" introspectable="0">
|
|
<doc xml:space="preserve">Removes an element from a #GSList.
|
|
If two elements contain the same data, only the first is removed.
|
|
If none of the elements contain the data, the #GSList is unchanged.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new start of the #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data of the element to remove</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_all" c:identifier="g_slist_remove_all" introspectable="0">
|
|
<doc xml:space="preserve">Removes all list nodes with data equal to @data.
|
|
Returns the new head of the list. Contrast with
|
|
g_slist_remove() which removes only the first node
|
|
matching the given data.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">new head of @list</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to remove</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_link" c:identifier="g_slist_remove_link" introspectable="0">
|
|
<doc xml:space="preserve">Removes an element from a #GSList, without
|
|
freeing the element. The removed element's next
|
|
link is set to %NULL, so that it becomes a
|
|
self-contained list with one element.
|
|
|
|
Removing arbitrary nodes from a singly-linked list
|
|
requires time that is proportional to the length of the list
|
|
(ie. O(n)). If you find yourself using g_slist_remove_link()
|
|
frequently, you should consider a different data structure,
|
|
such as the doubly-linked #GList.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new start of the #GSList, without the element</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="link_" transfer-ownership="none">
|
|
<doc xml:space="preserve">an element in the #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="reverse" c:identifier="g_slist_reverse" introspectable="0">
|
|
<doc xml:space="preserve">Reverses a #GSList.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the start of the reversed #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sort" c:identifier="g_slist_sort" introspectable="0">
|
|
<doc xml:space="preserve">Sorts a #GSList using the given comparison function. The algorithm
|
|
used is a stable sort.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the start of the sorted #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="compare_func" transfer-ownership="none">
|
|
<doc xml:space="preserve">the comparison function used to sort the #GSList.
|
|
This function is passed the data from 2 elements of the #GSList
|
|
and should return 0 if they are equal, a negative value if the
|
|
first element comes before the second, or a positive value if
|
|
the first element comes after the second.</doc>
|
|
<type name="CompareFunc" c:type="GCompareFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sort_with_data" c:identifier="g_slist_sort_with_data" introspectable="0">
|
|
<doc xml:space="preserve">Like g_slist_sort(), but the sort function accepts a user data argument.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">new head of the list</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList</doc>
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="compare_func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">comparison function</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to comparison function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<constant name="SOURCE_CONTINUE" value="true" c:type="G_SOURCE_CONTINUE" version="2.32">
|
|
<doc xml:space="preserve">Use this macro as the return value of a #GSourceFunc to leave
|
|
the #GSource in the main loop.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</constant>
|
|
<function-macro name="SOURCE_FUNC" c:identifier="G_SOURCE_FUNC" version="2.58" introspectable="0">
|
|
<doc xml:space="preserve">Cast a function pointer to a #GSourceFunc, suppressing warnings from GCC 8
|
|
onwards with `-Wextra` or `-Wcast-function-type` enabled about the function
|
|
types being incompatible.
|
|
|
|
For example, the correct type of callback for a source created by
|
|
g_child_watch_source_new() is #GChildWatchFunc, which accepts more arguments
|
|
than #GSourceFunc. Casting the function with `(GSourceFunc)` to call
|
|
g_source_set_callback() will trigger a warning, even though it will be cast
|
|
back to the correct type before it is called by the source.</doc>
|
|
<parameters>
|
|
<parameter name="f">
|
|
<doc xml:space="preserve">a function pointer.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="SOURCE_REMOVE" value="false" c:type="G_SOURCE_REMOVE" version="2.32">
|
|
<doc xml:space="preserve">Use this macro as the return value of a #GSourceFunc to remove
|
|
the #GSource from the main loop.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</constant>
|
|
<constant name="SQRT2" value="1.414214" c:type="G_SQRT2">
|
|
<doc xml:space="preserve">The square root of two.</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</constant>
|
|
<function-macro name="STRINGIFY" c:identifier="G_STRINGIFY" introspectable="0">
|
|
<doc xml:space="preserve">Accepts a macro or a string and converts it into a string after
|
|
preprocessor argument expansion. For example, the following code:
|
|
|
|
|[<!-- language="C" -->
|
|
#define AGE 27
|
|
const gchar *greeting = G_STRINGIFY (AGE) " today!";
|
|
]|
|
|
|
|
is transformed by the preprocessor into (code equivalent to):
|
|
|
|
|[<!-- language="C" -->
|
|
const gchar *greeting = "27 today!";
|
|
]|</doc>
|
|
<parameters>
|
|
<parameter name="macro_or_string">
|
|
<doc xml:space="preserve">a macro or a string</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="STRINGIFY_ARG" c:identifier="G_STRINGIFY_ARG" introspectable="0">
|
|
<parameters>
|
|
<parameter name="contents">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="STRUCT_MEMBER" c:identifier="G_STRUCT_MEMBER" introspectable="0">
|
|
<doc xml:space="preserve">Returns a member of a structure at a given offset, using the given type.</doc>
|
|
<parameters>
|
|
<parameter name="member_type">
|
|
<doc xml:space="preserve">the type of the struct field</doc>
|
|
</parameter>
|
|
<parameter name="struct_p">
|
|
<doc xml:space="preserve">a pointer to a struct</doc>
|
|
</parameter>
|
|
<parameter name="struct_offset">
|
|
<doc xml:space="preserve">the offset of the field from the start of the struct,
|
|
in bytes</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="STRUCT_MEMBER_P" c:identifier="G_STRUCT_MEMBER_P" introspectable="0">
|
|
<doc xml:space="preserve">Returns an untyped pointer to a given offset of a struct.</doc>
|
|
<parameters>
|
|
<parameter name="struct_p">
|
|
<doc xml:space="preserve">a pointer to a struct</doc>
|
|
</parameter>
|
|
<parameter name="struct_offset">
|
|
<doc xml:space="preserve">the offset from the start of the struct, in bytes</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="STRUCT_OFFSET" c:identifier="G_STRUCT_OFFSET" introspectable="0">
|
|
<doc xml:space="preserve">Returns the offset, in bytes, of a member of a struct.</doc>
|
|
<parameters>
|
|
<parameter name="struct_type">
|
|
<doc xml:space="preserve">a structure type, e.g. #GtkWidget</doc>
|
|
</parameter>
|
|
<parameter name="member">
|
|
<doc xml:space="preserve">a field in the structure, e.g. @window</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="STR_DELIMITERS" value="_-|> <." c:type="G_STR_DELIMITERS">
|
|
<doc xml:space="preserve">The standard delimiters, used in g_strdelimit().</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="SYSDEF_AF_INET" value="2" c:type="GLIB_SYSDEF_AF_INET">
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="SYSDEF_AF_INET6" value="10" c:type="GLIB_SYSDEF_AF_INET6">
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="SYSDEF_AF_UNIX" value="1" c:type="GLIB_SYSDEF_AF_UNIX">
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="SYSDEF_MSG_DONTROUTE" value="4" c:type="GLIB_SYSDEF_MSG_DONTROUTE">
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="SYSDEF_MSG_OOB" value="1" c:type="GLIB_SYSDEF_MSG_OOB">
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="SYSDEF_MSG_PEEK" value="2" c:type="GLIB_SYSDEF_MSG_PEEK">
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<record name="Scanner" c:type="GScanner">
|
|
<doc xml:space="preserve">The data structure representing a lexical scanner.
|
|
|
|
You should set @input_name after creating the scanner, since
|
|
it is used by the default message handler when displaying
|
|
warnings and errors. If you are scanning a file, the filename
|
|
would be a good choice.
|
|
|
|
The @user_data and @max_parse_errors fields are not used.
|
|
If you need to associate extra data with the scanner you
|
|
can place them here.
|
|
|
|
If you want to use your own message handler you can set the
|
|
@msg_handler field. The type of the message handler function
|
|
is declared by #GScannerMsgFunc.</doc>
|
|
<field name="user_data" writable="1">
|
|
<doc xml:space="preserve">unused</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="max_parse_errors" writable="1">
|
|
<doc xml:space="preserve">unused</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="parse_errors" writable="1">
|
|
<doc xml:space="preserve">g_scanner_error() increments this field</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="input_name" writable="1">
|
|
<doc xml:space="preserve">name of input stream, featured by the default message handler</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</field>
|
|
<field name="qdata" writable="1">
|
|
<doc xml:space="preserve">quarked data</doc>
|
|
<type name="Data" c:type="GData*"/>
|
|
</field>
|
|
<field name="config" writable="1">
|
|
<doc xml:space="preserve">link into the scanner configuration</doc>
|
|
<type name="ScannerConfig" c:type="GScannerConfig*"/>
|
|
</field>
|
|
<field name="token" writable="1">
|
|
<doc xml:space="preserve">token parsed by the last g_scanner_get_next_token()</doc>
|
|
<type name="TokenType" c:type="GTokenType"/>
|
|
</field>
|
|
<field name="value" writable="1">
|
|
<doc xml:space="preserve">value of the last token from g_scanner_get_next_token()</doc>
|
|
<type name="TokenValue" c:type="GTokenValue"/>
|
|
</field>
|
|
<field name="line" writable="1">
|
|
<doc xml:space="preserve">line number of the last token from g_scanner_get_next_token()</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="position" writable="1">
|
|
<doc xml:space="preserve">char number of the last token from g_scanner_get_next_token()</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="next_token" writable="1">
|
|
<doc xml:space="preserve">token parsed by the last g_scanner_peek_next_token()</doc>
|
|
<type name="TokenType" c:type="GTokenType"/>
|
|
</field>
|
|
<field name="next_value" writable="1">
|
|
<doc xml:space="preserve">value of the last token from g_scanner_peek_next_token()</doc>
|
|
<type name="TokenValue" c:type="GTokenValue"/>
|
|
</field>
|
|
<field name="next_line" writable="1">
|
|
<doc xml:space="preserve">line number of the last token from g_scanner_peek_next_token()</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="next_position" writable="1">
|
|
<doc xml:space="preserve">char number of the last token from g_scanner_peek_next_token()</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="symbol_table" readable="0" private="1">
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</field>
|
|
<field name="input_fd" readable="0" private="1">
|
|
<type name="gint" c:type="gint"/>
|
|
</field>
|
|
<field name="text" readable="0" private="1">
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</field>
|
|
<field name="text_end" readable="0" private="1">
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</field>
|
|
<field name="buffer" readable="0" private="1">
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</field>
|
|
<field name="scope_id" readable="0" private="1">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="msg_handler" writable="1">
|
|
<doc xml:space="preserve">handler function for _warn and _error</doc>
|
|
<type name="ScannerMsgFunc" c:type="GScannerMsgFunc"/>
|
|
</field>
|
|
<method name="cur_line" c:identifier="g_scanner_cur_line">
|
|
<doc xml:space="preserve">Returns the current line in the input stream (counting
|
|
from 1). This is the line of the last token parsed via
|
|
g_scanner_get_next_token().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the current line</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="cur_position" c:identifier="g_scanner_cur_position">
|
|
<doc xml:space="preserve">Returns the current position in the current line (counting
|
|
from 0). This is the position of the last token parsed via
|
|
g_scanner_get_next_token().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the current position on the line</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="cur_token" c:identifier="g_scanner_cur_token">
|
|
<doc xml:space="preserve">Gets the current token type. This is simply the @token
|
|
field in the #GScanner structure.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the current token type</doc>
|
|
<type name="TokenType" c:type="GTokenType"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="cur_value" c:identifier="g_scanner_cur_value" introspectable="0">
|
|
<doc xml:space="preserve">Gets the current token value. This is simply the @value
|
|
field in the #GScanner structure.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the current token value</doc>
|
|
<type name="TokenValue" c:type="GTokenValue"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="destroy" c:identifier="g_scanner_destroy">
|
|
<doc xml:space="preserve">Frees all memory used by the #GScanner.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="eof" c:identifier="g_scanner_eof">
|
|
<doc xml:space="preserve">Returns %TRUE if the scanner has reached the end of
|
|
the file or text buffer.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the scanner has reached the end of
|
|
the file or text buffer</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="error" c:identifier="g_scanner_error" introspectable="0">
|
|
<doc xml:space="preserve">Outputs an error message, via the #GScanner message handler.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">the message format. See the printf() documentation</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">the parameters to insert into the format string</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_next_token" c:identifier="g_scanner_get_next_token">
|
|
<doc xml:space="preserve">Parses the next token just like g_scanner_peek_next_token()
|
|
and also removes it from the input stream. The token data is
|
|
placed in the @token, @value, @line, and @position fields of
|
|
the #GScanner structure.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the type of the token</doc>
|
|
<type name="TokenType" c:type="GTokenType"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="input_file" c:identifier="g_scanner_input_file">
|
|
<doc xml:space="preserve">Prepares to scan a file.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
<parameter name="input_fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">a file descriptor</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="input_text" c:identifier="g_scanner_input_text">
|
|
<doc xml:space="preserve">Prepares to scan a text buffer.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
<parameter name="text" transfer-ownership="none">
|
|
<doc xml:space="preserve">the text buffer to scan</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="text_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the text buffer</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="lookup_symbol" c:identifier="g_scanner_lookup_symbol">
|
|
<doc xml:space="preserve">Looks up a symbol in the current scope and return its value.
|
|
If the symbol is not bound in the current scope, %NULL is
|
|
returned.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the value of @symbol in the current scope, or %NULL
|
|
if @symbol is not bound in the current scope</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
<parameter name="symbol" transfer-ownership="none">
|
|
<doc xml:space="preserve">the symbol to look up</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="peek_next_token" c:identifier="g_scanner_peek_next_token">
|
|
<doc xml:space="preserve">Parses the next token, without removing it from the input stream.
|
|
The token data is placed in the @next_token, @next_value, @next_line,
|
|
and @next_position fields of the #GScanner structure.
|
|
|
|
Note that, while the token is not removed from the input stream
|
|
(i.e. the next call to g_scanner_get_next_token() will return the
|
|
same token), it will not be reevaluated. This can lead to surprising
|
|
results when changing scope or the scanner configuration after peeking
|
|
the next token. Getting the next token after switching the scope or
|
|
configuration will return whatever was peeked before, regardless of
|
|
any symbols that may have been added or removed in the new scope.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the type of the token</doc>
|
|
<type name="TokenType" c:type="GTokenType"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="scope_add_symbol" c:identifier="g_scanner_scope_add_symbol">
|
|
<doc xml:space="preserve">Adds a symbol to the given scope.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
<parameter name="scope_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">the scope id</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="symbol" transfer-ownership="none">
|
|
<doc xml:space="preserve">the symbol to add</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the value of the symbol</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="scope_foreach_symbol" c:identifier="g_scanner_scope_foreach_symbol" introspectable="0">
|
|
<doc xml:space="preserve">Calls the given function for each of the symbol/value pairs
|
|
in the given scope of the #GScanner. The function is passed
|
|
the symbol and value of each pair, and the given @user_data
|
|
parameter.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
<parameter name="scope_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">the scope id</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function to call for each symbol/value pair</doc>
|
|
<type name="HFunc" c:type="GHFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to the function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="scope_lookup_symbol" c:identifier="g_scanner_scope_lookup_symbol">
|
|
<doc xml:space="preserve">Looks up a symbol in a scope and return its value. If the
|
|
symbol is not bound in the scope, %NULL is returned.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the value of @symbol in the given scope, or %NULL
|
|
if @symbol is not bound in the given scope.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
<parameter name="scope_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">the scope id</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="symbol" transfer-ownership="none">
|
|
<doc xml:space="preserve">the symbol to look up</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="scope_remove_symbol" c:identifier="g_scanner_scope_remove_symbol">
|
|
<doc xml:space="preserve">Removes a symbol from a scope.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
<parameter name="scope_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">the scope id</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="symbol" transfer-ownership="none">
|
|
<doc xml:space="preserve">the symbol to remove</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_scope" c:identifier="g_scanner_set_scope">
|
|
<doc xml:space="preserve">Sets the current scope.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the old scope id</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
<parameter name="scope_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">the new scope id</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="sync_file_offset" c:identifier="g_scanner_sync_file_offset">
|
|
<doc xml:space="preserve">Rewinds the filedescriptor to the current buffer position
|
|
and blows the file read ahead buffer. This is useful for
|
|
third party uses of the scanners filedescriptor, which hooks
|
|
onto the current scanning position.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unexp_token" c:identifier="g_scanner_unexp_token">
|
|
<doc xml:space="preserve">Outputs a message through the scanner's msg_handler,
|
|
resulting from an unexpected token in the input stream.
|
|
Note that you should not call g_scanner_peek_next_token()
|
|
followed by g_scanner_unexp_token() without an intermediate
|
|
call to g_scanner_get_next_token(), as g_scanner_unexp_token()
|
|
evaluates the scanner's current token (not the peeked token)
|
|
to construct part of the message.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
<parameter name="expected_token" transfer-ownership="none">
|
|
<doc xml:space="preserve">the expected token</doc>
|
|
<type name="TokenType" c:type="GTokenType"/>
|
|
</parameter>
|
|
<parameter name="identifier_spec" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string describing how the scanner's user
|
|
refers to identifiers (%NULL defaults to "identifier").
|
|
This is used if @expected_token is %G_TOKEN_IDENTIFIER or
|
|
%G_TOKEN_IDENTIFIER_NULL.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="symbol_spec" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string describing how the scanner's user refers
|
|
to symbols (%NULL defaults to "symbol"). This is used if
|
|
@expected_token is %G_TOKEN_SYMBOL or any token value greater
|
|
than %G_TOKEN_LAST.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="symbol_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">the name of the symbol, if the scanner's current
|
|
token is a symbol.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="message" transfer-ownership="none">
|
|
<doc xml:space="preserve">a message string to output at the end of the
|
|
warning/error, or %NULL.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="is_error" transfer-ownership="none">
|
|
<doc xml:space="preserve">if %TRUE it is output as an error. If %FALSE it is
|
|
output as a warning.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="warn" c:identifier="g_scanner_warn" introspectable="0">
|
|
<doc xml:space="preserve">Outputs a warning message, via the #GScanner message handler.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</instance-parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">the message format. See the printf() documentation</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">the parameters to insert into the format string</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="new" c:identifier="g_scanner_new" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GScanner.
|
|
|
|
The @config_templ structure specifies the initial settings
|
|
of the scanner, which are copied into the #GScanner
|
|
@config field. If you pass %NULL then the default settings
|
|
are used.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="config_templ" transfer-ownership="none">
|
|
<doc xml:space="preserve">the initial scanner settings</doc>
|
|
<type name="ScannerConfig" c:type="const GScannerConfig*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<record name="ScannerConfig" c:type="GScannerConfig">
|
|
<doc xml:space="preserve">Specifies the #GScanner parser configuration. Most settings can
|
|
be changed during the parsing phase and will affect the lexical
|
|
parsing of the next unpeeked token.</doc>
|
|
<field name="cset_skip_characters" writable="1">
|
|
<doc xml:space="preserve">specifies which characters should be skipped
|
|
by the scanner (the default is the whitespace characters: space,
|
|
tab, carriage-return and line-feed).</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</field>
|
|
<field name="cset_identifier_first" writable="1">
|
|
<doc xml:space="preserve">specifies the characters which can start
|
|
identifiers (the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z).</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</field>
|
|
<field name="cset_identifier_nth" writable="1">
|
|
<doc xml:space="preserve">specifies the characters which can be used
|
|
in identifiers, after the first character (the default is
|
|
#G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS,
|
|
#G_CSET_LATINC).</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</field>
|
|
<field name="cpair_comment_single" writable="1">
|
|
<doc xml:space="preserve">specifies the characters at the start and
|
|
end of single-line comments. The default is "#\n" which means
|
|
that single-line comments start with a '#' and continue until
|
|
a '\n' (end of line).</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</field>
|
|
<field name="case_sensitive" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if symbols are case sensitive (the
|
|
default is %FALSE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="skip_comment_multi" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if multi-line comments are skipped
|
|
and not returned as tokens (the default is %TRUE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="skip_comment_single" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if single-line comments are skipped
|
|
and not returned as tokens (the default is %TRUE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="scan_comment_multi" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if multi-line comments are recognized
|
|
(the default is %TRUE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="scan_identifier" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if identifiers are recognized (the
|
|
default is %TRUE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="scan_identifier_1char" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if single-character
|
|
identifiers are recognized (the default is %FALSE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="scan_identifier_NULL" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if %NULL is reported as
|
|
%G_TOKEN_IDENTIFIER_NULL (the default is %FALSE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="scan_symbols" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if symbols are recognized (the default
|
|
is %TRUE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="scan_binary" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if binary numbers are recognized (the
|
|
default is %FALSE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="scan_octal" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if octal numbers are recognized (the
|
|
default is %TRUE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="scan_float" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if floating point numbers are recognized
|
|
(the default is %TRUE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="scan_hex" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if hexadecimal numbers are recognized (the
|
|
default is %TRUE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="scan_hex_dollar" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if '$' is recognized as a prefix for
|
|
hexadecimal numbers (the default is %FALSE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="scan_string_sq" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if strings can be enclosed in single
|
|
quotes (the default is %TRUE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="scan_string_dq" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if strings can be enclosed in double
|
|
quotes (the default is %TRUE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="numbers_2_int" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if binary, octal and hexadecimal numbers
|
|
are reported as #G_TOKEN_INT (the default is %TRUE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="int_2_float" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if all numbers are reported as %G_TOKEN_FLOAT
|
|
(the default is %FALSE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="identifier_2_string" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if identifiers are reported as strings
|
|
(the default is %FALSE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="char_2_token" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if characters are reported by setting
|
|
`token = ch` or as %G_TOKEN_CHAR (the default is %TRUE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="symbol_2_token" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if symbols are reported by setting
|
|
`token = v_symbol` or as %G_TOKEN_SYMBOL (the default is %FALSE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="scope_0_fallback" writable="1" bits="1">
|
|
<doc xml:space="preserve">specifies if a symbol is searched for in the
|
|
default scope in addition to the current scope (the default is %FALSE).</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="store_int64" writable="1" bits="1">
|
|
<doc xml:space="preserve">use value.v_int64 rather than v_int</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="padding_dummy" readable="0" private="1">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
</record>
|
|
<callback name="ScannerMsgFunc" c:type="GScannerMsgFunc">
|
|
<doc xml:space="preserve">Specifies the type of the message handler function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="scanner" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
<type name="Scanner" c:type="GScanner*"/>
|
|
</parameter>
|
|
<parameter name="message" transfer-ownership="none">
|
|
<doc xml:space="preserve">the message</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="error" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the message signals an error,
|
|
%FALSE if it signals a warning.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<enumeration name="SeekType" c:type="GSeekType">
|
|
<doc xml:space="preserve">An enumeration specifying the base position for a
|
|
g_io_channel_seek_position() operation.</doc>
|
|
<member name="cur" value="0" c:identifier="G_SEEK_CUR">
|
|
<doc xml:space="preserve">the current position in the file.</doc>
|
|
</member>
|
|
<member name="set" value="1" c:identifier="G_SEEK_SET">
|
|
<doc xml:space="preserve">the start of the file.</doc>
|
|
</member>
|
|
<member name="end" value="2" c:identifier="G_SEEK_END">
|
|
<doc xml:space="preserve">the end of the file.</doc>
|
|
</member>
|
|
</enumeration>
|
|
<record name="Sequence" c:type="GSequence" disguised="1">
|
|
<doc xml:space="preserve">The #GSequence struct is an opaque data type representing a
|
|
[sequence][glib-Sequences] data type.</doc>
|
|
<method name="append" c:identifier="g_sequence_append" version="2.14">
|
|
<doc xml:space="preserve">Adds a new item to the end of @seq.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">an iterator pointing to the new item</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="seq" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new item</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="foreach" c:identifier="g_sequence_foreach" version="2.14" introspectable="0">
|
|
<doc xml:space="preserve">Calls @func for each item in the sequence passing @user_data
|
|
to the function. @func must not modify the sequence itself.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="seq" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</instance-parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="1">
|
|
<doc xml:space="preserve">the function to call for each item in @seq</doc>
|
|
<type name="Func" c:type="GFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free" c:identifier="g_sequence_free" version="2.14">
|
|
<doc xml:space="preserve">Frees the memory allocated for @seq. If @seq has a data destroy
|
|
function associated with it, that function is called on all items
|
|
in @seq.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="seq" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_begin_iter" c:identifier="g_sequence_get_begin_iter" version="2.14">
|
|
<doc xml:space="preserve">Returns the begin iterator for @seq.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the begin iterator for @seq.</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="seq" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_end_iter" c:identifier="g_sequence_get_end_iter" version="2.14">
|
|
<doc xml:space="preserve">Returns the end iterator for @seg</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the end iterator for @seq</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="seq" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_iter_at_pos" c:identifier="g_sequence_get_iter_at_pos" version="2.14">
|
|
<doc xml:space="preserve">Returns the iterator at position @pos. If @pos is negative or larger
|
|
than the number of items in @seq, the end iterator is returned.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">The #GSequenceIter at position @pos</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="seq" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</instance-parameter>
|
|
<parameter name="pos" transfer-ownership="none">
|
|
<doc xml:space="preserve">a position in @seq, or -1 for the end</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_length" c:identifier="g_sequence_get_length" version="2.14">
|
|
<doc xml:space="preserve">Returns the length of @seq. Note that this method is O(h) where `h' is the
|
|
height of the tree. It is thus more efficient to use g_sequence_is_empty()
|
|
when comparing the length to zero.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @seq</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="seq" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert_sorted" c:identifier="g_sequence_insert_sorted" version="2.14" introspectable="0">
|
|
<doc xml:space="preserve">Inserts @data into @seq using @cmp_func to determine the new
|
|
position. The sequence must already be sorted according to @cmp_func;
|
|
otherwise the new position of @data is undefined.
|
|
|
|
@cmp_func is called with two items of the @seq, and @cmp_data.
|
|
It should return 0 if the items are equal, a negative value
|
|
if the first item comes before the second, and a positive value
|
|
if the second item comes before the first.
|
|
|
|
Note that when adding a large amount of data to a #GSequence,
|
|
it is more efficient to do unsorted insertions and then call
|
|
g_sequence_sort() or g_sequence_sort_iter().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter pointing to the new item.</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="seq" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to insert</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="cmp_func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function used to compare items in the sequence</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @cmp_func.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert_sorted_iter" c:identifier="g_sequence_insert_sorted_iter" version="2.14" introspectable="0">
|
|
<doc xml:space="preserve">Like g_sequence_insert_sorted(), but uses
|
|
a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as
|
|
the compare function.
|
|
|
|
@iter_cmp is called with two iterators pointing into @seq.
|
|
It should return 0 if the iterators are equal, a negative
|
|
value if the first iterator comes before the second, and a
|
|
positive value if the second iterator comes before the first.
|
|
|
|
Note that when adding a large amount of data to a #GSequence,
|
|
it is more efficient to do unsorted insertions and then call
|
|
g_sequence_sort() or g_sequence_sort_iter().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter pointing to the new item</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="seq" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data for the new item</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="iter_cmp" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function used to compare iterators in the sequence</doc>
|
|
<type name="SequenceIterCompareFunc" c:type="GSequenceIterCompareFunc"/>
|
|
</parameter>
|
|
<parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @iter_cmp</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_empty" c:identifier="g_sequence_is_empty" version="2.48">
|
|
<doc xml:space="preserve">Returns %TRUE if the sequence contains zero items.
|
|
|
|
This function is functionally identical to checking the result of
|
|
g_sequence_get_length() being equal to zero. However this function is
|
|
implemented in O(1) running time.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the sequence is empty, otherwise %FALSE.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="seq" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="lookup" c:identifier="g_sequence_lookup" version="2.28" introspectable="0">
|
|
<doc xml:space="preserve">Returns an iterator pointing to the position of the first item found
|
|
equal to @data according to @cmp_func and @cmp_data. If more than one
|
|
item is equal, it is not guaranteed that it is the first which is
|
|
returned. In that case, you can use g_sequence_iter_next() and
|
|
g_sequence_iter_prev() to get others.
|
|
|
|
@cmp_func is called with two items of the @seq, and @cmp_data.
|
|
It should return 0 if the items are equal, a negative value if
|
|
the first item comes before the second, and a positive value if
|
|
the second item comes before the first.
|
|
|
|
This function will fail if the data contained in the sequence is
|
|
unsorted.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">an #GSequenceIter pointing to the position of the
|
|
first item found equal to @data according to @cmp_func and
|
|
@cmp_data, or %NULL if no such item exists</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="seq" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to look up</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="cmp_func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function used to compare items in the sequence</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @cmp_func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="lookup_iter" c:identifier="g_sequence_lookup_iter" version="2.28" introspectable="0">
|
|
<doc xml:space="preserve">Like g_sequence_lookup(), but uses a #GSequenceIterCompareFunc
|
|
instead of a #GCompareDataFunc as the compare function.
|
|
|
|
@iter_cmp is called with two iterators pointing into @seq.
|
|
It should return 0 if the iterators are equal, a negative value
|
|
if the first iterator comes before the second, and a positive
|
|
value if the second iterator comes before the first.
|
|
|
|
This function will fail if the data contained in the sequence is
|
|
unsorted.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">an #GSequenceIter pointing to the position of
|
|
the first item found equal to @data according to @iter_cmp
|
|
and @cmp_data, or %NULL if no such item exists</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="seq" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to look up</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="iter_cmp" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function used to compare iterators in the sequence</doc>
|
|
<type name="SequenceIterCompareFunc" c:type="GSequenceIterCompareFunc"/>
|
|
</parameter>
|
|
<parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @iter_cmp</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="prepend" c:identifier="g_sequence_prepend" version="2.14">
|
|
<doc xml:space="preserve">Adds a new item to the front of @seq</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">an iterator pointing to the new item</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="seq" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new item</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="search" c:identifier="g_sequence_search" version="2.14" introspectable="0">
|
|
<doc xml:space="preserve">Returns an iterator pointing to the position where @data would
|
|
be inserted according to @cmp_func and @cmp_data.
|
|
|
|
@cmp_func is called with two items of the @seq, and @cmp_data.
|
|
It should return 0 if the items are equal, a negative value if
|
|
the first item comes before the second, and a positive value if
|
|
the second item comes before the first.
|
|
|
|
If you are simply searching for an existing element of the sequence,
|
|
consider using g_sequence_lookup().
|
|
|
|
This function will fail if the data contained in the sequence is
|
|
unsorted.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">an #GSequenceIter pointing to the position where @data
|
|
would have been inserted according to @cmp_func and @cmp_data</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="seq" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data for the new item</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="cmp_func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function used to compare items in the sequence</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @cmp_func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="search_iter" c:identifier="g_sequence_search_iter" version="2.14" introspectable="0">
|
|
<doc xml:space="preserve">Like g_sequence_search(), but uses a #GSequenceIterCompareFunc
|
|
instead of a #GCompareDataFunc as the compare function.
|
|
|
|
@iter_cmp is called with two iterators pointing into @seq.
|
|
It should return 0 if the iterators are equal, a negative value
|
|
if the first iterator comes before the second, and a positive
|
|
value if the second iterator comes before the first.
|
|
|
|
If you are simply searching for an existing element of the sequence,
|
|
consider using g_sequence_lookup_iter().
|
|
|
|
This function will fail if the data contained in the sequence is
|
|
unsorted.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter pointing to the position in @seq
|
|
where @data would have been inserted according to @iter_cmp
|
|
and @cmp_data</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="seq" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data for the new item</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="iter_cmp" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function used to compare iterators in the sequence</doc>
|
|
<type name="SequenceIterCompareFunc" c:type="GSequenceIterCompareFunc"/>
|
|
</parameter>
|
|
<parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @iter_cmp</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="sort" c:identifier="g_sequence_sort" version="2.14" introspectable="0">
|
|
<doc xml:space="preserve">Sorts @seq using @cmp_func.
|
|
|
|
@cmp_func is passed two items of @seq and should
|
|
return 0 if they are equal, a negative value if the
|
|
first comes before the second, and a positive value
|
|
if the second comes before the first.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="seq" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</instance-parameter>
|
|
<parameter name="cmp_func" transfer-ownership="none" closure="1">
|
|
<doc xml:space="preserve">the function used to sort the sequence</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @cmp_func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="sort_iter" c:identifier="g_sequence_sort_iter" version="2.14" introspectable="0">
|
|
<doc xml:space="preserve">Like g_sequence_sort(), but uses a #GSequenceIterCompareFunc instead
|
|
of a #GCompareDataFunc as the compare function
|
|
|
|
@cmp_func is called with two iterators pointing into @seq. It should
|
|
return 0 if the iterators are equal, a negative value if the first
|
|
iterator comes before the second, and a positive value if the second
|
|
iterator comes before the first.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="seq" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</instance-parameter>
|
|
<parameter name="cmp_func" transfer-ownership="none" closure="1">
|
|
<doc xml:space="preserve">the function used to compare iterators in the sequence</doc>
|
|
<type name="SequenceIterCompareFunc" c:type="GSequenceIterCompareFunc"/>
|
|
</parameter>
|
|
<parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @cmp_func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="foreach_range" c:identifier="g_sequence_foreach_range" version="2.14" introspectable="0">
|
|
<doc xml:space="preserve">Calls @func for each item in the range (@begin, @end) passing
|
|
@user_data to the function. @func must not modify the sequence
|
|
itself.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="begin" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="end" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="3">
|
|
<doc xml:space="preserve">a #GFunc</doc>
|
|
<type name="Func" c:type="GFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="get" c:identifier="g_sequence_get" version="2.14">
|
|
<doc xml:space="preserve">Returns the data that @iter points to.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the data that @iter points to</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="insert_before" c:identifier="g_sequence_insert_before" version="2.14">
|
|
<doc xml:space="preserve">Inserts a new item just before the item pointed to by @iter.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">an iterator pointing to the new item</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new item</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="move" c:identifier="g_sequence_move" version="2.14">
|
|
<doc xml:space="preserve">Moves the item pointed to by @src to the position indicated by @dest.
|
|
After calling this function @dest will point to the position immediately
|
|
after @src. It is allowed for @src and @dest to point into different
|
|
sequences.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="src" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter pointing to the item to move</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="dest" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter pointing to the position to which
|
|
the item is moved</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="move_range" c:identifier="g_sequence_move_range" version="2.14">
|
|
<doc xml:space="preserve">Inserts the (@begin, @end) range at the destination pointed to by @dest.
|
|
The @begin and @end iters must point into the same sequence. It is
|
|
allowed for @dest to point to a different sequence than the one pointed
|
|
into by @begin and @end.
|
|
|
|
If @dest is %NULL, the range indicated by @begin and @end is
|
|
removed from the sequence. If @dest points to a place within
|
|
the (@begin, @end) range, the range does not move.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dest" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="begin" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="end" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="new" c:identifier="g_sequence_new" version="2.14" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new GSequence. The @data_destroy function, if non-%NULL will
|
|
be called on all items when the sequence is destroyed and on items that
|
|
are removed from the sequence.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GSequence</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="data_destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">a #GDestroyNotify function, or %NULL</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="range_get_midpoint" c:identifier="g_sequence_range_get_midpoint" version="2.14">
|
|
<doc xml:space="preserve">Finds an iterator somewhere in the range (@begin, @end). This
|
|
iterator will be close to the middle of the range, but is not
|
|
guaranteed to be exactly in the middle.
|
|
|
|
The @begin and @end iterators must both point to the same sequence
|
|
and @begin must come before or be equal to @end in the sequence.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter pointing somewhere in the
|
|
(@begin, @end) range</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="begin" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="end" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove" c:identifier="g_sequence_remove" version="2.14">
|
|
<doc xml:space="preserve">Removes the item pointed to by @iter. It is an error to pass the
|
|
end iterator to this function.
|
|
|
|
If the sequence has a data destroy function associated with it, this
|
|
function is called on the data for the removed item.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_range" c:identifier="g_sequence_remove_range" version="2.14">
|
|
<doc xml:space="preserve">Removes all items in the (@begin, @end) range.
|
|
|
|
If the sequence has a data destroy function associated with it, this
|
|
function is called on the data for the removed items.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="begin" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="end" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="set" c:identifier="g_sequence_set" version="2.14">
|
|
<doc xml:space="preserve">Changes the data for the item pointed to by @iter to be @data. If
|
|
the sequence has a data destroy function associated with it, that
|
|
function is called on the existing data that @iter pointed to.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">new data for the item</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sort_changed" c:identifier="g_sequence_sort_changed" version="2.14" introspectable="0">
|
|
<doc xml:space="preserve">Moves the data pointed to by @iter to a new position as indicated by
|
|
@cmp_func. This
|
|
function should be called for items in a sequence already sorted according
|
|
to @cmp_func whenever some aspect of an item changes so that @cmp_func
|
|
may return different values for that item.
|
|
|
|
@cmp_func is called with two items of the @seq, and @cmp_data.
|
|
It should return 0 if the items are equal, a negative value if
|
|
the first item comes before the second, and a positive value if
|
|
the second item comes before the first.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="cmp_func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function used to compare items in the sequence</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @cmp_func.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sort_changed_iter" c:identifier="g_sequence_sort_changed_iter" version="2.14" introspectable="0">
|
|
<doc xml:space="preserve">Like g_sequence_sort_changed(), but uses
|
|
a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as
|
|
the compare function.
|
|
|
|
@iter_cmp is called with two iterators pointing into the #GSequence that
|
|
@iter points into. It should
|
|
return 0 if the iterators are equal, a negative value if the first
|
|
iterator comes before the second, and a positive value if the second
|
|
iterator comes before the first.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="iter_cmp" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function used to compare iterators in the sequence</doc>
|
|
<type name="SequenceIterCompareFunc" c:type="GSequenceIterCompareFunc"/>
|
|
</parameter>
|
|
<parameter name="cmp_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @cmp_func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="swap" c:identifier="g_sequence_swap" version="2.14">
|
|
<doc xml:space="preserve">Swaps the items pointed to by @a and @b. It is allowed for @a and @b
|
|
to point into difference sequences.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="a" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="b" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<record name="SequenceIter" c:type="GSequenceIter" disguised="1">
|
|
<doc xml:space="preserve">The #GSequenceIter struct is an opaque data type representing an
|
|
iterator pointing into a #GSequence.</doc>
|
|
<method name="compare" c:identifier="g_sequence_iter_compare" version="2.14">
|
|
<doc xml:space="preserve">Returns a negative number if @a comes before @b, 0 if they are equal,
|
|
and a positive number if @a comes after @b.
|
|
|
|
The @a and @b iterators must point into the same sequence.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a negative number if @a comes before @b, 0 if they are
|
|
equal, and a positive number if @a comes after @b</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="a" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</instance-parameter>
|
|
<parameter name="b" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_position" c:identifier="g_sequence_iter_get_position" version="2.14">
|
|
<doc xml:space="preserve">Returns the position of @iter</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the position of @iter</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_sequence" c:identifier="g_sequence_iter_get_sequence" version="2.14">
|
|
<doc xml:space="preserve">Returns the #GSequence that @iter points into.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GSequence that @iter points into</doc>
|
|
<type name="Sequence" c:type="GSequence*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_begin" c:identifier="g_sequence_iter_is_begin" version="2.14">
|
|
<doc xml:space="preserve">Returns whether @iter is the begin iterator</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">whether @iter is the begin iterator</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_end" c:identifier="g_sequence_iter_is_end" version="2.14">
|
|
<doc xml:space="preserve">Returns whether @iter is the end iterator</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">Whether @iter is the end iterator</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="move" c:identifier="g_sequence_iter_move" version="2.14">
|
|
<doc xml:space="preserve">Returns the #GSequenceIter which is @delta positions away from @iter.
|
|
If @iter is closer than -@delta positions to the beginning of the sequence,
|
|
the begin iterator is returned. If @iter is closer than @delta positions
|
|
to the end of the sequence, the end iterator is returned.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter which is @delta positions away from @iter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</instance-parameter>
|
|
<parameter name="delta" transfer-ownership="none">
|
|
<doc xml:space="preserve">A positive or negative number indicating how many positions away
|
|
from @iter the returned #GSequenceIter will be</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="next" c:identifier="g_sequence_iter_next" version="2.14">
|
|
<doc xml:space="preserve">Returns an iterator pointing to the next position after @iter.
|
|
If @iter is the end iterator, the end iterator is returned.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter pointing to the next position after @iter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="prev" c:identifier="g_sequence_iter_prev" version="2.14">
|
|
<doc xml:space="preserve">Returns an iterator pointing to the previous position before @iter.
|
|
If @iter is the begin iterator, the begin iterator is returned.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter pointing to the previous position
|
|
before @iter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<callback name="SequenceIterCompareFunc" c:type="GSequenceIterCompareFunc">
|
|
<doc xml:space="preserve">A #GSequenceIterCompareFunc is a function used to compare iterators.
|
|
It must return zero if the iterators compare equal, a negative value
|
|
if @a comes before @b, and a positive value if @b comes before @a.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">zero if the iterators are equal, a negative value if @a
|
|
comes before @b, and a positive value if @b comes before @a.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="a" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="b" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<enumeration name="ShellError" c:type="GShellError" glib:error-domain="g-shell-error-quark">
|
|
<doc xml:space="preserve">Error codes returned by shell functions.</doc>
|
|
<member name="bad_quoting" value="0" c:identifier="G_SHELL_ERROR_BAD_QUOTING">
|
|
<doc xml:space="preserve">Mismatched or otherwise mangled quoting.</doc>
|
|
</member>
|
|
<member name="empty_string" value="1" c:identifier="G_SHELL_ERROR_EMPTY_STRING">
|
|
<doc xml:space="preserve">String to be parsed was empty.</doc>
|
|
</member>
|
|
<member name="failed" value="2" c:identifier="G_SHELL_ERROR_FAILED">
|
|
<doc xml:space="preserve">Some other error.</doc>
|
|
</member>
|
|
</enumeration>
|
|
<enumeration name="SliceConfig" c:type="GSliceConfig">
|
|
<member name="always_malloc" value="1" c:identifier="G_SLICE_CONFIG_ALWAYS_MALLOC">
|
|
</member>
|
|
<member name="bypass_magazines" value="2" c:identifier="G_SLICE_CONFIG_BYPASS_MAGAZINES">
|
|
</member>
|
|
<member name="working_set_msecs" value="3" c:identifier="G_SLICE_CONFIG_WORKING_SET_MSECS">
|
|
</member>
|
|
<member name="color_increment" value="4" c:identifier="G_SLICE_CONFIG_COLOR_INCREMENT">
|
|
</member>
|
|
<member name="chunk_sizes" value="5" c:identifier="G_SLICE_CONFIG_CHUNK_SIZES">
|
|
</member>
|
|
<member name="contention_counter" value="6" c:identifier="G_SLICE_CONFIG_CONTENTION_COUNTER">
|
|
</member>
|
|
</enumeration>
|
|
<record name="Source" c:type="GSource" glib:type-name="GSource" glib:get-type="g_source_get_type" c:symbol-prefix="source">
|
|
<doc xml:space="preserve">The `GSource` struct is an opaque data type
|
|
representing an event source.</doc>
|
|
<field name="callback_data" readable="0" private="1">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="callback_funcs" readable="0" private="1">
|
|
<type name="SourceCallbackFuncs" c:type="GSourceCallbackFuncs*"/>
|
|
</field>
|
|
<field name="source_funcs" readable="0" private="1">
|
|
<type name="SourceFuncs" c:type="const GSourceFuncs*"/>
|
|
</field>
|
|
<field name="ref_count" readable="0" private="1">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="context" readable="0" private="1">
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</field>
|
|
<field name="priority" readable="0" private="1">
|
|
<type name="gint" c:type="gint"/>
|
|
</field>
|
|
<field name="flags" readable="0" private="1">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="source_id" readable="0" private="1">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="poll_fds" readable="0" private="1">
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</field>
|
|
<field name="prev" readable="0" private="1">
|
|
<type name="Source" c:type="GSource*"/>
|
|
</field>
|
|
<field name="next" readable="0" private="1">
|
|
<type name="Source" c:type="GSource*"/>
|
|
</field>
|
|
<field name="name" readable="0" private="1">
|
|
<type name="utf8" c:type="char*"/>
|
|
</field>
|
|
<field name="priv" readable="0" private="1">
|
|
<type name="SourcePrivate" c:type="GSourcePrivate*"/>
|
|
</field>
|
|
<constructor name="new" c:identifier="g_source_new">
|
|
<doc xml:space="preserve">Creates a new #GSource structure. The size is specified to
|
|
allow creating structures derived from #GSource that contain
|
|
additional data. The size passed in must be at least
|
|
`sizeof (GSource)`.
|
|
|
|
The source will not initially be associated with any #GMainContext
|
|
and must be added to one with g_source_attach() before it will be
|
|
executed.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the newly-created #GSource.</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="source_funcs" transfer-ownership="none">
|
|
<doc xml:space="preserve">structure containing functions that implement
|
|
the sources behavior.</doc>
|
|
<type name="SourceFuncs" c:type="GSourceFuncs*"/>
|
|
</parameter>
|
|
<parameter name="struct_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">size of the #GSource structure to create.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<method name="add_child_source" c:identifier="g_source_add_child_source" version="2.28">
|
|
<doc xml:space="preserve">Adds @child_source to @source as a "polled" source; when @source is
|
|
added to a #GMainContext, @child_source will be automatically added
|
|
with the same priority, when @child_source is triggered, it will
|
|
cause @source to dispatch (in addition to calling its own
|
|
callback), and when @source is destroyed, it will destroy
|
|
@child_source as well. (@source will also still be dispatched if
|
|
its own prepare/check functions indicate that it is ready.)
|
|
|
|
If you don't need @child_source to do anything on its own when it
|
|
triggers, you can call g_source_set_dummy_callback() on it to set a
|
|
callback that does nothing (except return %TRUE if appropriate).
|
|
|
|
@source will hold a reference on @child_source while @child_source
|
|
is attached to it.
|
|
|
|
This API is only intended to be used by implementations of #GSource.
|
|
Do not call this API on a #GSource that you did not create.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="child_source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a second #GSource that @source should "poll"</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_poll" c:identifier="g_source_add_poll">
|
|
<doc xml:space="preserve">Adds a file descriptor to the set of file descriptors polled for
|
|
this source. This is usually combined with g_source_new() to add an
|
|
event source. The event source's check function will typically test
|
|
the @revents field in the #GPollFD struct and return %TRUE if events need
|
|
to be processed.
|
|
|
|
This API is only intended to be used by implementations of #GSource.
|
|
Do not call this API on a #GSource that you did not create.
|
|
|
|
Using this API forces the linear scanning of event sources on each
|
|
main loop iteration. Newly-written event sources should try to use
|
|
g_source_add_unix_fd() instead of this API.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPollFD structure holding information about a file
|
|
descriptor to watch.</doc>
|
|
<type name="PollFD" c:type="GPollFD*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_unix_fd" c:identifier="g_source_add_unix_fd" version="2.36">
|
|
<doc xml:space="preserve">Monitors @fd for the IO events in @events.
|
|
|
|
The tag returned by this function can be used to remove or modify the
|
|
monitoring of the fd using g_source_remove_unix_fd() or
|
|
g_source_modify_unix_fd().
|
|
|
|
It is not necessary to remove the fd before destroying the source; it
|
|
will be cleaned up automatically.
|
|
|
|
This API is only intended to be used by implementations of #GSource.
|
|
Do not call this API on a #GSource that you did not create.
|
|
|
|
As the name suggests, this function is not available on Windows.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">an opaque tag</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">the fd to monitor</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="events" transfer-ownership="none">
|
|
<doc xml:space="preserve">an event mask</doc>
|
|
<type name="IOCondition" c:type="GIOCondition"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="attach" c:identifier="g_source_attach">
|
|
<doc xml:space="preserve">Adds a #GSource to a @context so that it will be executed within
|
|
that context. Remove it by calling g_source_destroy().
|
|
|
|
This function is safe to call from any thread, regardless of which thread
|
|
the @context is running in.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the ID (greater than 0) for the source within the
|
|
#GMainContext.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="context" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GMainContext (if %NULL, the default context will be used)</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="destroy" c:identifier="g_source_destroy">
|
|
<doc xml:space="preserve">Removes a source from its #GMainContext, if any, and mark it as
|
|
destroyed. The source cannot be subsequently added to another
|
|
context. It is safe to call this on sources which have already been
|
|
removed from their context.
|
|
|
|
This does not unref the #GSource: if you still hold a reference, use
|
|
g_source_unref() to drop it.
|
|
|
|
This function is safe to call from any thread, regardless of which thread
|
|
the #GMainContext is running in.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_can_recurse" c:identifier="g_source_get_can_recurse">
|
|
<doc xml:space="preserve">Checks whether a source is allowed to be called recursively.
|
|
see g_source_set_can_recurse().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">whether recursion is allowed.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_context" c:identifier="g_source_get_context">
|
|
<doc xml:space="preserve">Gets the #GMainContext with which the source is associated.
|
|
|
|
You can call this on a source that has been destroyed, provided
|
|
that the #GMainContext it was attached to still exists (in which
|
|
case it will return that #GMainContext). In particular, you can
|
|
always call this function on the source returned from
|
|
g_main_current_source(). But calling this function on a source
|
|
whose #GMainContext has been destroyed is an error.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the #GMainContext with which the
|
|
source is associated, or %NULL if the context has not
|
|
yet been added to a source.</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_current_time" c:identifier="g_source_get_current_time" deprecated="1" deprecated-version="2.28">
|
|
<doc xml:space="preserve">This function ignores @source and is otherwise the same as
|
|
g_get_current_time().</doc>
|
|
<doc-deprecated xml:space="preserve">use g_source_get_time() instead</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="timeval" transfer-ownership="none">
|
|
<doc xml:space="preserve">#GTimeVal structure in which to store current time.</doc>
|
|
<type name="TimeVal" c:type="GTimeVal*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_id" c:identifier="g_source_get_id">
|
|
<doc xml:space="preserve">Returns the numeric ID for a particular source. The ID of a source
|
|
is a positive integer which is unique within a particular main loop
|
|
context. The reverse
|
|
mapping from ID to source is done by g_main_context_find_source_by_id().
|
|
|
|
You can only call this function while the source is associated to a
|
|
#GMainContext instance; calling this function before g_source_attach()
|
|
or after g_source_destroy() yields undefined behavior. The ID returned
|
|
is unique within the #GMainContext instance passed to g_source_attach().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the ID (greater than 0) for the source</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_name" c:identifier="g_source_get_name" version="2.26">
|
|
<doc xml:space="preserve">Gets a name for the source, used in debugging and profiling. The
|
|
name may be #NULL if it has never been set with g_source_set_name().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the name of the source</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_priority" c:identifier="g_source_get_priority">
|
|
<doc xml:space="preserve">Gets the priority of a source.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the priority of the source</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_ready_time" c:identifier="g_source_get_ready_time">
|
|
<doc xml:space="preserve">Gets the "ready time" of @source, as set by
|
|
g_source_set_ready_time().
|
|
|
|
Any time before the current monotonic time (including 0) is an
|
|
indication that the source will fire immediately.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the monotonic ready time, -1 for "never"</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_time" c:identifier="g_source_get_time" version="2.28">
|
|
<doc xml:space="preserve">Gets the time to be used when checking this source. The advantage of
|
|
calling this function over calling g_get_monotonic_time() directly is
|
|
that when checking multiple sources, GLib can cache a single value
|
|
instead of having to repeatedly get the system monotonic time.
|
|
|
|
The time here is the system monotonic time, if available, or some
|
|
other reasonable alternative otherwise. See g_get_monotonic_time().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the monotonic time in microseconds</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_destroyed" c:identifier="g_source_is_destroyed" version="2.12">
|
|
<doc xml:space="preserve">Returns whether @source has been destroyed.
|
|
|
|
This is important when you operate upon your objects
|
|
from within idle handlers, but may have freed the object
|
|
before the dispatch of your idle handler.
|
|
|
|
|[<!-- language="C" -->
|
|
static gboolean
|
|
idle_callback (gpointer data)
|
|
{
|
|
SomeWidget *self = data;
|
|
|
|
GDK_THREADS_ENTER ();
|
|
// do stuff with self
|
|
self->idle_id = 0;
|
|
GDK_THREADS_LEAVE ();
|
|
|
|
return G_SOURCE_REMOVE;
|
|
}
|
|
|
|
static void
|
|
some_widget_do_stuff_later (SomeWidget *self)
|
|
{
|
|
self->idle_id = g_idle_add (idle_callback, self);
|
|
}
|
|
|
|
static void
|
|
some_widget_finalize (GObject *object)
|
|
{
|
|
SomeWidget *self = SOME_WIDGET (object);
|
|
|
|
if (self->idle_id)
|
|
g_source_remove (self->idle_id);
|
|
|
|
G_OBJECT_CLASS (parent_class)->finalize (object);
|
|
}
|
|
]|
|
|
|
|
This will fail in a multi-threaded application if the
|
|
widget is destroyed before the idle handler fires due
|
|
to the use after free in the callback. A solution, to
|
|
this particular problem, is to check to if the source
|
|
has already been destroy within the callback.
|
|
|
|
|[<!-- language="C" -->
|
|
static gboolean
|
|
idle_callback (gpointer data)
|
|
{
|
|
SomeWidget *self = data;
|
|
|
|
GDK_THREADS_ENTER ();
|
|
if (!g_source_is_destroyed (g_main_current_source ()))
|
|
{
|
|
// do stuff with self
|
|
}
|
|
GDK_THREADS_LEAVE ();
|
|
|
|
return FALSE;
|
|
}
|
|
]|
|
|
|
|
Calls to this function from a thread other than the one acquired by the
|
|
#GMainContext the #GSource is attached to are typically redundant, as the
|
|
source could be destroyed immediately after this function returns. However,
|
|
once a source is destroyed it cannot be un-destroyed, so this function can be
|
|
used for opportunistic checks from any thread.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the source has been destroyed</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="modify_unix_fd" c:identifier="g_source_modify_unix_fd" version="2.36">
|
|
<doc xml:space="preserve">Updates the event mask to watch for the fd identified by @tag.
|
|
|
|
@tag is the tag returned from g_source_add_unix_fd().
|
|
|
|
If you want to remove a fd, don't set its event mask to zero.
|
|
Instead, call g_source_remove_unix_fd().
|
|
|
|
This API is only intended to be used by implementations of #GSource.
|
|
Do not call this API on a #GSource that you did not create.
|
|
|
|
As the name suggests, this function is not available on Windows.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="tag" transfer-ownership="none">
|
|
<doc xml:space="preserve">the tag from g_source_add_unix_fd()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="new_events" transfer-ownership="none">
|
|
<doc xml:space="preserve">the new event mask to watch</doc>
|
|
<type name="IOCondition" c:type="GIOCondition"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="query_unix_fd" c:identifier="g_source_query_unix_fd" version="2.36">
|
|
<doc xml:space="preserve">Queries the events reported for the fd corresponding to @tag on
|
|
@source during the last poll.
|
|
|
|
The return value of this function is only defined when the function
|
|
is called from the check or dispatch functions for @source.
|
|
|
|
This API is only intended to be used by implementations of #GSource.
|
|
Do not call this API on a #GSource that you did not create.
|
|
|
|
As the name suggests, this function is not available on Windows.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the conditions reported on the fd</doc>
|
|
<type name="IOCondition" c:type="GIOCondition"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="tag" transfer-ownership="none">
|
|
<doc xml:space="preserve">the tag from g_source_add_unix_fd()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_source_ref">
|
|
<doc xml:space="preserve">Increases the reference count on a source by one.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">@source</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="remove_child_source" c:identifier="g_source_remove_child_source" version="2.28">
|
|
<doc xml:space="preserve">Detaches @child_source from @source and destroys it.
|
|
|
|
This API is only intended to be used by implementations of #GSource.
|
|
Do not call this API on a #GSource that you did not create.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="child_source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource previously passed to
|
|
g_source_add_child_source().</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="remove_poll" c:identifier="g_source_remove_poll">
|
|
<doc xml:space="preserve">Removes a file descriptor from the set of file descriptors polled for
|
|
this source.
|
|
|
|
This API is only intended to be used by implementations of #GSource.
|
|
Do not call this API on a #GSource that you did not create.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPollFD structure previously passed to g_source_add_poll().</doc>
|
|
<type name="PollFD" c:type="GPollFD*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="remove_unix_fd" c:identifier="g_source_remove_unix_fd" version="2.36">
|
|
<doc xml:space="preserve">Reverses the effect of a previous call to g_source_add_unix_fd().
|
|
|
|
You only need to call this if you want to remove an fd from being
|
|
watched while keeping the same source around. In the normal case you
|
|
will just want to destroy the source.
|
|
|
|
This API is only intended to be used by implementations of #GSource.
|
|
Do not call this API on a #GSource that you did not create.
|
|
|
|
As the name suggests, this function is not available on Windows.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="tag" transfer-ownership="none">
|
|
<doc xml:space="preserve">the tag from g_source_add_unix_fd()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_callback" c:identifier="g_source_set_callback">
|
|
<doc xml:space="preserve">Sets the callback function for a source. The callback for a source is
|
|
called from the source's dispatch function.
|
|
|
|
The exact type of @func depends on the type of source; ie. you
|
|
should not count on @func being called with @data as its first
|
|
parameter. Cast @func with G_SOURCE_FUNC() to avoid warnings about
|
|
incompatible function types.
|
|
|
|
See [memory management of sources][mainloop-memory-management] for details
|
|
on how to handle memory management of @data.
|
|
|
|
Typically, you won't use this function. Instead use functions specific
|
|
to the type of source you are using, such as g_idle_add() or g_timeout_add().
|
|
|
|
It is safe to call this function multiple times on a source which has already
|
|
been attached to a context. The changes will take effect for the next time
|
|
the source is dispatched after this call returns.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">the source</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="func" transfer-ownership="none" scope="notified" closure="1" destroy="2">
|
|
<doc xml:space="preserve">a callback function</doc>
|
|
<type name="SourceFunc" c:type="GSourceFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data to pass to callback function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">a function to call when @data is no longer in use, or %NULL.</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_callback_indirect" c:identifier="g_source_set_callback_indirect">
|
|
<doc xml:space="preserve">Sets the callback function storing the data as a refcounted callback
|
|
"object". This is used internally. Note that calling
|
|
g_source_set_callback_indirect() assumes
|
|
an initial reference count on @callback_data, and thus
|
|
@callback_funcs->unref will eventually be called once more
|
|
than @callback_funcs->ref.
|
|
|
|
It is safe to call this function multiple times on a source which has already
|
|
been attached to a context. The changes will take effect for the next time
|
|
the source is dispatched after this call returns.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">the source</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="callback_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">pointer to callback data "object"</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="callback_funcs" transfer-ownership="none">
|
|
<doc xml:space="preserve">functions for reference counting @callback_data
|
|
and getting the callback and data</doc>
|
|
<type name="SourceCallbackFuncs" c:type="GSourceCallbackFuncs*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_can_recurse" c:identifier="g_source_set_can_recurse">
|
|
<doc xml:space="preserve">Sets whether a source can be called recursively. If @can_recurse is
|
|
%TRUE, then while the source is being dispatched then this source
|
|
will be processed normally. Otherwise, all processing of this
|
|
source is blocked until the dispatch function returns.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="can_recurse" transfer-ownership="none">
|
|
<doc xml:space="preserve">whether recursion is allowed for this source</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_dispose_function" c:identifier="g_source_set_dispose_function" version="2.64" introspectable="0">
|
|
<doc xml:space="preserve">Set @dispose as dispose function on @source. @dispose will be called once
|
|
the reference count of @source reaches 0 but before any of the state of the
|
|
source is freed, especially before the finalize function is called.
|
|
|
|
This means that at this point @source is still a valid #GSource and it is
|
|
allow for the reference count to increase again until @dispose returns.
|
|
|
|
The dispose function can be used to clear any "weak" references to the
|
|
@source in other data structures in a thread-safe way where it is possible
|
|
for another thread to increase the reference count of @source again while
|
|
it is being freed.
|
|
|
|
The finalize function can not be used for this purpose as at that point
|
|
@source is already partially freed and not valid anymore.
|
|
|
|
This should only ever be called from #GSource implementations.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GSource to set the dispose function on</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="dispose" transfer-ownership="none">
|
|
<doc xml:space="preserve">#GSourceDisposeFunc to set on the source</doc>
|
|
<type name="SourceDisposeFunc" c:type="GSourceDisposeFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_funcs" c:identifier="g_source_set_funcs" version="2.12">
|
|
<doc xml:space="preserve">Sets the source functions (can be used to override
|
|
default implementations) of an unattached source.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="funcs" transfer-ownership="none">
|
|
<doc xml:space="preserve">the new #GSourceFuncs</doc>
|
|
<type name="SourceFuncs" c:type="GSourceFuncs*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_name" c:identifier="g_source_set_name" version="2.26">
|
|
<doc xml:space="preserve">Sets a name for the source, used in debugging and profiling.
|
|
The name defaults to #NULL.
|
|
|
|
The source name should describe in a human-readable way
|
|
what the source does. For example, "X11 event queue"
|
|
or "GTK+ repaint idle handler" or whatever it is.
|
|
|
|
It is permitted to call this function multiple times, but is not
|
|
recommended due to the potential performance impact. For example,
|
|
one could change the name in the "check" function of a #GSourceFuncs
|
|
to include details like the event type in the source name.
|
|
|
|
Use caution if changing the name while another thread may be
|
|
accessing it with g_source_get_name(); that function does not copy
|
|
the value, and changing the value will free it while the other thread
|
|
may be attempting to use it.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="name" transfer-ownership="none">
|
|
<doc xml:space="preserve">debug name for the source</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_priority" c:identifier="g_source_set_priority">
|
|
<doc xml:space="preserve">Sets the priority of a source. While the main loop is being run, a
|
|
source will be dispatched if it is ready to be dispatched and no
|
|
sources at a higher (numerically smaller) priority are ready to be
|
|
dispatched.
|
|
|
|
A child source always has the same priority as its parent. It is not
|
|
permitted to change the priority of a source once it has been added
|
|
as a child of another source.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="priority" transfer-ownership="none">
|
|
<doc xml:space="preserve">the new priority.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_ready_time" c:identifier="g_source_set_ready_time" version="2.36">
|
|
<doc xml:space="preserve">Sets a #GSource to be dispatched when the given monotonic time is
|
|
reached (or passed). If the monotonic time is in the past (as it
|
|
always will be if @ready_time is 0) then the source will be
|
|
dispatched immediately.
|
|
|
|
If @ready_time is -1 then the source is never woken up on the basis
|
|
of the passage of time.
|
|
|
|
Dispatching the source does not reset the ready time. You should do
|
|
so yourself, from the source dispatch function.
|
|
|
|
Note that if you have a pair of sources where the ready time of one
|
|
suggests that it will be delivered first but the priority for the
|
|
other suggests that it would be delivered first, and the ready time
|
|
for both sources is reached during the same main context iteration,
|
|
then the order of dispatch is undefined.
|
|
|
|
It is a no-op to call this function on a #GSource which has already been
|
|
destroyed with g_source_destroy().
|
|
|
|
This API is only intended to be used by implementations of #GSource.
|
|
Do not call this API on a #GSource that you did not create.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
<parameter name="ready_time" transfer-ownership="none">
|
|
<doc xml:space="preserve">the monotonic time at which the source will be ready,
|
|
0 for "immediately", -1 for "never"</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_source_unref">
|
|
<doc xml:space="preserve">Decreases the reference count of a source by one. If the
|
|
resulting reference count is zero the source and associated
|
|
memory will be destroyed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="remove" c:identifier="g_source_remove">
|
|
<doc xml:space="preserve">Removes the source with the given ID from the default main context. You must
|
|
use g_source_destroy() for sources added to a non-default main context.
|
|
|
|
The ID of a #GSource is given by g_source_get_id(), or will be
|
|
returned by the functions g_source_attach(), g_idle_add(),
|
|
g_idle_add_full(), g_timeout_add(), g_timeout_add_full(),
|
|
g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and
|
|
g_io_add_watch_full().
|
|
|
|
It is a programmer error to attempt to remove a non-existent source.
|
|
|
|
More specifically: source IDs can be reissued after a source has been
|
|
destroyed and therefore it is never valid to use this function with a
|
|
source ID which may have already been removed. An example is when
|
|
scheduling an idle to run in another thread with g_idle_add(): the
|
|
idle may already have run and been removed by the time this function
|
|
is called on its (now invalid) source ID. This source ID may have
|
|
been reissued, leading to the operation being performed against the
|
|
wrong source.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">For historical reasons, this function always returns %TRUE</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="tag" transfer-ownership="none">
|
|
<doc xml:space="preserve">the ID of the source to remove.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_by_funcs_user_data" c:identifier="g_source_remove_by_funcs_user_data">
|
|
<doc xml:space="preserve">Removes a source from the default main loop context given the
|
|
source functions and user data. If multiple sources exist with the
|
|
same source functions and user data, only one will be destroyed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a source was found and removed.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="funcs" transfer-ownership="none">
|
|
<doc xml:space="preserve">The @source_funcs passed to g_source_new()</doc>
|
|
<type name="SourceFuncs" c:type="GSourceFuncs*"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the user data for the callback</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="remove_by_user_data" c:identifier="g_source_remove_by_user_data">
|
|
<doc xml:space="preserve">Removes a source from the default main loop context given the user
|
|
data for the callback. If multiple sources exist with the same user
|
|
data, only one will be destroyed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a source was found and removed.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the user_data for the callback.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="set_name_by_id" c:identifier="g_source_set_name_by_id" version="2.26">
|
|
<doc xml:space="preserve">Sets the name of a source using its ID.
|
|
|
|
This is a convenience utility to set source names from the return
|
|
value of g_idle_add(), g_timeout_add(), etc.
|
|
|
|
It is a programmer error to attempt to set the name of a non-existent
|
|
source.
|
|
|
|
More specifically: source IDs can be reissued after a source has been
|
|
destroyed and therefore it is never valid to use this function with a
|
|
source ID which may have already been removed. An example is when
|
|
scheduling an idle to run in another thread with g_idle_add(): the
|
|
idle may already have run and been removed by the time this function
|
|
is called on its (now invalid) source ID. This source ID may have
|
|
been reissued, leading to the operation being performed against the
|
|
wrong source.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="tag" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource ID</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="name" transfer-ownership="none">
|
|
<doc xml:space="preserve">debug name for the source</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<record name="SourceCallbackFuncs" c:type="GSourceCallbackFuncs">
|
|
<doc xml:space="preserve">The `GSourceCallbackFuncs` struct contains
|
|
functions for managing callback objects.</doc>
|
|
<field name="ref">
|
|
<callback name="ref">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="cb_data" transfer-ownership="none">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="unref">
|
|
<callback name="unref">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="cb_data" transfer-ownership="none">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="get" introspectable="0">
|
|
<callback name="get" introspectable="0">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="cb_data" transfer-ownership="none">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="source" transfer-ownership="none">
|
|
<type name="Source" c:type="GSource*"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="3">
|
|
<type name="SourceFunc" c:type="GSourceFunc*"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
</record>
|
|
<callback name="SourceDisposeFunc" c:type="GSourceDisposeFunc" version="2.64">
|
|
<doc xml:space="preserve">Dispose function for @source. See g_source_set_dispose_function() for
|
|
details.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">#GSource that is currently being disposed</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<callback name="SourceDummyMarshal" c:type="GSourceDummyMarshal">
|
|
<doc xml:space="preserve">This is just a placeholder for #GClosureMarshal,
|
|
which cannot be used here for dependency reasons.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
</callback>
|
|
<callback name="SourceFunc" c:type="GSourceFunc">
|
|
<doc xml:space="preserve">Specifies the type of function passed to g_timeout_add(),
|
|
g_timeout_add_full(), g_idle_add(), and g_idle_add_full().
|
|
|
|
When calling g_source_set_callback(), you may need to cast a function of a
|
|
different type to this type. Use G_SOURCE_FUNC() to avoid warnings about
|
|
incompatible function types.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%FALSE if the source should be removed. #G_SOURCE_CONTINUE and
|
|
#G_SOURCE_REMOVE are more memorable names for the return value.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="0">
|
|
<doc xml:space="preserve">data passed to the function, set when the source was
|
|
created with one of the above functions</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<record name="SourceFuncs" c:type="GSourceFuncs">
|
|
<doc xml:space="preserve">The `GSourceFuncs` struct contains a table of
|
|
functions used to handle event sources in a generic manner.
|
|
|
|
For idle sources, the prepare and check functions always return %TRUE
|
|
to indicate that the source is always ready to be processed. The prepare
|
|
function also returns a timeout value of 0 to ensure that the poll() call
|
|
doesn't block (since that would be time wasted which could have been spent
|
|
running the idle function).
|
|
|
|
For timeout sources, the prepare and check functions both return %TRUE
|
|
if the timeout interval has expired. The prepare function also returns
|
|
a timeout value to ensure that the poll() call doesn't block too long
|
|
and miss the next timeout.
|
|
|
|
For file descriptor sources, the prepare function typically returns %FALSE,
|
|
since it must wait until poll() has been called before it knows whether
|
|
any events need to be processed. It sets the returned timeout to -1 to
|
|
indicate that it doesn't mind how long the poll() call blocks. In the
|
|
check function, it tests the results of the poll() call to see if the
|
|
required condition has been met, and returns %TRUE if so.</doc>
|
|
<field name="prepare">
|
|
<callback name="prepare">
|
|
<return-value transfer-ownership="none">
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="source" transfer-ownership="none">
|
|
<type name="Source" c:type="GSource*"/>
|
|
</parameter>
|
|
<parameter name="timeout_" transfer-ownership="none">
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="check">
|
|
<callback name="check">
|
|
<return-value transfer-ownership="none">
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="source" transfer-ownership="none">
|
|
<type name="Source" c:type="GSource*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="dispatch" introspectable="0">
|
|
<callback name="dispatch" introspectable="0">
|
|
<return-value transfer-ownership="none">
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="source" transfer-ownership="none">
|
|
<type name="Source" c:type="GSource*"/>
|
|
</parameter>
|
|
<parameter name="callback" transfer-ownership="none" closure="2">
|
|
<type name="SourceFunc" c:type="GSourceFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="finalize">
|
|
<callback name="finalize">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="source" transfer-ownership="none">
|
|
<type name="Source" c:type="GSource*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
</field>
|
|
<field name="closure_callback" readable="0" private="1">
|
|
<type name="SourceFunc" c:type="GSourceFunc"/>
|
|
</field>
|
|
<field name="closure_marshal" readable="0" private="1">
|
|
<type name="SourceDummyMarshal" c:type="GSourceDummyMarshal"/>
|
|
</field>
|
|
</record>
|
|
<record name="SourcePrivate" c:type="GSourcePrivate" disguised="1">
|
|
|
|
</record>
|
|
<callback name="SpawnChildSetupFunc" c:type="GSpawnChildSetupFunc">
|
|
<doc xml:space="preserve">Specifies the type of the setup function passed to g_spawn_async(),
|
|
g_spawn_sync() and g_spawn_async_with_pipes(), which can, in very
|
|
limited ways, be used to affect the child's execution.
|
|
|
|
On POSIX platforms, the function is called in the child after GLib
|
|
has performed all the setup it plans to perform, but before calling
|
|
exec(). Actions taken in this function will only affect the child,
|
|
not the parent.
|
|
|
|
On Windows, the function is called in the parent. Its usefulness on
|
|
Windows is thus questionable. In many cases executing the child setup
|
|
function in the parent can have ill effects, and you should be very
|
|
careful when porting software to Windows that uses child setup
|
|
functions.
|
|
|
|
However, even on POSIX, you are extremely limited in what you can
|
|
safely do from a #GSpawnChildSetupFunc, because any mutexes that were
|
|
held by other threads in the parent process at the time of the fork()
|
|
will still be locked in the child process, and they will never be
|
|
unlocked (since the threads that held them don't exist in the child).
|
|
POSIX allows only async-signal-safe functions (see signal(7)) to be
|
|
called in the child between fork() and exec(), which drastically limits
|
|
the usefulness of child setup functions.
|
|
|
|
In particular, it is not safe to call any function which may
|
|
call malloc(), which includes POSIX functions such as setenv().
|
|
If you need to set up the child environment differently from
|
|
the parent, you should use g_get_environ(), g_environ_setenv(),
|
|
and g_environ_unsetenv(), and then pass the complete environment
|
|
list to the `g_spawn...` function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="0">
|
|
<doc xml:space="preserve">user data to pass to the function.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<enumeration name="SpawnError" c:type="GSpawnError" glib:error-domain="g-exec-error-quark">
|
|
<doc xml:space="preserve">Error codes returned by spawning processes.</doc>
|
|
<member name="fork" value="0" c:identifier="G_SPAWN_ERROR_FORK">
|
|
<doc xml:space="preserve">Fork failed due to lack of memory.</doc>
|
|
</member>
|
|
<member name="read" value="1" c:identifier="G_SPAWN_ERROR_READ">
|
|
<doc xml:space="preserve">Read or select on pipes failed.</doc>
|
|
</member>
|
|
<member name="chdir" value="2" c:identifier="G_SPAWN_ERROR_CHDIR">
|
|
<doc xml:space="preserve">Changing to working directory failed.</doc>
|
|
</member>
|
|
<member name="acces" value="3" c:identifier="G_SPAWN_ERROR_ACCES">
|
|
<doc xml:space="preserve">execv() returned `EACCES`</doc>
|
|
</member>
|
|
<member name="perm" value="4" c:identifier="G_SPAWN_ERROR_PERM">
|
|
<doc xml:space="preserve">execv() returned `EPERM`</doc>
|
|
</member>
|
|
<member name="too_big" value="5" c:identifier="G_SPAWN_ERROR_TOO_BIG">
|
|
<doc xml:space="preserve">execv() returned `E2BIG`</doc>
|
|
</member>
|
|
<member name="2big" value="5" c:identifier="G_SPAWN_ERROR_2BIG">
|
|
<doc xml:space="preserve">deprecated alias for %G_SPAWN_ERROR_TOO_BIG (deprecated since GLib 2.32)</doc>
|
|
</member>
|
|
<member name="noexec" value="6" c:identifier="G_SPAWN_ERROR_NOEXEC">
|
|
<doc xml:space="preserve">execv() returned `ENOEXEC`</doc>
|
|
</member>
|
|
<member name="nametoolong" value="7" c:identifier="G_SPAWN_ERROR_NAMETOOLONG">
|
|
<doc xml:space="preserve">execv() returned `ENAMETOOLONG`</doc>
|
|
</member>
|
|
<member name="noent" value="8" c:identifier="G_SPAWN_ERROR_NOENT">
|
|
<doc xml:space="preserve">execv() returned `ENOENT`</doc>
|
|
</member>
|
|
<member name="nomem" value="9" c:identifier="G_SPAWN_ERROR_NOMEM">
|
|
<doc xml:space="preserve">execv() returned `ENOMEM`</doc>
|
|
</member>
|
|
<member name="notdir" value="10" c:identifier="G_SPAWN_ERROR_NOTDIR">
|
|
<doc xml:space="preserve">execv() returned `ENOTDIR`</doc>
|
|
</member>
|
|
<member name="loop" value="11" c:identifier="G_SPAWN_ERROR_LOOP">
|
|
<doc xml:space="preserve">execv() returned `ELOOP`</doc>
|
|
</member>
|
|
<member name="txtbusy" value="12" c:identifier="G_SPAWN_ERROR_TXTBUSY">
|
|
<doc xml:space="preserve">execv() returned `ETXTBUSY`</doc>
|
|
</member>
|
|
<member name="io" value="13" c:identifier="G_SPAWN_ERROR_IO">
|
|
<doc xml:space="preserve">execv() returned `EIO`</doc>
|
|
</member>
|
|
<member name="nfile" value="14" c:identifier="G_SPAWN_ERROR_NFILE">
|
|
<doc xml:space="preserve">execv() returned `ENFILE`</doc>
|
|
</member>
|
|
<member name="mfile" value="15" c:identifier="G_SPAWN_ERROR_MFILE">
|
|
<doc xml:space="preserve">execv() returned `EMFILE`</doc>
|
|
</member>
|
|
<member name="inval" value="16" c:identifier="G_SPAWN_ERROR_INVAL">
|
|
<doc xml:space="preserve">execv() returned `EINVAL`</doc>
|
|
</member>
|
|
<member name="isdir" value="17" c:identifier="G_SPAWN_ERROR_ISDIR">
|
|
<doc xml:space="preserve">execv() returned `EISDIR`</doc>
|
|
</member>
|
|
<member name="libbad" value="18" c:identifier="G_SPAWN_ERROR_LIBBAD">
|
|
<doc xml:space="preserve">execv() returned `ELIBBAD`</doc>
|
|
</member>
|
|
<member name="failed" value="19" c:identifier="G_SPAWN_ERROR_FAILED">
|
|
<doc xml:space="preserve">Some other fatal failure,
|
|
`error->message` should explain.</doc>
|
|
</member>
|
|
</enumeration>
|
|
<bitfield name="SpawnFlags" c:type="GSpawnFlags">
|
|
<doc xml:space="preserve">Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes().</doc>
|
|
<member name="default" value="0" c:identifier="G_SPAWN_DEFAULT">
|
|
<doc xml:space="preserve">no flags, default behaviour</doc>
|
|
</member>
|
|
<member name="leave_descriptors_open" value="1" c:identifier="G_SPAWN_LEAVE_DESCRIPTORS_OPEN">
|
|
<doc xml:space="preserve">the parent's open file descriptors will
|
|
be inherited by the child; otherwise all descriptors except stdin,
|
|
stdout and stderr will be closed before calling exec() in the child.</doc>
|
|
</member>
|
|
<member name="do_not_reap_child" value="2" c:identifier="G_SPAWN_DO_NOT_REAP_CHILD">
|
|
<doc xml:space="preserve">the child will not be automatically reaped;
|
|
you must use g_child_watch_add() yourself (or call waitpid() or handle
|
|
`SIGCHLD` yourself), or the child will become a zombie.</doc>
|
|
</member>
|
|
<member name="search_path" value="4" c:identifier="G_SPAWN_SEARCH_PATH">
|
|
<doc xml:space="preserve">`argv[0]` need not be an absolute path, it will be
|
|
looked for in the user's `PATH`.</doc>
|
|
</member>
|
|
<member name="stdout_to_dev_null" value="8" c:identifier="G_SPAWN_STDOUT_TO_DEV_NULL">
|
|
<doc xml:space="preserve">the child's standard output will be discarded,
|
|
instead of going to the same location as the parent's standard output.</doc>
|
|
</member>
|
|
<member name="stderr_to_dev_null" value="16" c:identifier="G_SPAWN_STDERR_TO_DEV_NULL">
|
|
<doc xml:space="preserve">the child's standard error will be discarded.</doc>
|
|
</member>
|
|
<member name="child_inherits_stdin" value="32" c:identifier="G_SPAWN_CHILD_INHERITS_STDIN">
|
|
<doc xml:space="preserve">the child will inherit the parent's standard
|
|
input (by default, the child's standard input is attached to `/dev/null`).</doc>
|
|
</member>
|
|
<member name="file_and_argv_zero" value="64" c:identifier="G_SPAWN_FILE_AND_ARGV_ZERO">
|
|
<doc xml:space="preserve">the first element of `argv` is the file to
|
|
execute, while the remaining elements are the actual argument vector
|
|
to pass to the file. Normally g_spawn_async_with_pipes() uses `argv[0]`
|
|
as the file to execute, and passes all of `argv` to the child.</doc>
|
|
</member>
|
|
<member name="search_path_from_envp" value="128" c:identifier="G_SPAWN_SEARCH_PATH_FROM_ENVP">
|
|
<doc xml:space="preserve">if `argv[0]` is not an absolute path,
|
|
it will be looked for in the `PATH` from the passed child environment.
|
|
Since: 2.34</doc>
|
|
</member>
|
|
<member name="cloexec_pipes" value="256" c:identifier="G_SPAWN_CLOEXEC_PIPES">
|
|
<doc xml:space="preserve">create all pipes with the `O_CLOEXEC` flag set.
|
|
Since: 2.40</doc>
|
|
</member>
|
|
</bitfield>
|
|
<record name="StatBuf" c:type="GStatBuf" disguised="1">
|
|
<doc xml:space="preserve">A type corresponding to the appropriate struct type for the stat()
|
|
system call, depending on the platform and/or compiler being used.
|
|
|
|
See g_stat() for more information.</doc>
|
|
</record>
|
|
<record name="String" c:type="GString" glib:type-name="GString" glib:get-type="g_gstring_get_type" c:symbol-prefix="gstring">
|
|
<doc xml:space="preserve">The GString struct contains the public fields of a GString.</doc>
|
|
<field name="str" writable="1">
|
|
<doc xml:space="preserve">points to the character data. It may move as text is added.
|
|
The @str field is null-terminated and so
|
|
can be used as an ordinary C string.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</field>
|
|
<field name="len" writable="1">
|
|
<doc xml:space="preserve">contains the length of the string, not including the
|
|
terminating nul byte.</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</field>
|
|
<field name="allocated_len" writable="1">
|
|
<doc xml:space="preserve">the number of bytes that can be stored in the
|
|
string before it needs to be reallocated. May be larger than @len.</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</field>
|
|
<method name="append" c:identifier="g_string_append">
|
|
<doc xml:space="preserve">Adds a string onto the end of a #GString, expanding
|
|
it if necessary.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to append onto the end of @string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="append_c" c:identifier="g_string_append_c">
|
|
<doc xml:space="preserve">Adds a byte onto the end of a #GString, expanding
|
|
it if necessary.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">the byte to append onto the end of @string</doc>
|
|
<type name="gchar" c:type="gchar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="append_len" c:identifier="g_string_append_len">
|
|
<doc xml:space="preserve">Appends @len bytes of @val to @string.
|
|
|
|
If @len is positive, @val may contain embedded nuls and need
|
|
not be nul-terminated. It is the caller's responsibility to
|
|
ensure that @val has at least @len addressable bytes.
|
|
|
|
If @len is negative, @val must be nul-terminated and @len
|
|
is considered to request the entire string length. This
|
|
makes g_string_append_len() equivalent to g_string_append().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">bytes to append</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of bytes of @val to use, or -1 for all of @val</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="append_printf" c:identifier="g_string_append_printf" introspectable="0">
|
|
<doc xml:space="preserve">Appends a formatted string onto the end of a #GString.
|
|
This function is similar to g_string_printf() except
|
|
that the text is appended to the #GString.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string format. See the printf() documentation</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">the parameters to insert into the format string</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="append_unichar" c:identifier="g_string_append_unichar">
|
|
<doc xml:space="preserve">Converts a Unicode character into UTF-8, and appends it
|
|
to the string.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="wc" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="append_uri_escaped" c:identifier="g_string_append_uri_escaped" version="2.16">
|
|
<doc xml:space="preserve">Appends @unescaped to @string, escaping any characters that
|
|
are reserved in URIs using URI-style escape sequences.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="unescaped" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="reserved_chars_allowed" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string of reserved characters allowed
|
|
to be used, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="allow_utf8" transfer-ownership="none">
|
|
<doc xml:space="preserve">set %TRUE if the escaped string may include UTF8 characters</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="append_vprintf" c:identifier="g_string_append_vprintf" version="2.14" introspectable="0">
|
|
<doc xml:space="preserve">Appends a formatted string onto the end of a #GString.
|
|
This function is similar to g_string_append_printf()
|
|
except that the arguments to the format string are passed
|
|
as a va_list.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string format. See the printf() documentation</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="args" transfer-ownership="none">
|
|
<doc xml:space="preserve">the list of arguments to insert in the output</doc>
|
|
<type name="va_list" c:type="va_list"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ascii_down" c:identifier="g_string_ascii_down">
|
|
<doc xml:space="preserve">Converts all uppercase ASCII letters to lowercase ASCII letters.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">passed-in @string pointer, with all the
|
|
uppercase characters converted to lowercase in place,
|
|
with semantics that exactly match g_ascii_tolower().</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ascii_up" c:identifier="g_string_ascii_up">
|
|
<doc xml:space="preserve">Converts all lowercase ASCII letters to uppercase ASCII letters.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">passed-in @string pointer, with all the
|
|
lowercase characters converted to uppercase in place,
|
|
with semantics that exactly match g_ascii_toupper().</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="assign" c:identifier="g_string_assign">
|
|
<doc xml:space="preserve">Copies the bytes from a string into a #GString,
|
|
destroying any previous contents. It is rather like
|
|
the standard strcpy() function, except that you do not
|
|
have to worry about having enough space to copy the string.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the destination #GString. Its current contents
|
|
are destroyed.</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="rval" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to copy into @string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="down" c:identifier="g_string_down" deprecated="1" deprecated-version="2.2">
|
|
<doc xml:space="preserve">Converts a #GString to lowercase.</doc>
|
|
<doc-deprecated xml:space="preserve">This function uses the locale-specific
|
|
tolower() function, which is almost never the right thing.
|
|
Use g_string_ascii_down() or g_utf8_strdown() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="equal" c:identifier="g_string_equal">
|
|
<doc xml:space="preserve">Compares two strings for equality, returning %TRUE if they are equal.
|
|
For use with #GHashTable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the strings are the same length and contain the
|
|
same bytes</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="v" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="const GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="v2" transfer-ownership="none">
|
|
<doc xml:space="preserve">another #GString</doc>
|
|
<type name="String" c:type="const GString*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="erase" c:identifier="g_string_erase">
|
|
<doc xml:space="preserve">Removes @len bytes from a #GString, starting at position @pos.
|
|
The rest of the #GString is shifted down to fill the gap.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="pos" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position of the content to remove</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes to remove, or -1 to remove all
|
|
following bytes</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free" c:identifier="g_string_free">
|
|
<doc xml:space="preserve">Frees the memory allocated for the #GString.
|
|
If @free_segment is %TRUE it also frees the character data. If
|
|
it's %FALSE, the caller gains ownership of the buffer and must
|
|
free it after use with g_free().</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the character data of @string
|
|
(i.e. %NULL if @free_segment is %TRUE)</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="full">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="free_segment" transfer-ownership="none">
|
|
<doc xml:space="preserve">if %TRUE, the actual character data is freed as well</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free_to_bytes" c:identifier="g_string_free_to_bytes" version="2.34">
|
|
<doc xml:space="preserve">Transfers ownership of the contents of @string to a newly allocated
|
|
#GBytes. The #GString structure itself is deallocated, and it is
|
|
therefore invalid to use @string after invoking this function.
|
|
|
|
Note that while #GString ensures that its buffer always has a
|
|
trailing nul character (not reflected in its "len"), the returned
|
|
#GBytes does not include this extra nul; i.e. it has length exactly
|
|
equal to the "len" member.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">A newly allocated #GBytes containing contents of @string; @string itself is freed</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="full">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="hash" c:identifier="g_string_hash">
|
|
<doc xml:space="preserve">Creates a hash code for @str; for use with #GHashTable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">hash code for @str</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string to hash</doc>
|
|
<type name="String" c:type="const GString*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert" c:identifier="g_string_insert">
|
|
<doc xml:space="preserve">Inserts a copy of a string into a #GString,
|
|
expanding it if necessary.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="pos" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position to insert the copy of the string</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to insert</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert_c" c:identifier="g_string_insert_c">
|
|
<doc xml:space="preserve">Inserts a byte into a #GString, expanding it if necessary.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="pos" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position to insert the byte</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">the byte to insert</doc>
|
|
<type name="gchar" c:type="gchar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert_len" c:identifier="g_string_insert_len">
|
|
<doc xml:space="preserve">Inserts @len bytes of @val into @string at @pos.
|
|
|
|
If @len is positive, @val may contain embedded nuls and need
|
|
not be nul-terminated. It is the caller's responsibility to
|
|
ensure that @val has at least @len addressable bytes.
|
|
|
|
If @len is negative, @val must be nul-terminated and @len
|
|
is considered to request the entire string length.
|
|
|
|
If @pos is -1, bytes are inserted at the end of the string.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="pos" transfer-ownership="none">
|
|
<doc xml:space="preserve">position in @string where insertion should
|
|
happen, or -1 for at the end</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">bytes to insert</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of bytes of @val to insert, or -1 for all of @val</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert_unichar" c:identifier="g_string_insert_unichar">
|
|
<doc xml:space="preserve">Converts a Unicode character into UTF-8, and insert it
|
|
into the string at the given position.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="pos" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position at which to insert character, or -1
|
|
to append at the end of the string</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="wc" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="overwrite" c:identifier="g_string_overwrite" version="2.14">
|
|
<doc xml:space="preserve">Overwrites part of a string, lengthening it if necessary.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="pos" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position at which to start overwriting</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string that will overwrite the @string starting at @pos</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="overwrite_len" c:identifier="g_string_overwrite_len" version="2.14">
|
|
<doc xml:space="preserve">Overwrites part of a string, lengthening it if necessary.
|
|
This function will work with embedded nuls.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="pos" transfer-ownership="none">
|
|
<doc xml:space="preserve">the position at which to start overwriting</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string that will overwrite the @string starting at @pos</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes to write from @val</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="prepend" c:identifier="g_string_prepend">
|
|
<doc xml:space="preserve">Adds a string on to the start of a #GString,
|
|
expanding it if necessary.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to prepend on the start of @string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="prepend_c" c:identifier="g_string_prepend_c">
|
|
<doc xml:space="preserve">Adds a byte onto the start of a #GString,
|
|
expanding it if necessary.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">the byte to prepend on the start of the #GString</doc>
|
|
<type name="gchar" c:type="gchar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="prepend_len" c:identifier="g_string_prepend_len">
|
|
<doc xml:space="preserve">Prepends @len bytes of @val to @string.
|
|
|
|
If @len is positive, @val may contain embedded nuls and need
|
|
not be nul-terminated. It is the caller's responsibility to
|
|
ensure that @val has at least @len addressable bytes.
|
|
|
|
If @len is negative, @val must be nul-terminated and @len
|
|
is considered to request the entire string length. This
|
|
makes g_string_prepend_len() equivalent to g_string_prepend().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">bytes to prepend</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of bytes in @val to prepend, or -1 for all of @val</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="prepend_unichar" c:identifier="g_string_prepend_unichar">
|
|
<doc xml:space="preserve">Converts a Unicode character into UTF-8, and prepends it
|
|
to the string.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="wc" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="printf" c:identifier="g_string_printf" introspectable="0">
|
|
<doc xml:space="preserve">Writes a formatted string into a #GString.
|
|
This is similar to the standard sprintf() function,
|
|
except that the #GString buffer automatically expands
|
|
to contain the results. The previous contents of the
|
|
#GString are destroyed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string format. See the printf() documentation</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">the parameters to insert into the format string</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_size" c:identifier="g_string_set_size">
|
|
<doc xml:space="preserve">Sets the length of a #GString. If the length is less than
|
|
the current length, the string will be truncated. If the
|
|
length is greater than the current length, the contents
|
|
of the newly added area are undefined. (However, as
|
|
always, string->str[string->len] will be a nul byte.)</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the new length</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="truncate" c:identifier="g_string_truncate">
|
|
<doc xml:space="preserve">Cuts off the end of the GString, leaving the first @len bytes.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the new size of @string</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="up" c:identifier="g_string_up" deprecated="1" deprecated-version="2.2">
|
|
<doc xml:space="preserve">Converts a #GString to uppercase.</doc>
|
|
<doc-deprecated xml:space="preserve">This function uses the locale-specific
|
|
toupper() function, which is almost never the right thing.
|
|
Use g_string_ascii_up() or g_utf8_strup() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="vprintf" c:identifier="g_string_vprintf" version="2.14" introspectable="0">
|
|
<doc xml:space="preserve">Writes a formatted string into a #GString.
|
|
This function is similar to g_string_printf() except that
|
|
the arguments to the format string are passed as a va_list.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</instance-parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string format. See the printf() documentation</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="args" transfer-ownership="none">
|
|
<doc xml:space="preserve">the parameters to insert into the format string</doc>
|
|
<type name="va_list" c:type="va_list"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<record name="StringChunk" c:type="GStringChunk" disguised="1">
|
|
<doc xml:space="preserve">An opaque data structure representing String Chunks.
|
|
It should only be accessed by using the following functions.</doc>
|
|
<method name="clear" c:identifier="g_string_chunk_clear" version="2.14">
|
|
<doc xml:space="preserve">Frees all strings contained within the #GStringChunk.
|
|
After calling g_string_chunk_clear() it is not safe to
|
|
access any of the strings which were contained within it.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="chunk" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GStringChunk</doc>
|
|
<type name="StringChunk" c:type="GStringChunk*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free" c:identifier="g_string_chunk_free">
|
|
<doc xml:space="preserve">Frees all memory allocated by the #GStringChunk.
|
|
After calling g_string_chunk_free() it is not safe to
|
|
access any of the strings which were contained within it.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="chunk" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GStringChunk</doc>
|
|
<type name="StringChunk" c:type="GStringChunk*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert" c:identifier="g_string_chunk_insert">
|
|
<doc xml:space="preserve">Adds a copy of @string to the #GStringChunk.
|
|
It returns a pointer to the new copy of the string
|
|
in the #GStringChunk. The characters in the string
|
|
can be changed, if necessary, though you should not
|
|
change anything after the end of the string.
|
|
|
|
Unlike g_string_chunk_insert_const(), this function
|
|
does not check for duplicates. Also strings added
|
|
with g_string_chunk_insert() will not be searched
|
|
by g_string_chunk_insert_const() when looking for
|
|
duplicates.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to the copy of @string within
|
|
the #GStringChunk</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="chunk" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GStringChunk</doc>
|
|
<type name="StringChunk" c:type="GStringChunk*"/>
|
|
</instance-parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to add</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert_const" c:identifier="g_string_chunk_insert_const">
|
|
<doc xml:space="preserve">Adds a copy of @string to the #GStringChunk, unless the same
|
|
string has already been added to the #GStringChunk with
|
|
g_string_chunk_insert_const().
|
|
|
|
This function is useful if you need to copy a large number
|
|
of strings but do not want to waste space storing duplicates.
|
|
But you must remember that there may be several pointers to
|
|
the same string, and so any changes made to the strings
|
|
should be done very carefully.
|
|
|
|
Note that g_string_chunk_insert_const() will not return a
|
|
pointer to a string added with g_string_chunk_insert(), even
|
|
if they do match.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to the new or existing copy of @string
|
|
within the #GStringChunk</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="chunk" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GStringChunk</doc>
|
|
<type name="StringChunk" c:type="GStringChunk*"/>
|
|
</instance-parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to add</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert_len" c:identifier="g_string_chunk_insert_len" version="2.4">
|
|
<doc xml:space="preserve">Adds a copy of the first @len bytes of @string to the #GStringChunk.
|
|
The copy is nul-terminated.
|
|
|
|
Since this function does not stop at nul bytes, it is the caller's
|
|
responsibility to ensure that @string has at least @len addressable
|
|
bytes.
|
|
|
|
The characters in the returned string can be changed, if necessary,
|
|
though you should not change anything after the end of the string.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to the copy of @string within the #GStringChunk</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="chunk" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GStringChunk</doc>
|
|
<type name="StringChunk" c:type="GStringChunk*"/>
|
|
</instance-parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">bytes to insert</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of bytes of @string to insert, or -1 to insert a
|
|
nul-terminated string</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="new" c:identifier="g_string_chunk_new" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GStringChunk.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a new #GStringChunk</doc>
|
|
<type name="StringChunk" c:type="GStringChunk*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the default size of the blocks of memory which are
|
|
allocated to store the strings. If a particular string
|
|
is larger than this default size, a larger block of
|
|
memory will be allocated for it.</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<constant name="TEST_OPTION_ISOLATE_DIRS" value="isolate_dirs" c:type="G_TEST_OPTION_ISOLATE_DIRS" version="2.60">
|
|
<doc xml:space="preserve">Creates a unique temporary directory for each unit test and uses
|
|
g_set_user_dirs() to set XDG directories to point into subdirectories of it
|
|
for the duration of the unit test. The directory tree is cleaned up after the
|
|
test finishes successfully. Note that this doesn’t take effect until
|
|
g_test_run() is called, so calls to (for example) g_get_user_home_dir() will
|
|
return the system-wide value when made in a test program’s main() function.
|
|
|
|
The following functions will return subdirectories of the temporary directory
|
|
when this option is used. The specific subdirectory paths in use are not
|
|
guaranteed to be stable API — always use a getter function to retrieve them.
|
|
|
|
- g_get_home_dir()
|
|
- g_get_user_cache_dir()
|
|
- g_get_system_config_dirs()
|
|
- g_get_user_config_dir()
|
|
- g_get_system_data_dirs()
|
|
- g_get_user_data_dir()
|
|
- g_get_user_runtime_dir()
|
|
|
|
The subdirectories may not be created by the test harness; as with normal
|
|
calls to functions like g_get_user_cache_dir(), the caller must be prepared
|
|
to create the directory if it doesn’t exist.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="TIME_SPAN_DAY" value="86400000000" c:type="G_TIME_SPAN_DAY" version="2.26">
|
|
<doc xml:space="preserve">Evaluates to a time span of one day.</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</constant>
|
|
<constant name="TIME_SPAN_HOUR" value="3600000000" c:type="G_TIME_SPAN_HOUR" version="2.26">
|
|
<doc xml:space="preserve">Evaluates to a time span of one hour.</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</constant>
|
|
<constant name="TIME_SPAN_MILLISECOND" value="1000" c:type="G_TIME_SPAN_MILLISECOND" version="2.26">
|
|
<doc xml:space="preserve">Evaluates to a time span of one millisecond.</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</constant>
|
|
<constant name="TIME_SPAN_MINUTE" value="60000000" c:type="G_TIME_SPAN_MINUTE" version="2.26">
|
|
<doc xml:space="preserve">Evaluates to a time span of one minute.</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</constant>
|
|
<constant name="TIME_SPAN_SECOND" value="1000000" c:type="G_TIME_SPAN_SECOND" version="2.26">
|
|
<doc xml:space="preserve">Evaluates to a time span of one second.</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</constant>
|
|
<function-macro name="TRYLOCK" c:identifier="G_TRYLOCK" introspectable="0">
|
|
<doc xml:space="preserve">Works like g_mutex_trylock(), but for a lock defined with
|
|
#G_LOCK_DEFINE.</doc>
|
|
<parameters>
|
|
<parameter name="name">
|
|
<doc xml:space="preserve">the name of the lock</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<record name="TestCase" c:type="GTestCase" disguised="1">
|
|
<doc xml:space="preserve">An opaque structure representing a test case.</doc>
|
|
</record>
|
|
<record name="TestConfig" c:type="GTestConfig">
|
|
<field name="test_initialized" writable="1">
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</field>
|
|
<field name="test_quick" writable="1">
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</field>
|
|
<field name="test_perf" writable="1">
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</field>
|
|
<field name="test_verbose" writable="1">
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</field>
|
|
<field name="test_quiet" writable="1">
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</field>
|
|
<field name="test_undefined" writable="1">
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</field>
|
|
</record>
|
|
<callback name="TestDataFunc" c:type="GTestDataFunc" version="2.28">
|
|
<doc xml:space="preserve">The type used for test case functions that take an extra pointer
|
|
argument.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="0">
|
|
<doc xml:space="preserve">the data provided when registering the test</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<enumeration name="TestFileType" version="2.38" c:type="GTestFileType">
|
|
<doc xml:space="preserve">The type of file to return the filename for, when used with
|
|
g_test_build_filename().
|
|
|
|
These two options correspond rather directly to the 'dist' and
|
|
'built' terminology that automake uses and are explicitly used to
|
|
distinguish between the 'srcdir' and 'builddir' being separate. All
|
|
files in your project should either be dist (in the
|
|
`EXTRA_DIST` or `dist_schema_DATA`
|
|
sense, in which case they will always be in the srcdir) or built (in
|
|
the `BUILT_SOURCES` sense, in which case they will
|
|
always be in the builddir).
|
|
|
|
Note: as a general rule of automake, files that are generated only as
|
|
part of the build-from-git process (but then are distributed with the
|
|
tarball) always go in srcdir (even if doing a srcdir != builddir
|
|
build from git) and are considered as distributed files.</doc>
|
|
<member name="dist" value="0" c:identifier="G_TEST_DIST">
|
|
<doc xml:space="preserve">a file that was included in the distribution tarball</doc>
|
|
</member>
|
|
<member name="built" value="1" c:identifier="G_TEST_BUILT">
|
|
<doc xml:space="preserve">a file that was built on the compiling machine</doc>
|
|
</member>
|
|
</enumeration>
|
|
<callback name="TestFixtureFunc" c:type="GTestFixtureFunc" version="2.28">
|
|
<doc xml:space="preserve">The type used for functions that operate on test fixtures. This is
|
|
used for the fixture setup and teardown functions as well as for the
|
|
testcases themselves.
|
|
|
|
@user_data is a pointer to the data that was given when registering
|
|
the test case.
|
|
|
|
@fixture will be a pointer to the area of memory allocated by the
|
|
test framework, of the size requested. If the requested size was
|
|
zero then @fixture will be equal to @user_data.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="fixture" transfer-ownership="none">
|
|
<doc xml:space="preserve">the test fixture</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="1">
|
|
<doc xml:space="preserve">the data provided when registering the test</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<callback name="TestFunc" c:type="GTestFunc" version="2.28">
|
|
<doc xml:space="preserve">The type used for test case functions.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
</callback>
|
|
<record name="TestLogBuffer" c:type="GTestLogBuffer">
|
|
<field name="data" readable="0" private="1">
|
|
<type name="String" c:type="GString*"/>
|
|
</field>
|
|
<field name="msgs" readable="0" private="1">
|
|
<type name="GLib.SList" c:type="GSList*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</field>
|
|
<method name="free" c:identifier="g_test_log_buffer_free">
|
|
<doc xml:space="preserve">Internal function for gtester to free test log messages, no ABI guarantees provided.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tbuffer" transfer-ownership="none">
|
|
<type name="TestLogBuffer" c:type="GTestLogBuffer*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="pop" c:identifier="g_test_log_buffer_pop" introspectable="0">
|
|
<doc xml:space="preserve">Internal function for gtester to retrieve test log messages, no ABI guarantees provided.</doc>
|
|
<return-value>
|
|
<type name="TestLogMsg" c:type="GTestLogMsg*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tbuffer" transfer-ownership="none">
|
|
<type name="TestLogBuffer" c:type="GTestLogBuffer*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="push" c:identifier="g_test_log_buffer_push">
|
|
<doc xml:space="preserve">Internal function for gtester to decode test log messages, no ABI guarantees provided.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tbuffer" transfer-ownership="none">
|
|
<type name="TestLogBuffer" c:type="GTestLogBuffer*"/>
|
|
</instance-parameter>
|
|
<parameter name="n_bytes" transfer-ownership="none">
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="bytes" transfer-ownership="none">
|
|
<type name="guint8" c:type="const guint8*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="new" c:identifier="g_test_log_buffer_new" introspectable="0">
|
|
<doc xml:space="preserve">Internal function for gtester to decode test log messages, no ABI guarantees provided.</doc>
|
|
<return-value>
|
|
<type name="TestLogBuffer" c:type="GTestLogBuffer*"/>
|
|
</return-value>
|
|
</function>
|
|
</record>
|
|
<callback name="TestLogFatalFunc" c:type="GTestLogFatalFunc" version="2.22">
|
|
<doc xml:space="preserve">Specifies the prototype of fatal log handler functions.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the program should abort, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_domain" transfer-ownership="none">
|
|
<doc xml:space="preserve">the log domain of the message</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="log_level" transfer-ownership="none">
|
|
<doc xml:space="preserve">the log level of the message (including the fatal and recursion flags)</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
<parameter name="message" transfer-ownership="none">
|
|
<doc xml:space="preserve">the message to process</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="3">
|
|
<doc xml:space="preserve">user data, set in g_test_log_set_fatal_handler()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<record name="TestLogMsg" c:type="GTestLogMsg">
|
|
<field name="log_type" writable="1">
|
|
<type name="TestLogType" c:type="GTestLogType"/>
|
|
</field>
|
|
<field name="n_strings" writable="1">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="strings" writable="1">
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</field>
|
|
<field name="n_nums" writable="1">
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
<field name="nums" introspectable="0" writable="1">
|
|
<type name="long double" c:type="long double*"/>
|
|
</field>
|
|
<method name="free" c:identifier="g_test_log_msg_free">
|
|
<doc xml:space="preserve">Internal function for gtester to free test log messages, no ABI guarantees provided.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tmsg" transfer-ownership="none">
|
|
<type name="TestLogMsg" c:type="GTestLogMsg*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<enumeration name="TestLogType" c:type="GTestLogType">
|
|
<member name="none" value="0" c:identifier="G_TEST_LOG_NONE">
|
|
</member>
|
|
<member name="error" value="1" c:identifier="G_TEST_LOG_ERROR">
|
|
</member>
|
|
<member name="start_binary" value="2" c:identifier="G_TEST_LOG_START_BINARY">
|
|
</member>
|
|
<member name="list_case" value="3" c:identifier="G_TEST_LOG_LIST_CASE">
|
|
</member>
|
|
<member name="skip_case" value="4" c:identifier="G_TEST_LOG_SKIP_CASE">
|
|
</member>
|
|
<member name="start_case" value="5" c:identifier="G_TEST_LOG_START_CASE">
|
|
</member>
|
|
<member name="stop_case" value="6" c:identifier="G_TEST_LOG_STOP_CASE">
|
|
</member>
|
|
<member name="min_result" value="7" c:identifier="G_TEST_LOG_MIN_RESULT">
|
|
</member>
|
|
<member name="max_result" value="8" c:identifier="G_TEST_LOG_MAX_RESULT">
|
|
</member>
|
|
<member name="message" value="9" c:identifier="G_TEST_LOG_MESSAGE">
|
|
</member>
|
|
<member name="start_suite" value="10" c:identifier="G_TEST_LOG_START_SUITE">
|
|
</member>
|
|
<member name="stop_suite" value="11" c:identifier="G_TEST_LOG_STOP_SUITE">
|
|
</member>
|
|
</enumeration>
|
|
<enumeration name="TestResult" c:type="GTestResult">
|
|
<member name="success" value="0" c:identifier="G_TEST_RUN_SUCCESS">
|
|
</member>
|
|
<member name="skipped" value="1" c:identifier="G_TEST_RUN_SKIPPED">
|
|
</member>
|
|
<member name="failure" value="2" c:identifier="G_TEST_RUN_FAILURE">
|
|
</member>
|
|
<member name="incomplete" value="3" c:identifier="G_TEST_RUN_INCOMPLETE">
|
|
</member>
|
|
</enumeration>
|
|
<bitfield name="TestSubprocessFlags" c:type="GTestSubprocessFlags">
|
|
<doc xml:space="preserve">Flags to pass to g_test_trap_subprocess() to control input and output.
|
|
|
|
Note that in contrast with g_test_trap_fork(), the default is to
|
|
not show stdout and stderr.</doc>
|
|
<member name="stdin" value="1" c:identifier="G_TEST_SUBPROCESS_INHERIT_STDIN">
|
|
<doc xml:space="preserve">If this flag is given, the child
|
|
process will inherit the parent's stdin. Otherwise, the child's
|
|
stdin is redirected to `/dev/null`.</doc>
|
|
</member>
|
|
<member name="stdout" value="2" c:identifier="G_TEST_SUBPROCESS_INHERIT_STDOUT">
|
|
<doc xml:space="preserve">If this flag is given, the child
|
|
process will inherit the parent's stdout. Otherwise, the child's
|
|
stdout will not be visible, but it will be captured to allow
|
|
later tests with g_test_trap_assert_stdout().</doc>
|
|
</member>
|
|
<member name="stderr" value="4" c:identifier="G_TEST_SUBPROCESS_INHERIT_STDERR">
|
|
<doc xml:space="preserve">If this flag is given, the child
|
|
process will inherit the parent's stderr. Otherwise, the child's
|
|
stderr will not be visible, but it will be captured to allow
|
|
later tests with g_test_trap_assert_stderr().</doc>
|
|
</member>
|
|
</bitfield>
|
|
<record name="TestSuite" c:type="GTestSuite" disguised="1">
|
|
<doc xml:space="preserve">An opaque structure representing a test suite.</doc>
|
|
<method name="add" c:identifier="g_test_suite_add" version="2.16">
|
|
<doc xml:space="preserve">Adds @test_case to @suite.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="suite" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTestSuite</doc>
|
|
<type name="TestSuite" c:type="GTestSuite*"/>
|
|
</instance-parameter>
|
|
<parameter name="test_case" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTestCase</doc>
|
|
<type name="TestCase" c:type="GTestCase*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_suite" c:identifier="g_test_suite_add_suite" version="2.16">
|
|
<doc xml:space="preserve">Adds @nestedsuite to @suite.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="suite" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTestSuite</doc>
|
|
<type name="TestSuite" c:type="GTestSuite*"/>
|
|
</instance-parameter>
|
|
<parameter name="nestedsuite" transfer-ownership="none">
|
|
<doc xml:space="preserve">another #GTestSuite</doc>
|
|
<type name="TestSuite" c:type="GTestSuite*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<bitfield name="TestTrapFlags" deprecated="1" deprecated-version="2.38" c:type="GTestTrapFlags">
|
|
<doc xml:space="preserve">Test traps are guards around forked tests.
|
|
These flags determine what traps to set.</doc>
|
|
<doc-deprecated xml:space="preserve">#GTestTrapFlags is used only with g_test_trap_fork(),
|
|
which is deprecated. g_test_trap_subprocess() uses
|
|
#GTestSubprocessFlags.</doc-deprecated>
|
|
<member name="silence_stdout" value="128" c:identifier="G_TEST_TRAP_SILENCE_STDOUT">
|
|
<doc xml:space="preserve">Redirect stdout of the test child to
|
|
`/dev/null` so it cannot be observed on the console during test
|
|
runs. The actual output is still captured though to allow later
|
|
tests with g_test_trap_assert_stdout().</doc>
|
|
</member>
|
|
<member name="silence_stderr" value="256" c:identifier="G_TEST_TRAP_SILENCE_STDERR">
|
|
<doc xml:space="preserve">Redirect stderr of the test child to
|
|
`/dev/null` so it cannot be observed on the console during test
|
|
runs. The actual output is still captured though to allow later
|
|
tests with g_test_trap_assert_stderr().</doc>
|
|
</member>
|
|
<member name="inherit_stdin" value="512" c:identifier="G_TEST_TRAP_INHERIT_STDIN">
|
|
<doc xml:space="preserve">If this flag is given, stdin of the
|
|
child process is shared with stdin of its parent process.
|
|
It is redirected to `/dev/null` otherwise.</doc>
|
|
</member>
|
|
</bitfield>
|
|
<record name="Thread" c:type="GThread" glib:type-name="GThread" glib:get-type="g_thread_get_type" c:symbol-prefix="thread">
|
|
<doc xml:space="preserve">The #GThread struct represents a running thread. This struct
|
|
is returned by g_thread_new() or g_thread_try_new(). You can
|
|
obtain the #GThread struct representing the current thread by
|
|
calling g_thread_self().
|
|
|
|
GThread is refcounted, see g_thread_ref() and g_thread_unref().
|
|
The thread represented by it holds a reference while it is running,
|
|
and g_thread_join() consumes the reference that it is given, so
|
|
it is normally not necessary to manage GThread references
|
|
explicitly.
|
|
|
|
The structure is opaque -- none of its fields may be directly
|
|
accessed.</doc>
|
|
<constructor name="new" c:identifier="g_thread_new" version="2.32">
|
|
<doc xml:space="preserve">This function creates a new thread. The new thread starts by invoking
|
|
@func with the argument data. The thread will run until @func returns
|
|
or until g_thread_exit() is called from the new thread. The return value
|
|
of @func becomes the return value of the thread, which can be obtained
|
|
with g_thread_join().
|
|
|
|
The @name can be useful for discriminating threads in a debugger.
|
|
It is not used for other purposes and does not have to be unique.
|
|
Some systems restrict the length of @name to 16 bytes.
|
|
|
|
If the thread can not be created the program aborts. See
|
|
g_thread_try_new() if you want to attempt to deal with failures.
|
|
|
|
If you are using threads to offload (potentially many) short-lived tasks,
|
|
#GThreadPool may be more appropriate than manually spawning and tracking
|
|
multiple #GThreads.
|
|
|
|
To free the struct returned by this function, use g_thread_unref().
|
|
Note that g_thread_join() implicitly unrefs the #GThread as well.
|
|
|
|
New threads by default inherit their scheduler policy (POSIX) or thread
|
|
priority (Windows) of the thread creating the new thread.
|
|
|
|
This behaviour changed in GLib 2.64: before threads on Windows were not
|
|
inheriting the thread priority but were spawned with the default priority.
|
|
Starting with GLib 2.64 the behaviour is now consistent between Windows and
|
|
POSIX and all threads inherit their parent thread's priority.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the new #GThread</doc>
|
|
<type name="Thread" c:type="GThread*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="name" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">an (optional) name for the new thread</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" scope="async" closure="2">
|
|
<doc xml:space="preserve">a function to execute in the new thread</doc>
|
|
<type name="ThreadFunc" c:type="GThreadFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">an argument to supply to the new thread</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="try_new" c:identifier="g_thread_try_new" version="2.32" throws="1">
|
|
<doc xml:space="preserve">This function is the same as g_thread_new() except that
|
|
it allows for the possibility of failure.
|
|
|
|
If a thread can not be created (due to resource limits),
|
|
@error is set and %NULL is returned.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the new #GThread, or %NULL if an error occurred</doc>
|
|
<type name="Thread" c:type="GThread*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="name" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">an (optional) name for the new thread</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" scope="async" closure="2">
|
|
<doc xml:space="preserve">a function to execute in the new thread</doc>
|
|
<type name="ThreadFunc" c:type="GThreadFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">an argument to supply to the new thread</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<method name="join" c:identifier="g_thread_join">
|
|
<doc xml:space="preserve">Waits until @thread finishes, i.e. the function @func, as
|
|
given to g_thread_new(), returns or g_thread_exit() is called.
|
|
If @thread has already terminated, then g_thread_join()
|
|
returns immediately.
|
|
|
|
Any thread can wait for any other thread by calling g_thread_join(),
|
|
not just its 'creator'. Calling g_thread_join() from multiple threads
|
|
for the same @thread leads to undefined behaviour.
|
|
|
|
The value returned by @func or given to g_thread_exit() is
|
|
returned by this function.
|
|
|
|
g_thread_join() consumes the reference to the passed-in @thread.
|
|
This will usually cause the #GThread struct and associated resources
|
|
to be freed. Use g_thread_ref() to obtain an extra reference if you
|
|
want to keep the GThread alive beyond the g_thread_join() call.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the return value of the thread</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="thread" transfer-ownership="full">
|
|
<doc xml:space="preserve">a #GThread</doc>
|
|
<type name="Thread" c:type="GThread*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_thread_ref" version="2.32">
|
|
<doc xml:space="preserve">Increase the reference count on @thread.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new reference to @thread</doc>
|
|
<type name="Thread" c:type="GThread*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="thread" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GThread</doc>
|
|
<type name="Thread" c:type="GThread*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_thread_unref" version="2.32">
|
|
<doc xml:space="preserve">Decrease the reference count on @thread, possibly freeing all
|
|
resources associated with it.
|
|
|
|
Note that each thread holds a reference to its #GThread while
|
|
it is running, so it is safe to drop your own reference to it
|
|
if you don't need it anymore.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="thread" transfer-ownership="full">
|
|
<doc xml:space="preserve">a #GThread</doc>
|
|
<type name="Thread" c:type="GThread*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="error_quark" c:identifier="g_thread_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="exit" c:identifier="g_thread_exit">
|
|
<doc xml:space="preserve">Terminates the current thread.
|
|
|
|
If another thread is waiting for us using g_thread_join() then the
|
|
waiting thread will be woken up and get @retval as the return value
|
|
of g_thread_join().
|
|
|
|
Calling g_thread_exit() with a parameter @retval is equivalent to
|
|
returning @retval from the function @func, as given to g_thread_new().
|
|
|
|
You must only call g_thread_exit() from a thread that you created
|
|
yourself with g_thread_new() or related APIs. You must not call
|
|
this function from a thread created with another threading library
|
|
or or from within a #GThreadPool.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="retval" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the return value of this thread</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="self" c:identifier="g_thread_self">
|
|
<doc xml:space="preserve">This function returns the #GThread corresponding to the
|
|
current thread. Note that this function does not increase
|
|
the reference count of the returned struct.
|
|
|
|
This function will return a #GThread even for threads that
|
|
were not created by GLib (i.e. those created by other threading
|
|
APIs). This may be useful for thread identification purposes
|
|
(i.e. comparisons) but you must not use GLib functions (such
|
|
as g_thread_join()) on these threads.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GThread representing the current thread</doc>
|
|
<type name="Thread" c:type="GThread*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="yield" c:identifier="g_thread_yield">
|
|
<doc xml:space="preserve">Causes the calling thread to voluntarily relinquish the CPU, so
|
|
that other threads can run.
|
|
|
|
This function is often used as a method to make busy wait less evil.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
</function>
|
|
</record>
|
|
<enumeration name="ThreadError" c:type="GThreadError" glib:error-domain="g_thread_error">
|
|
<doc xml:space="preserve">Possible errors of thread related functions.</doc>
|
|
<member name="thread_error_again" value="0" c:identifier="G_THREAD_ERROR_AGAIN">
|
|
<doc xml:space="preserve">a thread couldn't be created due to resource
|
|
shortage. Try again later.</doc>
|
|
</member>
|
|
</enumeration>
|
|
<callback name="ThreadFunc" c:type="GThreadFunc">
|
|
<doc xml:space="preserve">Specifies the type of the @func functions passed to g_thread_new()
|
|
or g_thread_try_new().</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the return value of the thread</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data passed to the thread</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<record name="ThreadPool" c:type="GThreadPool">
|
|
<doc xml:space="preserve">The #GThreadPool struct represents a thread pool. It has three
|
|
public read-only members, but the underlying struct is bigger,
|
|
so you must not copy this struct.</doc>
|
|
<field name="func" writable="1">
|
|
<doc xml:space="preserve">the function to execute in the threads of this pool</doc>
|
|
<type name="Func" c:type="GFunc"/>
|
|
</field>
|
|
<field name="user_data" writable="1">
|
|
<doc xml:space="preserve">the user data for the threads of this pool</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="exclusive" writable="1">
|
|
<doc xml:space="preserve">are all threads exclusive to this pool</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</field>
|
|
<method name="free" c:identifier="g_thread_pool_free">
|
|
<doc xml:space="preserve">Frees all resources allocated for @pool.
|
|
|
|
If @immediate is %TRUE, no new task is processed for @pool.
|
|
Otherwise @pool is not freed before the last task is processed.
|
|
Note however, that no thread of this pool is interrupted while
|
|
processing a task. Instead at least all still running threads
|
|
can finish their tasks before the @pool is freed.
|
|
|
|
If @wait_ is %TRUE, this function does not return before all
|
|
tasks to be processed (dependent on @immediate, whether all
|
|
or only the currently running) are ready.
|
|
Otherwise this function returns immediately.
|
|
|
|
After calling this function @pool must not be used anymore.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="pool" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GThreadPool</doc>
|
|
<type name="ThreadPool" c:type="GThreadPool*"/>
|
|
</instance-parameter>
|
|
<parameter name="immediate" transfer-ownership="none">
|
|
<doc xml:space="preserve">should @pool shut down immediately?</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
<parameter name="wait_" transfer-ownership="none">
|
|
<doc xml:space="preserve">should the function wait for all tasks to be finished?</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_max_threads" c:identifier="g_thread_pool_get_max_threads">
|
|
<doc xml:space="preserve">Returns the maximal number of threads for @pool.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximal number of threads</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="pool" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GThreadPool</doc>
|
|
<type name="ThreadPool" c:type="GThreadPool*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_num_threads" c:identifier="g_thread_pool_get_num_threads">
|
|
<doc xml:space="preserve">Returns the number of threads currently running in @pool.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of threads currently running</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="pool" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GThreadPool</doc>
|
|
<type name="ThreadPool" c:type="GThreadPool*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="move_to_front" c:identifier="g_thread_pool_move_to_front" version="2.46">
|
|
<doc xml:space="preserve">Moves the item to the front of the queue of unprocessed
|
|
items, so that it will be processed next.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the item was found and moved</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="pool" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GThreadPool</doc>
|
|
<type name="ThreadPool" c:type="GThreadPool*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">an unprocessed item in the pool</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="push" c:identifier="g_thread_pool_push" throws="1">
|
|
<doc xml:space="preserve">Inserts @data into the list of tasks to be executed by @pool.
|
|
|
|
When the number of currently running threads is lower than the
|
|
maximal allowed number of threads, a new thread is started (or
|
|
reused) with the properties given to g_thread_pool_new().
|
|
Otherwise, @data stays in the queue until a thread in this pool
|
|
finishes its previous task and processes @data.
|
|
|
|
@error can be %NULL to ignore errors, or non-%NULL to report
|
|
errors. An error can only occur when a new thread couldn't be
|
|
created. In that case @data is simply appended to the queue of
|
|
work to do.
|
|
|
|
Before version 2.32, this function did not return a success status.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on success, %FALSE if an error occurred</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="pool" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GThreadPool</doc>
|
|
<type name="ThreadPool" c:type="GThreadPool*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a new task for @pool</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_max_threads" c:identifier="g_thread_pool_set_max_threads" throws="1">
|
|
<doc xml:space="preserve">Sets the maximal allowed number of threads for @pool.
|
|
A value of -1 means that the maximal number of threads
|
|
is unlimited. If @pool is an exclusive thread pool, setting
|
|
the maximal number of threads to -1 is not allowed.
|
|
|
|
Setting @max_threads to 0 means stopping all work for @pool.
|
|
It is effectively frozen until @max_threads is set to a non-zero
|
|
value again.
|
|
|
|
A thread is never terminated while calling @func, as supplied by
|
|
g_thread_pool_new(). Instead the maximal number of threads only
|
|
has effect for the allocation of new threads in g_thread_pool_push().
|
|
A new thread is allocated, whenever the number of currently
|
|
running threads in @pool is smaller than the maximal number.
|
|
|
|
@error can be %NULL to ignore errors, or non-%NULL to report
|
|
errors. An error can only occur when a new thread couldn't be
|
|
created.
|
|
|
|
Before version 2.32, this function did not return a success status.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on success, %FALSE if an error occurred</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="pool" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GThreadPool</doc>
|
|
<type name="ThreadPool" c:type="GThreadPool*"/>
|
|
</instance-parameter>
|
|
<parameter name="max_threads" transfer-ownership="none">
|
|
<doc xml:space="preserve">a new maximal number of threads for @pool,
|
|
or -1 for unlimited</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="set_sort_function" c:identifier="g_thread_pool_set_sort_function" version="2.10" introspectable="0">
|
|
<doc xml:space="preserve">Sets the function used to sort the list of tasks. This allows the
|
|
tasks to be processed by a priority determined by @func, and not
|
|
just in the order in which they were added to the pool.
|
|
|
|
Note, if the maximum number of threads is more than 1, the order
|
|
that threads are executed cannot be guaranteed 100%. Threads are
|
|
scheduled by the operating system and are executed at random. It
|
|
cannot be assumed that threads are executed in the order they are
|
|
created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="pool" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GThreadPool</doc>
|
|
<type name="ThreadPool" c:type="GThreadPool*"/>
|
|
</instance-parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="1">
|
|
<doc xml:space="preserve">the #GCompareDataFunc used to sort the list of tasks.
|
|
This function is passed two tasks. It should return
|
|
0 if the order in which they are handled does not matter,
|
|
a negative value if the first task should be processed before
|
|
the second or a positive value if the second task should be
|
|
processed first.</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to @func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unprocessed" c:identifier="g_thread_pool_unprocessed">
|
|
<doc xml:space="preserve">Returns the number of tasks still unprocessed in @pool.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of unprocessed tasks</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="pool" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GThreadPool</doc>
|
|
<type name="ThreadPool" c:type="GThreadPool*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="get_max_idle_time" c:identifier="g_thread_pool_get_max_idle_time" version="2.10">
|
|
<doc xml:space="preserve">This function will return the maximum @interval that a
|
|
thread will wait in the thread pool for new tasks before
|
|
being stopped.
|
|
|
|
If this function returns 0, threads waiting in the thread
|
|
pool for new work are not stopped.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum @interval (milliseconds) to wait
|
|
for new tasks in the thread pool before stopping the
|
|
thread</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_max_unused_threads" c:identifier="g_thread_pool_get_max_unused_threads">
|
|
<doc xml:space="preserve">Returns the maximal allowed number of unused threads.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximal number of unused threads</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_num_unused_threads" c:identifier="g_thread_pool_get_num_unused_threads">
|
|
<doc xml:space="preserve">Returns the number of currently unused threads.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of currently unused threads</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="new" c:identifier="g_thread_pool_new" introspectable="0" throws="1">
|
|
<doc xml:space="preserve">This function creates a new thread pool.
|
|
|
|
Whenever you call g_thread_pool_push(), either a new thread is
|
|
created or an unused one is reused. At most @max_threads threads
|
|
are running concurrently for this thread pool. @max_threads = -1
|
|
allows unlimited threads to be created for this thread pool. The
|
|
newly created or reused thread now executes the function @func
|
|
with the two arguments. The first one is the parameter to
|
|
g_thread_pool_push() and the second one is @user_data.
|
|
|
|
Pass g_get_num_processors() to @max_threads to create as many threads as
|
|
there are logical processors on the system. This will not pin each thread to
|
|
a specific processor.
|
|
|
|
The parameter @exclusive determines whether the thread pool owns
|
|
all threads exclusive or shares them with other thread pools.
|
|
If @exclusive is %TRUE, @max_threads threads are started
|
|
immediately and they will run exclusively for this thread pool
|
|
until it is destroyed by g_thread_pool_free(). If @exclusive is
|
|
%FALSE, threads are created when needed and shared between all
|
|
non-exclusive thread pools. This implies that @max_threads may
|
|
not be -1 for exclusive thread pools. Besides, exclusive thread
|
|
pools are not affected by g_thread_pool_set_max_idle_time()
|
|
since their threads are never considered idle and returned to the
|
|
global pool.
|
|
|
|
@error can be %NULL to ignore errors, or non-%NULL to report
|
|
errors. An error can only occur when @exclusive is set to %TRUE
|
|
and not all @max_threads threads could be created.
|
|
See #GThreadError for possible errors that may occur.
|
|
Note, even in case of error a valid #GThreadPool is returned.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the new #GThreadPool</doc>
|
|
<type name="ThreadPool" c:type="GThreadPool*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="func" transfer-ownership="none" closure="1">
|
|
<doc xml:space="preserve">a function to execute in the threads of the new thread pool</doc>
|
|
<type name="Func" c:type="GFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data that is handed over to @func every time it
|
|
is called</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="max_threads" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximal number of threads to execute concurrently
|
|
in the new thread pool, -1 means no limit</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="exclusive" transfer-ownership="none">
|
|
<doc xml:space="preserve">should this thread pool be exclusive?</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="set_max_idle_time" c:identifier="g_thread_pool_set_max_idle_time" version="2.10">
|
|
<doc xml:space="preserve">This function will set the maximum @interval that a thread
|
|
waiting in the pool for new tasks can be idle for before
|
|
being stopped. This function is similar to calling
|
|
g_thread_pool_stop_unused_threads() on a regular timeout,
|
|
except this is done on a per thread basis.
|
|
|
|
By setting @interval to 0, idle threads will not be stopped.
|
|
|
|
The default value is 15000 (15 seconds).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="interval" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum @interval (in milliseconds)
|
|
a thread can be idle</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="set_max_unused_threads" c:identifier="g_thread_pool_set_max_unused_threads">
|
|
<doc xml:space="preserve">Sets the maximal number of unused threads to @max_threads.
|
|
If @max_threads is -1, no limit is imposed on the number
|
|
of unused threads.
|
|
|
|
The default value is 2.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="max_threads" transfer-ownership="none">
|
|
<doc xml:space="preserve">maximal number of unused threads</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="stop_unused_threads" c:identifier="g_thread_pool_stop_unused_threads">
|
|
<doc xml:space="preserve">Stops all currently unused threads. This does not change the
|
|
maximal number of unused threads. This function can be used to
|
|
regularly stop all unused threads e.g. from g_timeout_add().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
</function>
|
|
</record>
|
|
<enumeration name="TimeType" c:type="GTimeType">
|
|
<doc xml:space="preserve">Disambiguates a given time in two ways.
|
|
|
|
First, specifies if the given time is in universal or local time.
|
|
|
|
Second, if the time is in local time, specifies if it is local
|
|
standard time or local daylight time. This is important for the case
|
|
where the same local time occurs twice (during daylight savings time
|
|
transitions, for example).</doc>
|
|
<member name="standard" value="0" c:identifier="G_TIME_TYPE_STANDARD">
|
|
<doc xml:space="preserve">the time is in local standard time</doc>
|
|
</member>
|
|
<member name="daylight" value="1" c:identifier="G_TIME_TYPE_DAYLIGHT">
|
|
<doc xml:space="preserve">the time is in local daylight time</doc>
|
|
</member>
|
|
<member name="universal" value="2" c:identifier="G_TIME_TYPE_UNIVERSAL">
|
|
<doc xml:space="preserve">the time is in UTC</doc>
|
|
</member>
|
|
</enumeration>
|
|
<record name="TimeVal" c:type="GTimeVal" deprecated="1" deprecated-version="2.62">
|
|
<doc xml:space="preserve">Represents a precise time, with seconds and microseconds.
|
|
Similar to the struct timeval returned by the gettimeofday()
|
|
UNIX system call.
|
|
|
|
GLib is attempting to unify around the use of 64-bit integers to
|
|
represent microsecond-precision time. As such, this type will be
|
|
removed from a future version of GLib. A consequence of using `glong` for
|
|
`tv_sec` is that on 32-bit systems `GTimeVal` is subject to the year 2038
|
|
problem.</doc>
|
|
<doc-deprecated xml:space="preserve">Use #GDateTime or #guint64 instead.</doc-deprecated>
|
|
<field name="tv_sec" writable="1">
|
|
<doc xml:space="preserve">seconds</doc>
|
|
<type name="glong" c:type="glong"/>
|
|
</field>
|
|
<field name="tv_usec" writable="1">
|
|
<doc xml:space="preserve">microseconds</doc>
|
|
<type name="glong" c:type="glong"/>
|
|
</field>
|
|
<method name="add" c:identifier="g_time_val_add" deprecated="1" deprecated-version="2.62">
|
|
<doc xml:space="preserve">Adds the given number of microseconds to @time_. @microseconds can
|
|
also be negative to decrease the value of @time_.</doc>
|
|
<doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use `guint64` for
|
|
representing microseconds since the epoch, or use #GDateTime.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="time_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeVal</doc>
|
|
<type name="TimeVal" c:type="GTimeVal*"/>
|
|
</instance-parameter>
|
|
<parameter name="microseconds" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of microseconds to add to @time</doc>
|
|
<type name="glong" c:type="glong"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="to_iso8601" c:identifier="g_time_val_to_iso8601" version="2.12" deprecated="1" deprecated-version="2.62">
|
|
<doc xml:space="preserve">Converts @time_ into an RFC 3339 encoded string, relative to the
|
|
Coordinated Universal Time (UTC). This is one of the many formats
|
|
allowed by ISO 8601.
|
|
|
|
ISO 8601 allows a large number of date/time formats, with or without
|
|
punctuation and optional elements. The format returned by this function
|
|
is a complete date and time, with optional punctuation included, the
|
|
UTC time zone represented as "Z", and the @tv_usec part included if
|
|
and only if it is nonzero, i.e. either
|
|
"YYYY-MM-DDTHH:MM:SSZ" or "YYYY-MM-DDTHH:MM:SS.fffffZ".
|
|
|
|
This corresponds to the Internet date/time format defined by
|
|
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt),
|
|
and to either of the two most-precise formats defined by
|
|
the W3C Note
|
|
[Date and Time Formats](http://www.w3.org/TR/NOTE-datetime-19980827).
|
|
Both of these documents are profiles of ISO 8601.
|
|
|
|
Use g_date_time_format() or g_strdup_printf() if a different
|
|
variation of ISO 8601 format is required.
|
|
|
|
If @time_ represents a date which is too large to fit into a `struct tm`,
|
|
%NULL will be returned. This is platform dependent. Note also that since
|
|
`GTimeVal` stores the number of seconds as a `glong`, on 32-bit systems it
|
|
is subject to the year 2038 problem. Accordingly, since GLib 2.62, this
|
|
function has been deprecated. Equivalent functionality is available using:
|
|
|[
|
|
GDateTime *dt = g_date_time_new_from_unix_utc (time_val);
|
|
iso8601_string = g_date_time_format_iso8601 (dt);
|
|
g_date_time_unref (dt);
|
|
]|
|
|
|
|
The return value of g_time_val_to_iso8601() has been nullable since GLib
|
|
2.54; before then, GLib would crash under the same conditions.</doc>
|
|
<doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use
|
|
g_date_time_format_iso8601(dt) instead.</doc-deprecated>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a newly allocated string containing an ISO 8601 date,
|
|
or %NULL if @time_ was too large</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="time_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeVal</doc>
|
|
<type name="TimeVal" c:type="GTimeVal*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="from_iso8601" c:identifier="g_time_val_from_iso8601" version="2.12" deprecated="1" deprecated-version="2.62">
|
|
<doc xml:space="preserve">Converts a string containing an ISO 8601 encoded date and time
|
|
to a #GTimeVal and puts it into @time_.
|
|
|
|
@iso_date must include year, month, day, hours, minutes, and
|
|
seconds. It can optionally include fractions of a second and a time
|
|
zone indicator. (In the absence of any time zone indication, the
|
|
timestamp is assumed to be in local time.)
|
|
|
|
Any leading or trailing space in @iso_date is ignored.
|
|
|
|
This function was deprecated, along with #GTimeVal itself, in GLib 2.62.
|
|
Equivalent functionality is available using code like:
|
|
|[
|
|
GDateTime *dt = g_date_time_new_from_iso8601 (iso8601_string, NULL);
|
|
gint64 time_val = g_date_time_to_unix (dt);
|
|
g_date_time_unref (dt);
|
|
]|</doc>
|
|
<doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use
|
|
g_date_time_new_from_iso8601() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the conversion was successful.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="iso_date" transfer-ownership="none">
|
|
<doc xml:space="preserve">an ISO 8601 encoded date string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="time_" direction="out" caller-allocates="1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeVal</doc>
|
|
<type name="TimeVal" c:type="GTimeVal*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<record name="TimeZone" c:type="GTimeZone" version="2.26" glib:type-name="GTimeZone" glib:get-type="g_time_zone_get_type" c:symbol-prefix="time_zone">
|
|
<doc xml:space="preserve">#GTimeZone is an opaque structure whose members cannot be accessed
|
|
directly.</doc>
|
|
<constructor name="new" c:identifier="g_time_zone_new" version="2.26">
|
|
<doc xml:space="preserve">Creates a #GTimeZone corresponding to @identifier.
|
|
|
|
@identifier can either be an RFC3339/ISO 8601 time offset or
|
|
something that would pass as a valid value for the `TZ` environment
|
|
variable (including %NULL).
|
|
|
|
In Windows, @identifier can also be the unlocalized name of a time
|
|
zone for standard time, for example "Pacific Standard Time".
|
|
|
|
Valid RFC3339 time offsets are `"Z"` (for UTC) or
|
|
`"±hh:mm"`. ISO 8601 additionally specifies
|
|
`"±hhmm"` and `"±hh"`. Offsets are
|
|
time values to be added to Coordinated Universal Time (UTC) to get
|
|
the local time.
|
|
|
|
In UNIX, the `TZ` environment variable typically corresponds
|
|
to the name of a file in the zoneinfo database, an absolute path to a file
|
|
somewhere else, or a string in
|
|
"std offset [dst [offset],start[/time],end[/time]]" (POSIX) format.
|
|
There are no spaces in the specification. The name of standard
|
|
and daylight savings time zone must be three or more alphabetic
|
|
characters. Offsets are time values to be added to local time to
|
|
get Coordinated Universal Time (UTC) and should be
|
|
`"[±]hh[[:]mm[:ss]]"`. Dates are either
|
|
`"Jn"` (Julian day with n between 1 and 365, leap
|
|
years not counted), `"n"` (zero-based Julian day
|
|
with n between 0 and 365) or `"Mm.w.d"` (day d
|
|
(0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day
|
|
0 is a Sunday). Times are in local wall clock time, the default is
|
|
02:00:00.
|
|
|
|
In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also
|
|
accepts POSIX format. The Windows format uses US rules for all time
|
|
zones; daylight savings time is 60 minutes behind the standard time
|
|
with date and time of change taken from Pacific Standard Time.
|
|
Offsets are time values to be added to the local time to get
|
|
Coordinated Universal Time (UTC).
|
|
|
|
g_time_zone_new_local() calls this function with the value of the
|
|
`TZ` environment variable. This function itself is independent of
|
|
the value of `TZ`, but if @identifier is %NULL then `/etc/localtime`
|
|
will be consulted to discover the correct time zone on UNIX and the
|
|
registry will be consulted or GetTimeZoneInformation() will be used
|
|
to get the local time zone on Windows.
|
|
|
|
If intervals are not available, only time zone rules from `TZ`
|
|
environment variable or other means, then they will be computed
|
|
from year 1900 to 2037. If the maximum year for the rules is
|
|
available and it is greater than 2037, then it will followed
|
|
instead.
|
|
|
|
See
|
|
[RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6)
|
|
for a precise definition of valid RFC3339 time offsets
|
|
(the `time-offset` expansion) and ISO 8601 for the
|
|
full list of valid time offsets. See
|
|
[The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html)
|
|
for an explanation of the possible
|
|
values of the `TZ` environment variable. See
|
|
[Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx)
|
|
for the list of time zones on Windows.
|
|
|
|
You should release the return value by calling g_time_zone_unref()
|
|
when you are done with it.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the requested timezone</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="identifier" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a timezone identifier</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_local" c:identifier="g_time_zone_new_local" version="2.26">
|
|
<doc xml:space="preserve">Creates a #GTimeZone corresponding to local time. The local time
|
|
zone may change between invocations to this function; for example,
|
|
if the system administrator changes it.
|
|
|
|
This is equivalent to calling g_time_zone_new() with the value of
|
|
the `TZ` environment variable (including the possibility of %NULL).
|
|
|
|
You should release the return value by calling g_time_zone_unref()
|
|
when you are done with it.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the local timezone</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</return-value>
|
|
</constructor>
|
|
<constructor name="new_offset" c:identifier="g_time_zone_new_offset" version="2.58">
|
|
<doc xml:space="preserve">Creates a #GTimeZone corresponding to the given constant offset from UTC,
|
|
in seconds.
|
|
|
|
This is equivalent to calling g_time_zone_new() with a string in the form
|
|
`[+|-]hh[:mm[:ss]]`.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a timezone at the given offset from UTC</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="seconds" transfer-ownership="none">
|
|
<doc xml:space="preserve">offset to UTC, in seconds</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_utc" c:identifier="g_time_zone_new_utc" version="2.26">
|
|
<doc xml:space="preserve">Creates a #GTimeZone corresponding to UTC.
|
|
|
|
This is equivalent to calling g_time_zone_new() with a value like
|
|
"Z", "UTC", "+00", etc.
|
|
|
|
You should release the return value by calling g_time_zone_unref()
|
|
when you are done with it.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the universal timezone</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</return-value>
|
|
</constructor>
|
|
<method name="adjust_time" c:identifier="g_time_zone_adjust_time" version="2.26">
|
|
<doc xml:space="preserve">Finds an interval within @tz that corresponds to the given @time_,
|
|
possibly adjusting @time_ if required to fit into an interval.
|
|
The meaning of @time_ depends on @type.
|
|
|
|
This function is similar to g_time_zone_find_interval(), with the
|
|
difference that it always succeeds (by making the adjustments
|
|
described below).
|
|
|
|
In any of the cases where g_time_zone_find_interval() succeeds then
|
|
this function returns the same value, without modifying @time_.
|
|
|
|
This function may, however, modify @time_ in order to deal with
|
|
non-existent times. If the non-existent local @time_ of 02:30 were
|
|
requested on March 14th 2010 in Toronto then this function would
|
|
adjust @time_ to be 03:00 and return the interval containing the
|
|
adjusted time.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the interval containing @time_, never -1</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tz" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeZone</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</instance-parameter>
|
|
<parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GTimeType of @time_</doc>
|
|
<type name="TimeType" c:type="GTimeType"/>
|
|
</parameter>
|
|
<parameter name="time_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a number of seconds since January 1, 1970</doc>
|
|
<type name="gint64" c:type="gint64*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="find_interval" c:identifier="g_time_zone_find_interval" version="2.26">
|
|
<doc xml:space="preserve">Finds an interval within @tz that corresponds to the given @time_.
|
|
The meaning of @time_ depends on @type.
|
|
|
|
If @type is %G_TIME_TYPE_UNIVERSAL then this function will always
|
|
succeed (since universal time is monotonic and continuous).
|
|
|
|
Otherwise @time_ is treated as local time. The distinction between
|
|
%G_TIME_TYPE_STANDARD and %G_TIME_TYPE_DAYLIGHT is ignored except in
|
|
the case that the given @time_ is ambiguous. In Toronto, for example,
|
|
01:30 on November 7th 2010 occurred twice (once inside of daylight
|
|
savings time and the next, an hour later, outside of daylight savings
|
|
time). In this case, the different value of @type would result in a
|
|
different interval being returned.
|
|
|
|
It is still possible for this function to fail. In Toronto, for
|
|
example, 02:00 on March 14th 2010 does not exist (due to the leap
|
|
forward to begin daylight savings time). -1 is returned in that
|
|
case.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the interval containing @time_, or -1 in case of failure</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tz" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeZone</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</instance-parameter>
|
|
<parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GTimeType of @time_</doc>
|
|
<type name="TimeType" c:type="GTimeType"/>
|
|
</parameter>
|
|
<parameter name="time_" transfer-ownership="none">
|
|
<doc xml:space="preserve">a number of seconds since January 1, 1970</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_abbreviation" c:identifier="g_time_zone_get_abbreviation" version="2.26">
|
|
<doc xml:space="preserve">Determines the time zone abbreviation to be used during a particular
|
|
@interval of time in the time zone @tz.
|
|
|
|
For example, in Toronto this is currently "EST" during the winter
|
|
months and "EDT" during the summer months when daylight savings time
|
|
is in effect.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the time zone abbreviation, which belongs to @tz</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tz" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeZone</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</instance-parameter>
|
|
<parameter name="interval" transfer-ownership="none">
|
|
<doc xml:space="preserve">an interval within the timezone</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_identifier" c:identifier="g_time_zone_get_identifier" version="2.58">
|
|
<doc xml:space="preserve">Get the identifier of this #GTimeZone, as passed to g_time_zone_new().
|
|
If the identifier passed at construction time was not recognised, `UTC` will
|
|
be returned. If it was %NULL, the identifier of the local timezone at
|
|
construction time will be returned.
|
|
|
|
The identifier will be returned in the same format as provided at
|
|
construction time: if provided as a time offset, that will be returned by
|
|
this function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">identifier for this timezone</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tz" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeZone</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_offset" c:identifier="g_time_zone_get_offset" version="2.26">
|
|
<doc xml:space="preserve">Determines the offset to UTC in effect during a particular @interval
|
|
of time in the time zone @tz.
|
|
|
|
The offset is the number of seconds that you add to UTC time to
|
|
arrive at local time for @tz (ie: negative numbers for time zones
|
|
west of GMT, positive numbers for east).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of seconds that should be added to UTC to get the
|
|
local time in @tz</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tz" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeZone</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</instance-parameter>
|
|
<parameter name="interval" transfer-ownership="none">
|
|
<doc xml:space="preserve">an interval within the timezone</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_dst" c:identifier="g_time_zone_is_dst" version="2.26">
|
|
<doc xml:space="preserve">Determines if daylight savings time is in effect during a particular
|
|
@interval of time in the time zone @tz.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if daylight savings time is in effect</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tz" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeZone</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</instance-parameter>
|
|
<parameter name="interval" transfer-ownership="none">
|
|
<doc xml:space="preserve">an interval within the timezone</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_time_zone_ref" version="2.26">
|
|
<doc xml:space="preserve">Increases the reference count on @tz.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new reference to @tz.</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tz" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeZone</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_time_zone_unref" version="2.26">
|
|
<doc xml:space="preserve">Decreases the reference count on @tz.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tz" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeZone</doc>
|
|
<type name="TimeZone" c:type="GTimeZone*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<record name="Timer" c:type="GTimer" disguised="1">
|
|
<doc xml:space="preserve">Opaque datatype that records a start time.</doc>
|
|
<method name="continue" c:identifier="g_timer_continue" version="2.4">
|
|
<doc xml:space="preserve">Resumes a timer that has previously been stopped with
|
|
g_timer_stop(). g_timer_stop() must be called before using this
|
|
function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="timer" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimer.</doc>
|
|
<type name="Timer" c:type="GTimer*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="destroy" c:identifier="g_timer_destroy">
|
|
<doc xml:space="preserve">Destroys a timer, freeing associated resources.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="timer" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimer to destroy.</doc>
|
|
<type name="Timer" c:type="GTimer*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="elapsed" c:identifier="g_timer_elapsed">
|
|
<doc xml:space="preserve">If @timer has been started but not stopped, obtains the time since
|
|
the timer was started. If @timer has been stopped, obtains the
|
|
elapsed time between the time it was started and the time it was
|
|
stopped. The return value is the number of seconds elapsed,
|
|
including any fractional part. The @microseconds out parameter is
|
|
essentially useless.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">seconds elapsed as a floating point value, including any
|
|
fractional part.</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="timer" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimer.</doc>
|
|
<type name="Timer" c:type="GTimer*"/>
|
|
</instance-parameter>
|
|
<parameter name="microseconds" transfer-ownership="none">
|
|
<doc xml:space="preserve">return location for the fractional part of seconds
|
|
elapsed, in microseconds (that is, the total number
|
|
of microseconds elapsed, modulo 1000000), or %NULL</doc>
|
|
<type name="gulong" c:type="gulong*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_active" c:identifier="g_timer_is_active" version="2.62">
|
|
<doc xml:space="preserve">Exposes whether the timer is currently active.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the timer is running, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="timer" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimer.</doc>
|
|
<type name="Timer" c:type="GTimer*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="reset" c:identifier="g_timer_reset">
|
|
<doc xml:space="preserve">This function is useless; it's fine to call g_timer_start() on an
|
|
already-started timer to reset the start time, so g_timer_reset()
|
|
serves no purpose.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="timer" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimer.</doc>
|
|
<type name="Timer" c:type="GTimer*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="start" c:identifier="g_timer_start">
|
|
<doc xml:space="preserve">Marks a start time, so that future calls to g_timer_elapsed() will
|
|
report the time since g_timer_start() was called. g_timer_new()
|
|
automatically marks the start time, so no need to call
|
|
g_timer_start() immediately after creating the timer.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="timer" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimer.</doc>
|
|
<type name="Timer" c:type="GTimer*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="stop" c:identifier="g_timer_stop">
|
|
<doc xml:space="preserve">Marks an end time, so calls to g_timer_elapsed() will return the
|
|
difference between this end time and the start time.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="timer" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimer.</doc>
|
|
<type name="Timer" c:type="GTimer*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="new" c:identifier="g_timer_new" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new timer, and starts timing (i.e. g_timer_start() is
|
|
implicitly called for you).</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a new #GTimer.</doc>
|
|
<type name="Timer" c:type="GTimer*"/>
|
|
</return-value>
|
|
</function>
|
|
</record>
|
|
<enumeration name="TokenType" c:type="GTokenType">
|
|
<doc xml:space="preserve">The possible types of token returned from each
|
|
g_scanner_get_next_token() call.</doc>
|
|
<member name="eof" value="0" c:identifier="G_TOKEN_EOF">
|
|
<doc xml:space="preserve">the end of the file</doc>
|
|
</member>
|
|
<member name="left_paren" value="40" c:identifier="G_TOKEN_LEFT_PAREN">
|
|
<doc xml:space="preserve">a '(' character</doc>
|
|
</member>
|
|
<member name="right_paren" value="41" c:identifier="G_TOKEN_RIGHT_PAREN">
|
|
<doc xml:space="preserve">a ')' character</doc>
|
|
</member>
|
|
<member name="left_curly" value="123" c:identifier="G_TOKEN_LEFT_CURLY">
|
|
<doc xml:space="preserve">a '{' character</doc>
|
|
</member>
|
|
<member name="right_curly" value="125" c:identifier="G_TOKEN_RIGHT_CURLY">
|
|
<doc xml:space="preserve">a '}' character</doc>
|
|
</member>
|
|
<member name="left_brace" value="91" c:identifier="G_TOKEN_LEFT_BRACE">
|
|
<doc xml:space="preserve">a '[' character</doc>
|
|
</member>
|
|
<member name="right_brace" value="93" c:identifier="G_TOKEN_RIGHT_BRACE">
|
|
<doc xml:space="preserve">a ']' character</doc>
|
|
</member>
|
|
<member name="equal_sign" value="61" c:identifier="G_TOKEN_EQUAL_SIGN">
|
|
<doc xml:space="preserve">a '=' character</doc>
|
|
</member>
|
|
<member name="comma" value="44" c:identifier="G_TOKEN_COMMA">
|
|
<doc xml:space="preserve">a ',' character</doc>
|
|
</member>
|
|
<member name="none" value="256" c:identifier="G_TOKEN_NONE">
|
|
<doc xml:space="preserve">not a token</doc>
|
|
</member>
|
|
<member name="error" value="257" c:identifier="G_TOKEN_ERROR">
|
|
<doc xml:space="preserve">an error occurred</doc>
|
|
</member>
|
|
<member name="char" value="258" c:identifier="G_TOKEN_CHAR">
|
|
<doc xml:space="preserve">a character</doc>
|
|
</member>
|
|
<member name="binary" value="259" c:identifier="G_TOKEN_BINARY">
|
|
<doc xml:space="preserve">a binary integer</doc>
|
|
</member>
|
|
<member name="octal" value="260" c:identifier="G_TOKEN_OCTAL">
|
|
<doc xml:space="preserve">an octal integer</doc>
|
|
</member>
|
|
<member name="int" value="261" c:identifier="G_TOKEN_INT">
|
|
<doc xml:space="preserve">an integer</doc>
|
|
</member>
|
|
<member name="hex" value="262" c:identifier="G_TOKEN_HEX">
|
|
<doc xml:space="preserve">a hex integer</doc>
|
|
</member>
|
|
<member name="float" value="263" c:identifier="G_TOKEN_FLOAT">
|
|
<doc xml:space="preserve">a floating point number</doc>
|
|
</member>
|
|
<member name="string" value="264" c:identifier="G_TOKEN_STRING">
|
|
<doc xml:space="preserve">a string</doc>
|
|
</member>
|
|
<member name="symbol" value="265" c:identifier="G_TOKEN_SYMBOL">
|
|
<doc xml:space="preserve">a symbol</doc>
|
|
</member>
|
|
<member name="identifier" value="266" c:identifier="G_TOKEN_IDENTIFIER">
|
|
<doc xml:space="preserve">an identifier</doc>
|
|
</member>
|
|
<member name="identifier_null" value="267" c:identifier="G_TOKEN_IDENTIFIER_NULL">
|
|
<doc xml:space="preserve">a null identifier</doc>
|
|
</member>
|
|
<member name="comment_single" value="268" c:identifier="G_TOKEN_COMMENT_SINGLE">
|
|
<doc xml:space="preserve">one line comment</doc>
|
|
</member>
|
|
<member name="comment_multi" value="269" c:identifier="G_TOKEN_COMMENT_MULTI">
|
|
<doc xml:space="preserve">multi line comment</doc>
|
|
</member>
|
|
</enumeration>
|
|
<union name="TokenValue" c:type="GTokenValue">
|
|
<doc xml:space="preserve">A union holding the value of the token.</doc>
|
|
<field name="v_symbol" writable="1">
|
|
<doc xml:space="preserve">token symbol value</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="v_identifier" writable="1">
|
|
<doc xml:space="preserve">token identifier value</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</field>
|
|
<field name="v_binary" writable="1">
|
|
<doc xml:space="preserve">token binary integer value</doc>
|
|
<type name="gulong" c:type="gulong"/>
|
|
</field>
|
|
<field name="v_octal" writable="1">
|
|
<doc xml:space="preserve">octal integer value</doc>
|
|
<type name="gulong" c:type="gulong"/>
|
|
</field>
|
|
<field name="v_int" writable="1">
|
|
<doc xml:space="preserve">integer value</doc>
|
|
<type name="gulong" c:type="gulong"/>
|
|
</field>
|
|
<field name="v_int64" writable="1">
|
|
<doc xml:space="preserve">64-bit integer value</doc>
|
|
<type name="guint64" c:type="guint64"/>
|
|
</field>
|
|
<field name="v_float" writable="1">
|
|
<doc xml:space="preserve">floating point value</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</field>
|
|
<field name="v_hex" writable="1">
|
|
<doc xml:space="preserve">hex integer value</doc>
|
|
<type name="gulong" c:type="gulong"/>
|
|
</field>
|
|
<field name="v_string" writable="1">
|
|
<doc xml:space="preserve">string value</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</field>
|
|
<field name="v_comment" writable="1">
|
|
<doc xml:space="preserve">comment value</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</field>
|
|
<field name="v_char" writable="1">
|
|
<doc xml:space="preserve">character value</doc>
|
|
<type name="guint8" c:type="guchar"/>
|
|
</field>
|
|
<field name="v_error" writable="1">
|
|
<doc xml:space="preserve">error value</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</field>
|
|
</union>
|
|
<callback name="TranslateFunc" c:type="GTranslateFunc">
|
|
<doc xml:space="preserve">The type of functions which are used to translate user-visible
|
|
strings, for <option>--help</option> output.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a translation of the string for the current locale.
|
|
The returned string is owned by GLib and must not be freed.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">the untranslated string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data specified when installing the function, e.g.
|
|
in g_option_group_set_translate_func()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<record name="TrashStack" c:type="GTrashStack" deprecated="1" deprecated-version="2.48">
|
|
<doc xml:space="preserve">Each piece of memory that is pushed onto the stack
|
|
is cast to a GTrashStack*.</doc>
|
|
<doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated>
|
|
<field name="next" writable="1">
|
|
<doc xml:space="preserve">pointer to the previous element of the stack,
|
|
gets stored in the first `sizeof (gpointer)`
|
|
bytes of the element</doc>
|
|
<type name="TrashStack" c:type="GTrashStack*"/>
|
|
</field>
|
|
<function name="height" c:identifier="g_trash_stack_height" deprecated="1" deprecated-version="2.48">
|
|
<doc xml:space="preserve">Returns the height of a #GTrashStack.
|
|
|
|
Note that execution of this function is of O(N) complexity
|
|
where N denotes the number of items on the stack.</doc>
|
|
<doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the height of the stack</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="stack_p" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTrashStack</doc>
|
|
<type name="TrashStack" c:type="GTrashStack**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="peek" c:identifier="g_trash_stack_peek" deprecated="1" deprecated-version="2.48">
|
|
<doc xml:space="preserve">Returns the element at the top of a #GTrashStack
|
|
which may be %NULL.</doc>
|
|
<doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the element at the top of the stack</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="stack_p" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTrashStack</doc>
|
|
<type name="TrashStack" c:type="GTrashStack**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="pop" c:identifier="g_trash_stack_pop" deprecated="1" deprecated-version="2.48">
|
|
<doc xml:space="preserve">Pops a piece of memory off a #GTrashStack.</doc>
|
|
<doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the element at the top of the stack</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="stack_p" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTrashStack</doc>
|
|
<type name="TrashStack" c:type="GTrashStack**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="push" c:identifier="g_trash_stack_push" deprecated="1" deprecated-version="2.48">
|
|
<doc xml:space="preserve">Pushes a piece of memory onto a #GTrashStack.</doc>
|
|
<doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="stack_p" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTrashStack</doc>
|
|
<type name="TrashStack" c:type="GTrashStack**"/>
|
|
</parameter>
|
|
<parameter name="data_p" transfer-ownership="none">
|
|
<doc xml:space="preserve">the piece of memory to push on the stack</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<bitfield name="TraverseFlags" c:type="GTraverseFlags">
|
|
<doc xml:space="preserve">Specifies which nodes are visited during several of the tree
|
|
functions, including g_node_traverse() and g_node_find().</doc>
|
|
<member name="leaves" value="1" c:identifier="G_TRAVERSE_LEAVES">
|
|
<doc xml:space="preserve">only leaf nodes should be visited. This name has
|
|
been introduced in 2.6, for older version use
|
|
%G_TRAVERSE_LEAFS.</doc>
|
|
</member>
|
|
<member name="non_leaves" value="2" c:identifier="G_TRAVERSE_NON_LEAVES">
|
|
<doc xml:space="preserve">only non-leaf nodes should be visited. This
|
|
name has been introduced in 2.6, for older
|
|
version use %G_TRAVERSE_NON_LEAFS.</doc>
|
|
</member>
|
|
<member name="all" value="3" c:identifier="G_TRAVERSE_ALL">
|
|
<doc xml:space="preserve">all nodes should be visited.</doc>
|
|
</member>
|
|
<member name="mask" value="3" c:identifier="G_TRAVERSE_MASK">
|
|
<doc xml:space="preserve">a mask of all traverse flags.</doc>
|
|
</member>
|
|
<member name="leafs" value="1" c:identifier="G_TRAVERSE_LEAFS">
|
|
<doc xml:space="preserve">identical to %G_TRAVERSE_LEAVES.</doc>
|
|
</member>
|
|
<member name="non_leafs" value="2" c:identifier="G_TRAVERSE_NON_LEAFS">
|
|
<doc xml:space="preserve">identical to %G_TRAVERSE_NON_LEAVES.</doc>
|
|
</member>
|
|
</bitfield>
|
|
<callback name="TraverseFunc" c:type="GTraverseFunc">
|
|
<doc xml:space="preserve">Specifies the type of function passed to g_tree_traverse(). It is
|
|
passed the key and value of each node, together with the @user_data
|
|
parameter passed to g_tree_traverse(). If the function returns
|
|
%TRUE, the traversal is stopped.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE to stop the traversal</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a key of a #GTree node</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the value corresponding to the key</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to g_tree_traverse()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<enumeration name="TraverseType" c:type="GTraverseType">
|
|
<doc xml:space="preserve">Specifies the type of traversal performed by g_tree_traverse(),
|
|
g_node_traverse() and g_node_find(). The different orders are
|
|
illustrated here:
|
|
- In order: A, B, C, D, E, F, G, H, I
|
|
|
|
- Pre order: F, B, A, D, C, E, G, I, H
|
|
|
|
- Post order: A, C, E, D, B, H, I, G, F
|
|
|
|
- Level order: F, B, G, A, D, I, C, E, H
|
|
</doc>
|
|
<member name="in_order" value="0" c:identifier="G_IN_ORDER">
|
|
<doc xml:space="preserve">vists a node's left child first, then the node itself,
|
|
then its right child. This is the one to use if you
|
|
want the output sorted according to the compare
|
|
function.</doc>
|
|
</member>
|
|
<member name="pre_order" value="1" c:identifier="G_PRE_ORDER">
|
|
<doc xml:space="preserve">visits a node, then its children.</doc>
|
|
</member>
|
|
<member name="post_order" value="2" c:identifier="G_POST_ORDER">
|
|
<doc xml:space="preserve">visits the node's children, then the node itself.</doc>
|
|
</member>
|
|
<member name="level_order" value="3" c:identifier="G_LEVEL_ORDER">
|
|
<doc xml:space="preserve">is not implemented for
|
|
[balanced binary trees][glib-Balanced-Binary-Trees].
|
|
For [n-ary trees][glib-N-ary-Trees], it
|
|
vists the root node first, then its children, then
|
|
its grandchildren, and so on. Note that this is less
|
|
efficient than the other orders.</doc>
|
|
</member>
|
|
</enumeration>
|
|
<record name="Tree" c:type="GTree" disguised="1">
|
|
<doc xml:space="preserve">The GTree struct is an opaque data structure representing a
|
|
[balanced binary tree][glib-Balanced-Binary-Trees]. It should be
|
|
accessed only by using the following functions.</doc>
|
|
<method name="destroy" c:identifier="g_tree_destroy">
|
|
<doc xml:space="preserve">Removes all keys and values from the #GTree and decreases its
|
|
reference count by one. If keys and/or values are dynamically
|
|
allocated, you should either free them first or create the #GTree
|
|
using g_tree_new_full(). In the latter case the destroy functions
|
|
you supplied will be called on all keys and values before destroying
|
|
the #GTree.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tree" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="foreach" c:identifier="g_tree_foreach" introspectable="0">
|
|
<doc xml:space="preserve">Calls the given function for each of the key/value pairs in the #GTree.
|
|
The function is passed the key and value of each pair, and the given
|
|
@data parameter. The tree is traversed in sorted order.
|
|
|
|
The tree may not be modified while iterating over it (you can't
|
|
add/remove items). To remove all items matching a predicate, you need
|
|
to add each item to a list in your #GTraverseFunc as you walk over
|
|
the tree, then walk the list and remove each item.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tree" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</instance-parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="1">
|
|
<doc xml:space="preserve">the function to call for each node visited.
|
|
If this function returns %TRUE, the traversal is stopped.</doc>
|
|
<type name="TraverseFunc" c:type="GTraverseFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to the function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="height" c:identifier="g_tree_height">
|
|
<doc xml:space="preserve">Gets the height of a #GTree.
|
|
|
|
If the #GTree contains no nodes, the height is 0.
|
|
If the #GTree contains only one root node the height is 1.
|
|
If the root node has children the height is 2, etc.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the height of @tree</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tree" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert" c:identifier="g_tree_insert">
|
|
<doc xml:space="preserve">Inserts a key/value pair into a #GTree.
|
|
|
|
If the given key already exists in the #GTree its corresponding value
|
|
is set to the new value. If you supplied a @value_destroy_func when
|
|
creating the #GTree, the old value is freed using that function. If
|
|
you supplied a @key_destroy_func when creating the #GTree, the passed
|
|
key is freed using that function.
|
|
|
|
The tree is automatically 'balanced' as new key/value pairs are added,
|
|
so that the distance from the root to every leaf is as small as possible.
|
|
The cost of maintaining a balanced tree while inserting new key/value
|
|
result in a O(n log(n)) operation where most of the other operations
|
|
are O(log(n)).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tree" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</instance-parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the key to insert</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the value corresponding to the key</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="lookup" c:identifier="g_tree_lookup">
|
|
<doc xml:space="preserve">Gets the value corresponding to the given key. Since a #GTree is
|
|
automatically balanced as key/value pairs are added, key lookup
|
|
is O(log n) (where n is the number of key/value pairs in the tree).</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the value corresponding to the key, or %NULL
|
|
if the key was not found</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tree" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</instance-parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the key to look up</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="lookup_extended" c:identifier="g_tree_lookup_extended">
|
|
<doc xml:space="preserve">Looks up a key in the #GTree, returning the original key and the
|
|
associated value. This is useful if you need to free the memory
|
|
allocated for the original key, for example before calling
|
|
g_tree_remove().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key was found in the #GTree</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tree" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</instance-parameter>
|
|
<parameter name="lookup_key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the key to look up</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="orig_key" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">returns the original key</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</parameter>
|
|
<parameter name="value" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">returns the value associated with the key</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="nnodes" c:identifier="g_tree_nnodes">
|
|
<doc xml:space="preserve">Gets the number of nodes in a #GTree.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of nodes in @tree</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tree" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_tree_ref" version="2.22" introspectable="0">
|
|
<doc xml:space="preserve">Increments the reference count of @tree by one.
|
|
|
|
It is safe to call this function from any thread.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the passed in #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tree" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="remove" c:identifier="g_tree_remove">
|
|
<doc xml:space="preserve">Removes a key/value pair from a #GTree.
|
|
|
|
If the #GTree was created using g_tree_new_full(), the key and value
|
|
are freed using the supplied destroy functions, otherwise you have to
|
|
make sure that any dynamically allocated values are freed yourself.
|
|
If the key does not exist in the #GTree, the function does nothing.
|
|
|
|
The cost of maintaining a balanced tree while removing a key/value
|
|
result in a O(n log(n)) operation where most of the other operations
|
|
are O(log(n)).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key was found (prior to 2.8, this function
|
|
returned nothing)</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tree" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</instance-parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the key to remove</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="replace" c:identifier="g_tree_replace">
|
|
<doc xml:space="preserve">Inserts a new key and value into a #GTree similar to g_tree_insert().
|
|
The difference is that if the key already exists in the #GTree, it gets
|
|
replaced by the new key. If you supplied a @value_destroy_func when
|
|
creating the #GTree, the old value is freed using that function. If you
|
|
supplied a @key_destroy_func when creating the #GTree, the old key is
|
|
freed using that function.
|
|
|
|
The tree is automatically 'balanced' as new key/value pairs are added,
|
|
so that the distance from the root to every leaf is as small as possible.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tree" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</instance-parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the key to insert</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the value corresponding to the key</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="search" c:identifier="g_tree_search" introspectable="0">
|
|
<doc xml:space="preserve">Searches a #GTree using @search_func.
|
|
|
|
The @search_func is called with a pointer to the key of a key/value
|
|
pair in the tree, and the passed in @user_data. If @search_func returns
|
|
0 for a key/value pair, then the corresponding value is returned as
|
|
the result of g_tree_search(). If @search_func returns -1, searching
|
|
will proceed among the key/value pairs that have a smaller key; if
|
|
@search_func returns 1, searching will proceed among the key/value
|
|
pairs that have a larger key.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the value corresponding to the found key, or %NULL
|
|
if the key was not found</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tree" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</instance-parameter>
|
|
<parameter name="search_func" transfer-ownership="none" closure="1">
|
|
<doc xml:space="preserve">a function used to search the #GTree</doc>
|
|
<type name="CompareFunc" c:type="GCompareFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data passed as the second argument to @search_func</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="steal" c:identifier="g_tree_steal">
|
|
<doc xml:space="preserve">Removes a key and its associated value from a #GTree without calling
|
|
the key and value destroy functions.
|
|
|
|
If the key does not exist in the #GTree, the function does nothing.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key was found (prior to 2.8, this function
|
|
returned nothing)</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tree" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</instance-parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the key to remove</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="traverse" c:identifier="g_tree_traverse" introspectable="0" deprecated="1" deprecated-version="2.2">
|
|
<doc xml:space="preserve">Calls the given function for each node in the #GTree.</doc>
|
|
<doc-deprecated xml:space="preserve">The order of a balanced tree is somewhat arbitrary.
|
|
If you just want to visit all nodes in sorted order, use
|
|
g_tree_foreach() instead. If you really need to visit nodes in
|
|
a different order, consider using an [n-ary tree][glib-N-ary-Trees].</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tree" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</instance-parameter>
|
|
<parameter name="traverse_func" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">the function to call for each node visited. If this
|
|
function returns %TRUE, the traversal is stopped.</doc>
|
|
<type name="TraverseFunc" c:type="GTraverseFunc"/>
|
|
</parameter>
|
|
<parameter name="traverse_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">the order in which nodes are visited, one of %G_IN_ORDER,
|
|
%G_PRE_ORDER and %G_POST_ORDER</doc>
|
|
<type name="TraverseType" c:type="GTraverseType"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to the function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_tree_unref" version="2.22">
|
|
<doc xml:space="preserve">Decrements the reference count of @tree by one.
|
|
If the reference count drops to 0, all keys and values will
|
|
be destroyed (if destroy functions were specified) and all
|
|
memory allocated by @tree will be released.
|
|
|
|
It is safe to call this function from any thread.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="tree" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="new" c:identifier="g_tree_new" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GTree.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a newly allocated #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="key_compare_func" transfer-ownership="none">
|
|
<doc xml:space="preserve">the function used to order the nodes in the #GTree.
|
|
It should return values similar to the standard strcmp() function -
|
|
0 if the two arguments are equal, a negative value if the first argument
|
|
comes before the second, or a positive value if the first argument comes
|
|
after the second.</doc>
|
|
<type name="CompareFunc" c:type="GCompareFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="new_full" c:identifier="g_tree_new_full" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GTree like g_tree_new() and allows to specify functions
|
|
to free the memory allocated for the key and value that get called when
|
|
removing the entry from the #GTree.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a newly allocated #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="key_compare_func" transfer-ownership="none" scope="notified" closure="1" destroy="3">
|
|
<doc xml:space="preserve">qsort()-style comparison function</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="key_compare_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to comparison function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="key_destroy_func" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">a function to free the memory allocated for the key
|
|
used when removing the entry from the #GTree or %NULL if you don't
|
|
want to supply such a function</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
<parameter name="value_destroy_func" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">a function to free the memory allocated for the
|
|
value used when removing the entry from the #GTree or %NULL if you
|
|
don't want to supply such a function</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="new_with_data" c:identifier="g_tree_new_with_data" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GTree with a comparison function that accepts user data.
|
|
See g_tree_new() for more details.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a newly allocated #GTree</doc>
|
|
<type name="Tree" c:type="GTree*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="key_compare_func" transfer-ownership="none" closure="1">
|
|
<doc xml:space="preserve">qsort()-style comparison function</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="key_compare_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to comparison function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<function-macro name="UNAVAILABLE" c:identifier="G_UNAVAILABLE" version="2.32" introspectable="0">
|
|
<doc xml:space="preserve">This macro can be used to mark a function declaration as unavailable.
|
|
It must be placed before the function declaration. Use of a function
|
|
that has been annotated with this macros will produce a compiler warning.</doc>
|
|
<parameters>
|
|
<parameter name="maj">
|
|
<doc xml:space="preserve">the major version that introduced the symbol</doc>
|
|
</parameter>
|
|
<parameter name="min">
|
|
<doc xml:space="preserve">the minor version that introduced the symbol</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="UNAVAILABLE_ENUMERATOR" c:identifier="GLIB_UNAVAILABLE_ENUMERATOR" introspectable="0">
|
|
<parameters>
|
|
<parameter name="maj">
|
|
</parameter>
|
|
<parameter name="min">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="UNAVAILABLE_MACRO" c:identifier="GLIB_UNAVAILABLE_MACRO" introspectable="0">
|
|
<parameters>
|
|
<parameter name="maj">
|
|
</parameter>
|
|
<parameter name="min">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="UNAVAILABLE_STATIC_INLINE" c:identifier="GLIB_UNAVAILABLE_STATIC_INLINE" introspectable="0">
|
|
<parameters>
|
|
<parameter name="maj">
|
|
</parameter>
|
|
<parameter name="min">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="UNAVAILABLE_TYPE" c:identifier="GLIB_UNAVAILABLE_TYPE" introspectable="0">
|
|
<parameters>
|
|
<parameter name="maj">
|
|
</parameter>
|
|
<parameter name="min">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="UNICHAR_MAX_DECOMPOSITION_LENGTH" value="18" c:type="G_UNICHAR_MAX_DECOMPOSITION_LENGTH" version="2.32">
|
|
<doc xml:space="preserve">The maximum length (in codepoints) of a compatibility or canonical
|
|
decomposition of a single Unicode character.
|
|
|
|
This is as defined by Unicode 6.1.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<function-macro name="UNLIKELY" c:identifier="G_UNLIKELY" version="2.2" introspectable="0">
|
|
<doc xml:space="preserve">Hints the compiler that the expression is unlikely to evaluate to
|
|
a true value. The compiler may use this information for optimizations.
|
|
|
|
|[<!-- language="C" -->
|
|
if (G_UNLIKELY (random () == 1))
|
|
g_print ("a random one");
|
|
]|</doc>
|
|
<parameters>
|
|
<parameter name="expr">
|
|
<doc xml:space="preserve">the expression</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="UNLOCK" c:identifier="G_UNLOCK" introspectable="0">
|
|
<doc xml:space="preserve">Works like g_mutex_unlock(), but for a lock defined with
|
|
#G_LOCK_DEFINE.</doc>
|
|
<parameters>
|
|
<parameter name="name">
|
|
<doc xml:space="preserve">the name of the lock</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="URI_RESERVED_CHARS_GENERIC_DELIMITERS" value=":/?#[]@" c:type="G_URI_RESERVED_CHARS_GENERIC_DELIMITERS" version="2.16">
|
|
<doc xml:space="preserve">Generic delimiters characters as defined in
|
|
[RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `:/?#[]@`.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS" value="!$&'()*+,;=" c:type="G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS" version="2.16">
|
|
<doc xml:space="preserve">Subcomponent delimiter characters as defined in
|
|
[RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `!$&'()*+,;=`.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</constant>
|
|
<constant name="USEC_PER_SEC" value="1000000" c:type="G_USEC_PER_SEC">
|
|
<doc xml:space="preserve">Number of microseconds in one second (1 million).
|
|
This macro is provided for code readability.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<enumeration name="UnicodeBreakType" c:type="GUnicodeBreakType">
|
|
<doc xml:space="preserve">These are the possible line break classifications.
|
|
|
|
Since new unicode versions may add new types here, applications should be ready
|
|
to handle unknown values. They may be regarded as %G_UNICODE_BREAK_UNKNOWN.
|
|
|
|
See [Unicode Line Breaking Algorithm](http://www.unicode.org/unicode/reports/tr14/).</doc>
|
|
<member name="mandatory" value="0" c:identifier="G_UNICODE_BREAK_MANDATORY">
|
|
<doc xml:space="preserve">Mandatory Break (BK)</doc>
|
|
</member>
|
|
<member name="carriage_return" value="1" c:identifier="G_UNICODE_BREAK_CARRIAGE_RETURN">
|
|
<doc xml:space="preserve">Carriage Return (CR)</doc>
|
|
</member>
|
|
<member name="line_feed" value="2" c:identifier="G_UNICODE_BREAK_LINE_FEED">
|
|
<doc xml:space="preserve">Line Feed (LF)</doc>
|
|
</member>
|
|
<member name="combining_mark" value="3" c:identifier="G_UNICODE_BREAK_COMBINING_MARK">
|
|
<doc xml:space="preserve">Attached Characters and Combining Marks (CM)</doc>
|
|
</member>
|
|
<member name="surrogate" value="4" c:identifier="G_UNICODE_BREAK_SURROGATE">
|
|
<doc xml:space="preserve">Surrogates (SG)</doc>
|
|
</member>
|
|
<member name="zero_width_space" value="5" c:identifier="G_UNICODE_BREAK_ZERO_WIDTH_SPACE">
|
|
<doc xml:space="preserve">Zero Width Space (ZW)</doc>
|
|
</member>
|
|
<member name="inseparable" value="6" c:identifier="G_UNICODE_BREAK_INSEPARABLE">
|
|
<doc xml:space="preserve">Inseparable (IN)</doc>
|
|
</member>
|
|
<member name="non_breaking_glue" value="7" c:identifier="G_UNICODE_BREAK_NON_BREAKING_GLUE">
|
|
<doc xml:space="preserve">Non-breaking ("Glue") (GL)</doc>
|
|
</member>
|
|
<member name="contingent" value="8" c:identifier="G_UNICODE_BREAK_CONTINGENT">
|
|
<doc xml:space="preserve">Contingent Break Opportunity (CB)</doc>
|
|
</member>
|
|
<member name="space" value="9" c:identifier="G_UNICODE_BREAK_SPACE">
|
|
<doc xml:space="preserve">Space (SP)</doc>
|
|
</member>
|
|
<member name="after" value="10" c:identifier="G_UNICODE_BREAK_AFTER">
|
|
<doc xml:space="preserve">Break Opportunity After (BA)</doc>
|
|
</member>
|
|
<member name="before" value="11" c:identifier="G_UNICODE_BREAK_BEFORE">
|
|
<doc xml:space="preserve">Break Opportunity Before (BB)</doc>
|
|
</member>
|
|
<member name="before_and_after" value="12" c:identifier="G_UNICODE_BREAK_BEFORE_AND_AFTER">
|
|
<doc xml:space="preserve">Break Opportunity Before and After (B2)</doc>
|
|
</member>
|
|
<member name="hyphen" value="13" c:identifier="G_UNICODE_BREAK_HYPHEN">
|
|
<doc xml:space="preserve">Hyphen (HY)</doc>
|
|
</member>
|
|
<member name="non_starter" value="14" c:identifier="G_UNICODE_BREAK_NON_STARTER">
|
|
<doc xml:space="preserve">Nonstarter (NS)</doc>
|
|
</member>
|
|
<member name="open_punctuation" value="15" c:identifier="G_UNICODE_BREAK_OPEN_PUNCTUATION">
|
|
<doc xml:space="preserve">Opening Punctuation (OP)</doc>
|
|
</member>
|
|
<member name="close_punctuation" value="16" c:identifier="G_UNICODE_BREAK_CLOSE_PUNCTUATION">
|
|
<doc xml:space="preserve">Closing Punctuation (CL)</doc>
|
|
</member>
|
|
<member name="quotation" value="17" c:identifier="G_UNICODE_BREAK_QUOTATION">
|
|
<doc xml:space="preserve">Ambiguous Quotation (QU)</doc>
|
|
</member>
|
|
<member name="exclamation" value="18" c:identifier="G_UNICODE_BREAK_EXCLAMATION">
|
|
<doc xml:space="preserve">Exclamation/Interrogation (EX)</doc>
|
|
</member>
|
|
<member name="ideographic" value="19" c:identifier="G_UNICODE_BREAK_IDEOGRAPHIC">
|
|
<doc xml:space="preserve">Ideographic (ID)</doc>
|
|
</member>
|
|
<member name="numeric" value="20" c:identifier="G_UNICODE_BREAK_NUMERIC">
|
|
<doc xml:space="preserve">Numeric (NU)</doc>
|
|
</member>
|
|
<member name="infix_separator" value="21" c:identifier="G_UNICODE_BREAK_INFIX_SEPARATOR">
|
|
<doc xml:space="preserve">Infix Separator (Numeric) (IS)</doc>
|
|
</member>
|
|
<member name="symbol" value="22" c:identifier="G_UNICODE_BREAK_SYMBOL">
|
|
<doc xml:space="preserve">Symbols Allowing Break After (SY)</doc>
|
|
</member>
|
|
<member name="alphabetic" value="23" c:identifier="G_UNICODE_BREAK_ALPHABETIC">
|
|
<doc xml:space="preserve">Ordinary Alphabetic and Symbol Characters (AL)</doc>
|
|
</member>
|
|
<member name="prefix" value="24" c:identifier="G_UNICODE_BREAK_PREFIX">
|
|
<doc xml:space="preserve">Prefix (Numeric) (PR)</doc>
|
|
</member>
|
|
<member name="postfix" value="25" c:identifier="G_UNICODE_BREAK_POSTFIX">
|
|
<doc xml:space="preserve">Postfix (Numeric) (PO)</doc>
|
|
</member>
|
|
<member name="complex_context" value="26" c:identifier="G_UNICODE_BREAK_COMPLEX_CONTEXT">
|
|
<doc xml:space="preserve">Complex Content Dependent (South East Asian) (SA)</doc>
|
|
</member>
|
|
<member name="ambiguous" value="27" c:identifier="G_UNICODE_BREAK_AMBIGUOUS">
|
|
<doc xml:space="preserve">Ambiguous (Alphabetic or Ideographic) (AI)</doc>
|
|
</member>
|
|
<member name="unknown" value="28" c:identifier="G_UNICODE_BREAK_UNKNOWN">
|
|
<doc xml:space="preserve">Unknown (XX)</doc>
|
|
</member>
|
|
<member name="next_line" value="29" c:identifier="G_UNICODE_BREAK_NEXT_LINE">
|
|
<doc xml:space="preserve">Next Line (NL)</doc>
|
|
</member>
|
|
<member name="word_joiner" value="30" c:identifier="G_UNICODE_BREAK_WORD_JOINER">
|
|
<doc xml:space="preserve">Word Joiner (WJ)</doc>
|
|
</member>
|
|
<member name="hangul_l_jamo" value="31" c:identifier="G_UNICODE_BREAK_HANGUL_L_JAMO">
|
|
<doc xml:space="preserve">Hangul L Jamo (JL)</doc>
|
|
</member>
|
|
<member name="hangul_v_jamo" value="32" c:identifier="G_UNICODE_BREAK_HANGUL_V_JAMO">
|
|
<doc xml:space="preserve">Hangul V Jamo (JV)</doc>
|
|
</member>
|
|
<member name="hangul_t_jamo" value="33" c:identifier="G_UNICODE_BREAK_HANGUL_T_JAMO">
|
|
<doc xml:space="preserve">Hangul T Jamo (JT)</doc>
|
|
</member>
|
|
<member name="hangul_lv_syllable" value="34" c:identifier="G_UNICODE_BREAK_HANGUL_LV_SYLLABLE">
|
|
<doc xml:space="preserve">Hangul LV Syllable (H2)</doc>
|
|
</member>
|
|
<member name="hangul_lvt_syllable" value="35" c:identifier="G_UNICODE_BREAK_HANGUL_LVT_SYLLABLE">
|
|
<doc xml:space="preserve">Hangul LVT Syllable (H3)</doc>
|
|
</member>
|
|
<member name="close_paranthesis" value="36" c:identifier="G_UNICODE_BREAK_CLOSE_PARANTHESIS">
|
|
<doc xml:space="preserve">Closing Parenthesis (CP). Since 2.28</doc>
|
|
</member>
|
|
<member name="conditional_japanese_starter" value="37" c:identifier="G_UNICODE_BREAK_CONDITIONAL_JAPANESE_STARTER">
|
|
<doc xml:space="preserve">Conditional Japanese Starter (CJ). Since: 2.32</doc>
|
|
</member>
|
|
<member name="hebrew_letter" value="38" c:identifier="G_UNICODE_BREAK_HEBREW_LETTER">
|
|
<doc xml:space="preserve">Hebrew Letter (HL). Since: 2.32</doc>
|
|
</member>
|
|
<member name="regional_indicator" value="39" c:identifier="G_UNICODE_BREAK_REGIONAL_INDICATOR">
|
|
<doc xml:space="preserve">Regional Indicator (RI). Since: 2.36</doc>
|
|
</member>
|
|
<member name="emoji_base" value="40" c:identifier="G_UNICODE_BREAK_EMOJI_BASE">
|
|
<doc xml:space="preserve">Emoji Base (EB). Since: 2.50</doc>
|
|
</member>
|
|
<member name="emoji_modifier" value="41" c:identifier="G_UNICODE_BREAK_EMOJI_MODIFIER">
|
|
<doc xml:space="preserve">Emoji Modifier (EM). Since: 2.50</doc>
|
|
</member>
|
|
<member name="zero_width_joiner" value="42" c:identifier="G_UNICODE_BREAK_ZERO_WIDTH_JOINER">
|
|
<doc xml:space="preserve">Zero Width Joiner (ZWJ). Since: 2.50</doc>
|
|
</member>
|
|
</enumeration>
|
|
<enumeration name="UnicodeScript" c:type="GUnicodeScript">
|
|
<doc xml:space="preserve">The #GUnicodeScript enumeration identifies different writing
|
|
systems. The values correspond to the names as defined in the
|
|
Unicode standard. The enumeration has been added in GLib 2.14,
|
|
and is interchangeable with #PangoScript.
|
|
|
|
Note that new types may be added in the future. Applications
|
|
should be ready to handle unknown values.
|
|
See [Unicode Standard Annex #24: Script names](http://www.unicode.org/reports/tr24/).</doc>
|
|
<member name="invalid_code" value="-1" c:identifier="G_UNICODE_SCRIPT_INVALID_CODE">
|
|
<doc xml:space="preserve">a value never returned from g_unichar_get_script()</doc>
|
|
</member>
|
|
<member name="common" value="0" c:identifier="G_UNICODE_SCRIPT_COMMON">
|
|
<doc xml:space="preserve">a character used by multiple different scripts</doc>
|
|
</member>
|
|
<member name="inherited" value="1" c:identifier="G_UNICODE_SCRIPT_INHERITED">
|
|
<doc xml:space="preserve">a mark glyph that takes its script from the
|
|
base glyph to which it is attached</doc>
|
|
</member>
|
|
<member name="arabic" value="2" c:identifier="G_UNICODE_SCRIPT_ARABIC">
|
|
<doc xml:space="preserve">Arabic</doc>
|
|
</member>
|
|
<member name="armenian" value="3" c:identifier="G_UNICODE_SCRIPT_ARMENIAN">
|
|
<doc xml:space="preserve">Armenian</doc>
|
|
</member>
|
|
<member name="bengali" value="4" c:identifier="G_UNICODE_SCRIPT_BENGALI">
|
|
<doc xml:space="preserve">Bengali</doc>
|
|
</member>
|
|
<member name="bopomofo" value="5" c:identifier="G_UNICODE_SCRIPT_BOPOMOFO">
|
|
<doc xml:space="preserve">Bopomofo</doc>
|
|
</member>
|
|
<member name="cherokee" value="6" c:identifier="G_UNICODE_SCRIPT_CHEROKEE">
|
|
<doc xml:space="preserve">Cherokee</doc>
|
|
</member>
|
|
<member name="coptic" value="7" c:identifier="G_UNICODE_SCRIPT_COPTIC">
|
|
<doc xml:space="preserve">Coptic</doc>
|
|
</member>
|
|
<member name="cyrillic" value="8" c:identifier="G_UNICODE_SCRIPT_CYRILLIC">
|
|
<doc xml:space="preserve">Cyrillic</doc>
|
|
</member>
|
|
<member name="deseret" value="9" c:identifier="G_UNICODE_SCRIPT_DESERET">
|
|
<doc xml:space="preserve">Deseret</doc>
|
|
</member>
|
|
<member name="devanagari" value="10" c:identifier="G_UNICODE_SCRIPT_DEVANAGARI">
|
|
<doc xml:space="preserve">Devanagari</doc>
|
|
</member>
|
|
<member name="ethiopic" value="11" c:identifier="G_UNICODE_SCRIPT_ETHIOPIC">
|
|
<doc xml:space="preserve">Ethiopic</doc>
|
|
</member>
|
|
<member name="georgian" value="12" c:identifier="G_UNICODE_SCRIPT_GEORGIAN">
|
|
<doc xml:space="preserve">Georgian</doc>
|
|
</member>
|
|
<member name="gothic" value="13" c:identifier="G_UNICODE_SCRIPT_GOTHIC">
|
|
<doc xml:space="preserve">Gothic</doc>
|
|
</member>
|
|
<member name="greek" value="14" c:identifier="G_UNICODE_SCRIPT_GREEK">
|
|
<doc xml:space="preserve">Greek</doc>
|
|
</member>
|
|
<member name="gujarati" value="15" c:identifier="G_UNICODE_SCRIPT_GUJARATI">
|
|
<doc xml:space="preserve">Gujarati</doc>
|
|
</member>
|
|
<member name="gurmukhi" value="16" c:identifier="G_UNICODE_SCRIPT_GURMUKHI">
|
|
<doc xml:space="preserve">Gurmukhi</doc>
|
|
</member>
|
|
<member name="han" value="17" c:identifier="G_UNICODE_SCRIPT_HAN">
|
|
<doc xml:space="preserve">Han</doc>
|
|
</member>
|
|
<member name="hangul" value="18" c:identifier="G_UNICODE_SCRIPT_HANGUL">
|
|
<doc xml:space="preserve">Hangul</doc>
|
|
</member>
|
|
<member name="hebrew" value="19" c:identifier="G_UNICODE_SCRIPT_HEBREW">
|
|
<doc xml:space="preserve">Hebrew</doc>
|
|
</member>
|
|
<member name="hiragana" value="20" c:identifier="G_UNICODE_SCRIPT_HIRAGANA">
|
|
<doc xml:space="preserve">Hiragana</doc>
|
|
</member>
|
|
<member name="kannada" value="21" c:identifier="G_UNICODE_SCRIPT_KANNADA">
|
|
<doc xml:space="preserve">Kannada</doc>
|
|
</member>
|
|
<member name="katakana" value="22" c:identifier="G_UNICODE_SCRIPT_KATAKANA">
|
|
<doc xml:space="preserve">Katakana</doc>
|
|
</member>
|
|
<member name="khmer" value="23" c:identifier="G_UNICODE_SCRIPT_KHMER">
|
|
<doc xml:space="preserve">Khmer</doc>
|
|
</member>
|
|
<member name="lao" value="24" c:identifier="G_UNICODE_SCRIPT_LAO">
|
|
<doc xml:space="preserve">Lao</doc>
|
|
</member>
|
|
<member name="latin" value="25" c:identifier="G_UNICODE_SCRIPT_LATIN">
|
|
<doc xml:space="preserve">Latin</doc>
|
|
</member>
|
|
<member name="malayalam" value="26" c:identifier="G_UNICODE_SCRIPT_MALAYALAM">
|
|
<doc xml:space="preserve">Malayalam</doc>
|
|
</member>
|
|
<member name="mongolian" value="27" c:identifier="G_UNICODE_SCRIPT_MONGOLIAN">
|
|
<doc xml:space="preserve">Mongolian</doc>
|
|
</member>
|
|
<member name="myanmar" value="28" c:identifier="G_UNICODE_SCRIPT_MYANMAR">
|
|
<doc xml:space="preserve">Myanmar</doc>
|
|
</member>
|
|
<member name="ogham" value="29" c:identifier="G_UNICODE_SCRIPT_OGHAM">
|
|
<doc xml:space="preserve">Ogham</doc>
|
|
</member>
|
|
<member name="old_italic" value="30" c:identifier="G_UNICODE_SCRIPT_OLD_ITALIC">
|
|
<doc xml:space="preserve">Old Italic</doc>
|
|
</member>
|
|
<member name="oriya" value="31" c:identifier="G_UNICODE_SCRIPT_ORIYA">
|
|
<doc xml:space="preserve">Oriya</doc>
|
|
</member>
|
|
<member name="runic" value="32" c:identifier="G_UNICODE_SCRIPT_RUNIC">
|
|
<doc xml:space="preserve">Runic</doc>
|
|
</member>
|
|
<member name="sinhala" value="33" c:identifier="G_UNICODE_SCRIPT_SINHALA">
|
|
<doc xml:space="preserve">Sinhala</doc>
|
|
</member>
|
|
<member name="syriac" value="34" c:identifier="G_UNICODE_SCRIPT_SYRIAC">
|
|
<doc xml:space="preserve">Syriac</doc>
|
|
</member>
|
|
<member name="tamil" value="35" c:identifier="G_UNICODE_SCRIPT_TAMIL">
|
|
<doc xml:space="preserve">Tamil</doc>
|
|
</member>
|
|
<member name="telugu" value="36" c:identifier="G_UNICODE_SCRIPT_TELUGU">
|
|
<doc xml:space="preserve">Telugu</doc>
|
|
</member>
|
|
<member name="thaana" value="37" c:identifier="G_UNICODE_SCRIPT_THAANA">
|
|
<doc xml:space="preserve">Thaana</doc>
|
|
</member>
|
|
<member name="thai" value="38" c:identifier="G_UNICODE_SCRIPT_THAI">
|
|
<doc xml:space="preserve">Thai</doc>
|
|
</member>
|
|
<member name="tibetan" value="39" c:identifier="G_UNICODE_SCRIPT_TIBETAN">
|
|
<doc xml:space="preserve">Tibetan</doc>
|
|
</member>
|
|
<member name="canadian_aboriginal" value="40" c:identifier="G_UNICODE_SCRIPT_CANADIAN_ABORIGINAL">
|
|
<doc xml:space="preserve">Canadian Aboriginal</doc>
|
|
</member>
|
|
<member name="yi" value="41" c:identifier="G_UNICODE_SCRIPT_YI">
|
|
<doc xml:space="preserve">Yi</doc>
|
|
</member>
|
|
<member name="tagalog" value="42" c:identifier="G_UNICODE_SCRIPT_TAGALOG">
|
|
<doc xml:space="preserve">Tagalog</doc>
|
|
</member>
|
|
<member name="hanunoo" value="43" c:identifier="G_UNICODE_SCRIPT_HANUNOO">
|
|
<doc xml:space="preserve">Hanunoo</doc>
|
|
</member>
|
|
<member name="buhid" value="44" c:identifier="G_UNICODE_SCRIPT_BUHID">
|
|
<doc xml:space="preserve">Buhid</doc>
|
|
</member>
|
|
<member name="tagbanwa" value="45" c:identifier="G_UNICODE_SCRIPT_TAGBANWA">
|
|
<doc xml:space="preserve">Tagbanwa</doc>
|
|
</member>
|
|
<member name="braille" value="46" c:identifier="G_UNICODE_SCRIPT_BRAILLE">
|
|
<doc xml:space="preserve">Braille</doc>
|
|
</member>
|
|
<member name="cypriot" value="47" c:identifier="G_UNICODE_SCRIPT_CYPRIOT">
|
|
<doc xml:space="preserve">Cypriot</doc>
|
|
</member>
|
|
<member name="limbu" value="48" c:identifier="G_UNICODE_SCRIPT_LIMBU">
|
|
<doc xml:space="preserve">Limbu</doc>
|
|
</member>
|
|
<member name="osmanya" value="49" c:identifier="G_UNICODE_SCRIPT_OSMANYA">
|
|
<doc xml:space="preserve">Osmanya</doc>
|
|
</member>
|
|
<member name="shavian" value="50" c:identifier="G_UNICODE_SCRIPT_SHAVIAN">
|
|
<doc xml:space="preserve">Shavian</doc>
|
|
</member>
|
|
<member name="linear_b" value="51" c:identifier="G_UNICODE_SCRIPT_LINEAR_B">
|
|
<doc xml:space="preserve">Linear B</doc>
|
|
</member>
|
|
<member name="tai_le" value="52" c:identifier="G_UNICODE_SCRIPT_TAI_LE">
|
|
<doc xml:space="preserve">Tai Le</doc>
|
|
</member>
|
|
<member name="ugaritic" value="53" c:identifier="G_UNICODE_SCRIPT_UGARITIC">
|
|
<doc xml:space="preserve">Ugaritic</doc>
|
|
</member>
|
|
<member name="new_tai_lue" value="54" c:identifier="G_UNICODE_SCRIPT_NEW_TAI_LUE">
|
|
<doc xml:space="preserve">New Tai Lue</doc>
|
|
</member>
|
|
<member name="buginese" value="55" c:identifier="G_UNICODE_SCRIPT_BUGINESE">
|
|
<doc xml:space="preserve">Buginese</doc>
|
|
</member>
|
|
<member name="glagolitic" value="56" c:identifier="G_UNICODE_SCRIPT_GLAGOLITIC">
|
|
<doc xml:space="preserve">Glagolitic</doc>
|
|
</member>
|
|
<member name="tifinagh" value="57" c:identifier="G_UNICODE_SCRIPT_TIFINAGH">
|
|
<doc xml:space="preserve">Tifinagh</doc>
|
|
</member>
|
|
<member name="syloti_nagri" value="58" c:identifier="G_UNICODE_SCRIPT_SYLOTI_NAGRI">
|
|
<doc xml:space="preserve">Syloti Nagri</doc>
|
|
</member>
|
|
<member name="old_persian" value="59" c:identifier="G_UNICODE_SCRIPT_OLD_PERSIAN">
|
|
<doc xml:space="preserve">Old Persian</doc>
|
|
</member>
|
|
<member name="kharoshthi" value="60" c:identifier="G_UNICODE_SCRIPT_KHAROSHTHI">
|
|
<doc xml:space="preserve">Kharoshthi</doc>
|
|
</member>
|
|
<member name="unknown" value="61" c:identifier="G_UNICODE_SCRIPT_UNKNOWN">
|
|
<doc xml:space="preserve">an unassigned code point</doc>
|
|
</member>
|
|
<member name="balinese" value="62" c:identifier="G_UNICODE_SCRIPT_BALINESE">
|
|
<doc xml:space="preserve">Balinese</doc>
|
|
</member>
|
|
<member name="cuneiform" value="63" c:identifier="G_UNICODE_SCRIPT_CUNEIFORM">
|
|
<doc xml:space="preserve">Cuneiform</doc>
|
|
</member>
|
|
<member name="phoenician" value="64" c:identifier="G_UNICODE_SCRIPT_PHOENICIAN">
|
|
<doc xml:space="preserve">Phoenician</doc>
|
|
</member>
|
|
<member name="phags_pa" value="65" c:identifier="G_UNICODE_SCRIPT_PHAGS_PA">
|
|
<doc xml:space="preserve">Phags-pa</doc>
|
|
</member>
|
|
<member name="nko" value="66" c:identifier="G_UNICODE_SCRIPT_NKO">
|
|
<doc xml:space="preserve">N'Ko</doc>
|
|
</member>
|
|
<member name="kayah_li" value="67" c:identifier="G_UNICODE_SCRIPT_KAYAH_LI">
|
|
<doc xml:space="preserve">Kayah Li. Since 2.16.3</doc>
|
|
</member>
|
|
<member name="lepcha" value="68" c:identifier="G_UNICODE_SCRIPT_LEPCHA">
|
|
<doc xml:space="preserve">Lepcha. Since 2.16.3</doc>
|
|
</member>
|
|
<member name="rejang" value="69" c:identifier="G_UNICODE_SCRIPT_REJANG">
|
|
<doc xml:space="preserve">Rejang. Since 2.16.3</doc>
|
|
</member>
|
|
<member name="sundanese" value="70" c:identifier="G_UNICODE_SCRIPT_SUNDANESE">
|
|
<doc xml:space="preserve">Sundanese. Since 2.16.3</doc>
|
|
</member>
|
|
<member name="saurashtra" value="71" c:identifier="G_UNICODE_SCRIPT_SAURASHTRA">
|
|
<doc xml:space="preserve">Saurashtra. Since 2.16.3</doc>
|
|
</member>
|
|
<member name="cham" value="72" c:identifier="G_UNICODE_SCRIPT_CHAM">
|
|
<doc xml:space="preserve">Cham. Since 2.16.3</doc>
|
|
</member>
|
|
<member name="ol_chiki" value="73" c:identifier="G_UNICODE_SCRIPT_OL_CHIKI">
|
|
<doc xml:space="preserve">Ol Chiki. Since 2.16.3</doc>
|
|
</member>
|
|
<member name="vai" value="74" c:identifier="G_UNICODE_SCRIPT_VAI">
|
|
<doc xml:space="preserve">Vai. Since 2.16.3</doc>
|
|
</member>
|
|
<member name="carian" value="75" c:identifier="G_UNICODE_SCRIPT_CARIAN">
|
|
<doc xml:space="preserve">Carian. Since 2.16.3</doc>
|
|
</member>
|
|
<member name="lycian" value="76" c:identifier="G_UNICODE_SCRIPT_LYCIAN">
|
|
<doc xml:space="preserve">Lycian. Since 2.16.3</doc>
|
|
</member>
|
|
<member name="lydian" value="77" c:identifier="G_UNICODE_SCRIPT_LYDIAN">
|
|
<doc xml:space="preserve">Lydian. Since 2.16.3</doc>
|
|
</member>
|
|
<member name="avestan" value="78" c:identifier="G_UNICODE_SCRIPT_AVESTAN">
|
|
<doc xml:space="preserve">Avestan. Since 2.26</doc>
|
|
</member>
|
|
<member name="bamum" value="79" c:identifier="G_UNICODE_SCRIPT_BAMUM">
|
|
<doc xml:space="preserve">Bamum. Since 2.26</doc>
|
|
</member>
|
|
<member name="egyptian_hieroglyphs" value="80" c:identifier="G_UNICODE_SCRIPT_EGYPTIAN_HIEROGLYPHS">
|
|
<doc xml:space="preserve">Egyptian Hieroglpyhs. Since 2.26</doc>
|
|
</member>
|
|
<member name="imperial_aramaic" value="81" c:identifier="G_UNICODE_SCRIPT_IMPERIAL_ARAMAIC">
|
|
<doc xml:space="preserve">Imperial Aramaic. Since 2.26</doc>
|
|
</member>
|
|
<member name="inscriptional_pahlavi" value="82" c:identifier="G_UNICODE_SCRIPT_INSCRIPTIONAL_PAHLAVI">
|
|
<doc xml:space="preserve">Inscriptional Pahlavi. Since 2.26</doc>
|
|
</member>
|
|
<member name="inscriptional_parthian" value="83" c:identifier="G_UNICODE_SCRIPT_INSCRIPTIONAL_PARTHIAN">
|
|
<doc xml:space="preserve">Inscriptional Parthian. Since 2.26</doc>
|
|
</member>
|
|
<member name="javanese" value="84" c:identifier="G_UNICODE_SCRIPT_JAVANESE">
|
|
<doc xml:space="preserve">Javanese. Since 2.26</doc>
|
|
</member>
|
|
<member name="kaithi" value="85" c:identifier="G_UNICODE_SCRIPT_KAITHI">
|
|
<doc xml:space="preserve">Kaithi. Since 2.26</doc>
|
|
</member>
|
|
<member name="lisu" value="86" c:identifier="G_UNICODE_SCRIPT_LISU">
|
|
<doc xml:space="preserve">Lisu. Since 2.26</doc>
|
|
</member>
|
|
<member name="meetei_mayek" value="87" c:identifier="G_UNICODE_SCRIPT_MEETEI_MAYEK">
|
|
<doc xml:space="preserve">Meetei Mayek. Since 2.26</doc>
|
|
</member>
|
|
<member name="old_south_arabian" value="88" c:identifier="G_UNICODE_SCRIPT_OLD_SOUTH_ARABIAN">
|
|
<doc xml:space="preserve">Old South Arabian. Since 2.26</doc>
|
|
</member>
|
|
<member name="old_turkic" value="89" c:identifier="G_UNICODE_SCRIPT_OLD_TURKIC">
|
|
<doc xml:space="preserve">Old Turkic. Since 2.28</doc>
|
|
</member>
|
|
<member name="samaritan" value="90" c:identifier="G_UNICODE_SCRIPT_SAMARITAN">
|
|
<doc xml:space="preserve">Samaritan. Since 2.26</doc>
|
|
</member>
|
|
<member name="tai_tham" value="91" c:identifier="G_UNICODE_SCRIPT_TAI_THAM">
|
|
<doc xml:space="preserve">Tai Tham. Since 2.26</doc>
|
|
</member>
|
|
<member name="tai_viet" value="92" c:identifier="G_UNICODE_SCRIPT_TAI_VIET">
|
|
<doc xml:space="preserve">Tai Viet. Since 2.26</doc>
|
|
</member>
|
|
<member name="batak" value="93" c:identifier="G_UNICODE_SCRIPT_BATAK">
|
|
<doc xml:space="preserve">Batak. Since 2.28</doc>
|
|
</member>
|
|
<member name="brahmi" value="94" c:identifier="G_UNICODE_SCRIPT_BRAHMI">
|
|
<doc xml:space="preserve">Brahmi. Since 2.28</doc>
|
|
</member>
|
|
<member name="mandaic" value="95" c:identifier="G_UNICODE_SCRIPT_MANDAIC">
|
|
<doc xml:space="preserve">Mandaic. Since 2.28</doc>
|
|
</member>
|
|
<member name="chakma" value="96" c:identifier="G_UNICODE_SCRIPT_CHAKMA">
|
|
<doc xml:space="preserve">Chakma. Since: 2.32</doc>
|
|
</member>
|
|
<member name="meroitic_cursive" value="97" c:identifier="G_UNICODE_SCRIPT_MEROITIC_CURSIVE">
|
|
<doc xml:space="preserve">Meroitic Cursive. Since: 2.32</doc>
|
|
</member>
|
|
<member name="meroitic_hieroglyphs" value="98" c:identifier="G_UNICODE_SCRIPT_MEROITIC_HIEROGLYPHS">
|
|
<doc xml:space="preserve">Meroitic Hieroglyphs. Since: 2.32</doc>
|
|
</member>
|
|
<member name="miao" value="99" c:identifier="G_UNICODE_SCRIPT_MIAO">
|
|
<doc xml:space="preserve">Miao. Since: 2.32</doc>
|
|
</member>
|
|
<member name="sharada" value="100" c:identifier="G_UNICODE_SCRIPT_SHARADA">
|
|
<doc xml:space="preserve">Sharada. Since: 2.32</doc>
|
|
</member>
|
|
<member name="sora_sompeng" value="101" c:identifier="G_UNICODE_SCRIPT_SORA_SOMPENG">
|
|
<doc xml:space="preserve">Sora Sompeng. Since: 2.32</doc>
|
|
</member>
|
|
<member name="takri" value="102" c:identifier="G_UNICODE_SCRIPT_TAKRI">
|
|
<doc xml:space="preserve">Takri. Since: 2.32</doc>
|
|
</member>
|
|
<member name="bassa_vah" value="103" c:identifier="G_UNICODE_SCRIPT_BASSA_VAH">
|
|
<doc xml:space="preserve">Bassa. Since: 2.42</doc>
|
|
</member>
|
|
<member name="caucasian_albanian" value="104" c:identifier="G_UNICODE_SCRIPT_CAUCASIAN_ALBANIAN">
|
|
<doc xml:space="preserve">Caucasian Albanian. Since: 2.42</doc>
|
|
</member>
|
|
<member name="duployan" value="105" c:identifier="G_UNICODE_SCRIPT_DUPLOYAN">
|
|
<doc xml:space="preserve">Duployan. Since: 2.42</doc>
|
|
</member>
|
|
<member name="elbasan" value="106" c:identifier="G_UNICODE_SCRIPT_ELBASAN">
|
|
<doc xml:space="preserve">Elbasan. Since: 2.42</doc>
|
|
</member>
|
|
<member name="grantha" value="107" c:identifier="G_UNICODE_SCRIPT_GRANTHA">
|
|
<doc xml:space="preserve">Grantha. Since: 2.42</doc>
|
|
</member>
|
|
<member name="khojki" value="108" c:identifier="G_UNICODE_SCRIPT_KHOJKI">
|
|
<doc xml:space="preserve">Kjohki. Since: 2.42</doc>
|
|
</member>
|
|
<member name="khudawadi" value="109" c:identifier="G_UNICODE_SCRIPT_KHUDAWADI">
|
|
<doc xml:space="preserve">Khudawadi, Sindhi. Since: 2.42</doc>
|
|
</member>
|
|
<member name="linear_a" value="110" c:identifier="G_UNICODE_SCRIPT_LINEAR_A">
|
|
<doc xml:space="preserve">Linear A. Since: 2.42</doc>
|
|
</member>
|
|
<member name="mahajani" value="111" c:identifier="G_UNICODE_SCRIPT_MAHAJANI">
|
|
<doc xml:space="preserve">Mahajani. Since: 2.42</doc>
|
|
</member>
|
|
<member name="manichaean" value="112" c:identifier="G_UNICODE_SCRIPT_MANICHAEAN">
|
|
<doc xml:space="preserve">Manichaean. Since: 2.42</doc>
|
|
</member>
|
|
<member name="mende_kikakui" value="113" c:identifier="G_UNICODE_SCRIPT_MENDE_KIKAKUI">
|
|
<doc xml:space="preserve">Mende Kikakui. Since: 2.42</doc>
|
|
</member>
|
|
<member name="modi" value="114" c:identifier="G_UNICODE_SCRIPT_MODI">
|
|
<doc xml:space="preserve">Modi. Since: 2.42</doc>
|
|
</member>
|
|
<member name="mro" value="115" c:identifier="G_UNICODE_SCRIPT_MRO">
|
|
<doc xml:space="preserve">Mro. Since: 2.42</doc>
|
|
</member>
|
|
<member name="nabataean" value="116" c:identifier="G_UNICODE_SCRIPT_NABATAEAN">
|
|
<doc xml:space="preserve">Nabataean. Since: 2.42</doc>
|
|
</member>
|
|
<member name="old_north_arabian" value="117" c:identifier="G_UNICODE_SCRIPT_OLD_NORTH_ARABIAN">
|
|
<doc xml:space="preserve">Old North Arabian. Since: 2.42</doc>
|
|
</member>
|
|
<member name="old_permic" value="118" c:identifier="G_UNICODE_SCRIPT_OLD_PERMIC">
|
|
<doc xml:space="preserve">Old Permic. Since: 2.42</doc>
|
|
</member>
|
|
<member name="pahawh_hmong" value="119" c:identifier="G_UNICODE_SCRIPT_PAHAWH_HMONG">
|
|
<doc xml:space="preserve">Pahawh Hmong. Since: 2.42</doc>
|
|
</member>
|
|
<member name="palmyrene" value="120" c:identifier="G_UNICODE_SCRIPT_PALMYRENE">
|
|
<doc xml:space="preserve">Palmyrene. Since: 2.42</doc>
|
|
</member>
|
|
<member name="pau_cin_hau" value="121" c:identifier="G_UNICODE_SCRIPT_PAU_CIN_HAU">
|
|
<doc xml:space="preserve">Pau Cin Hau. Since: 2.42</doc>
|
|
</member>
|
|
<member name="psalter_pahlavi" value="122" c:identifier="G_UNICODE_SCRIPT_PSALTER_PAHLAVI">
|
|
<doc xml:space="preserve">Psalter Pahlavi. Since: 2.42</doc>
|
|
</member>
|
|
<member name="siddham" value="123" c:identifier="G_UNICODE_SCRIPT_SIDDHAM">
|
|
<doc xml:space="preserve">Siddham. Since: 2.42</doc>
|
|
</member>
|
|
<member name="tirhuta" value="124" c:identifier="G_UNICODE_SCRIPT_TIRHUTA">
|
|
<doc xml:space="preserve">Tirhuta. Since: 2.42</doc>
|
|
</member>
|
|
<member name="warang_citi" value="125" c:identifier="G_UNICODE_SCRIPT_WARANG_CITI">
|
|
<doc xml:space="preserve">Warang Citi. Since: 2.42</doc>
|
|
</member>
|
|
<member name="ahom" value="126" c:identifier="G_UNICODE_SCRIPT_AHOM">
|
|
<doc xml:space="preserve">Ahom. Since: 2.48</doc>
|
|
</member>
|
|
<member name="anatolian_hieroglyphs" value="127" c:identifier="G_UNICODE_SCRIPT_ANATOLIAN_HIEROGLYPHS">
|
|
<doc xml:space="preserve">Anatolian Hieroglyphs. Since: 2.48</doc>
|
|
</member>
|
|
<member name="hatran" value="128" c:identifier="G_UNICODE_SCRIPT_HATRAN">
|
|
<doc xml:space="preserve">Hatran. Since: 2.48</doc>
|
|
</member>
|
|
<member name="multani" value="129" c:identifier="G_UNICODE_SCRIPT_MULTANI">
|
|
<doc xml:space="preserve">Multani. Since: 2.48</doc>
|
|
</member>
|
|
<member name="old_hungarian" value="130" c:identifier="G_UNICODE_SCRIPT_OLD_HUNGARIAN">
|
|
<doc xml:space="preserve">Old Hungarian. Since: 2.48</doc>
|
|
</member>
|
|
<member name="signwriting" value="131" c:identifier="G_UNICODE_SCRIPT_SIGNWRITING">
|
|
<doc xml:space="preserve">Signwriting. Since: 2.48</doc>
|
|
</member>
|
|
<member name="adlam" value="132" c:identifier="G_UNICODE_SCRIPT_ADLAM">
|
|
<doc xml:space="preserve">Adlam. Since: 2.50</doc>
|
|
</member>
|
|
<member name="bhaiksuki" value="133" c:identifier="G_UNICODE_SCRIPT_BHAIKSUKI">
|
|
<doc xml:space="preserve">Bhaiksuki. Since: 2.50</doc>
|
|
</member>
|
|
<member name="marchen" value="134" c:identifier="G_UNICODE_SCRIPT_MARCHEN">
|
|
<doc xml:space="preserve">Marchen. Since: 2.50</doc>
|
|
</member>
|
|
<member name="newa" value="135" c:identifier="G_UNICODE_SCRIPT_NEWA">
|
|
<doc xml:space="preserve">Newa. Since: 2.50</doc>
|
|
</member>
|
|
<member name="osage" value="136" c:identifier="G_UNICODE_SCRIPT_OSAGE">
|
|
<doc xml:space="preserve">Osage. Since: 2.50</doc>
|
|
</member>
|
|
<member name="tangut" value="137" c:identifier="G_UNICODE_SCRIPT_TANGUT">
|
|
<doc xml:space="preserve">Tangut. Since: 2.50</doc>
|
|
</member>
|
|
<member name="masaram_gondi" value="138" c:identifier="G_UNICODE_SCRIPT_MASARAM_GONDI">
|
|
<doc xml:space="preserve">Masaram Gondi. Since: 2.54</doc>
|
|
</member>
|
|
<member name="nushu" value="139" c:identifier="G_UNICODE_SCRIPT_NUSHU">
|
|
<doc xml:space="preserve">Nushu. Since: 2.54</doc>
|
|
</member>
|
|
<member name="soyombo" value="140" c:identifier="G_UNICODE_SCRIPT_SOYOMBO">
|
|
<doc xml:space="preserve">Soyombo. Since: 2.54</doc>
|
|
</member>
|
|
<member name="zanabazar_square" value="141" c:identifier="G_UNICODE_SCRIPT_ZANABAZAR_SQUARE">
|
|
<doc xml:space="preserve">Zanabazar Square. Since: 2.54</doc>
|
|
</member>
|
|
<member name="dogra" value="142" c:identifier="G_UNICODE_SCRIPT_DOGRA">
|
|
<doc xml:space="preserve">Dogra. Since: 2.58</doc>
|
|
</member>
|
|
<member name="gunjala_gondi" value="143" c:identifier="G_UNICODE_SCRIPT_GUNJALA_GONDI">
|
|
<doc xml:space="preserve">Gunjala Gondi. Since: 2.58</doc>
|
|
</member>
|
|
<member name="hanifi_rohingya" value="144" c:identifier="G_UNICODE_SCRIPT_HANIFI_ROHINGYA">
|
|
<doc xml:space="preserve">Hanifi Rohingya. Since: 2.58</doc>
|
|
</member>
|
|
<member name="makasar" value="145" c:identifier="G_UNICODE_SCRIPT_MAKASAR">
|
|
<doc xml:space="preserve">Makasar. Since: 2.58</doc>
|
|
</member>
|
|
<member name="medefaidrin" value="146" c:identifier="G_UNICODE_SCRIPT_MEDEFAIDRIN">
|
|
<doc xml:space="preserve">Medefaidrin. Since: 2.58</doc>
|
|
</member>
|
|
<member name="old_sogdian" value="147" c:identifier="G_UNICODE_SCRIPT_OLD_SOGDIAN">
|
|
<doc xml:space="preserve">Old Sogdian. Since: 2.58</doc>
|
|
</member>
|
|
<member name="sogdian" value="148" c:identifier="G_UNICODE_SCRIPT_SOGDIAN">
|
|
<doc xml:space="preserve">Sogdian. Since: 2.58</doc>
|
|
</member>
|
|
<member name="elymaic" value="149" c:identifier="G_UNICODE_SCRIPT_ELYMAIC">
|
|
<doc xml:space="preserve">Elym. Since: 2.62</doc>
|
|
</member>
|
|
<member name="nandinagari" value="150" c:identifier="G_UNICODE_SCRIPT_NANDINAGARI">
|
|
<doc xml:space="preserve">Nand. Since: 2.62</doc>
|
|
</member>
|
|
<member name="nyiakeng_puachue_hmong" value="151" c:identifier="G_UNICODE_SCRIPT_NYIAKENG_PUACHUE_HMONG">
|
|
<doc xml:space="preserve">Rohg. Since: 2.62</doc>
|
|
</member>
|
|
<member name="wancho" value="152" c:identifier="G_UNICODE_SCRIPT_WANCHO">
|
|
<doc xml:space="preserve">Wcho. Since: 2.62</doc>
|
|
</member>
|
|
<member name="chorasmian" value="153" c:identifier="G_UNICODE_SCRIPT_CHORASMIAN">
|
|
<doc xml:space="preserve">Chorasmian. Since: 2.66</doc>
|
|
</member>
|
|
<member name="dives_akuru" value="154" c:identifier="G_UNICODE_SCRIPT_DIVES_AKURU">
|
|
<doc xml:space="preserve">Dives Akuru. Since: 2.66</doc>
|
|
</member>
|
|
<member name="khitan_small_script" value="155" c:identifier="G_UNICODE_SCRIPT_KHITAN_SMALL_SCRIPT">
|
|
<doc xml:space="preserve">Khitan small script. Since: 2.66</doc>
|
|
</member>
|
|
<member name="yezidi" value="156" c:identifier="G_UNICODE_SCRIPT_YEZIDI">
|
|
<doc xml:space="preserve">Yezidi. Since: 2.66</doc>
|
|
</member>
|
|
</enumeration>
|
|
<enumeration name="UnicodeType" c:type="GUnicodeType">
|
|
<doc xml:space="preserve">These are the possible character classifications from the
|
|
Unicode specification.
|
|
See [Unicode Character Database](http://www.unicode.org/reports/tr44/#General_Category_Values).</doc>
|
|
<member name="control" value="0" c:identifier="G_UNICODE_CONTROL">
|
|
<doc xml:space="preserve">General category "Other, Control" (Cc)</doc>
|
|
</member>
|
|
<member name="format" value="1" c:identifier="G_UNICODE_FORMAT">
|
|
<doc xml:space="preserve">General category "Other, Format" (Cf)</doc>
|
|
</member>
|
|
<member name="unassigned" value="2" c:identifier="G_UNICODE_UNASSIGNED">
|
|
<doc xml:space="preserve">General category "Other, Not Assigned" (Cn)</doc>
|
|
</member>
|
|
<member name="private_use" value="3" c:identifier="G_UNICODE_PRIVATE_USE">
|
|
<doc xml:space="preserve">General category "Other, Private Use" (Co)</doc>
|
|
</member>
|
|
<member name="surrogate" value="4" c:identifier="G_UNICODE_SURROGATE">
|
|
<doc xml:space="preserve">General category "Other, Surrogate" (Cs)</doc>
|
|
</member>
|
|
<member name="lowercase_letter" value="5" c:identifier="G_UNICODE_LOWERCASE_LETTER">
|
|
<doc xml:space="preserve">General category "Letter, Lowercase" (Ll)</doc>
|
|
</member>
|
|
<member name="modifier_letter" value="6" c:identifier="G_UNICODE_MODIFIER_LETTER">
|
|
<doc xml:space="preserve">General category "Letter, Modifier" (Lm)</doc>
|
|
</member>
|
|
<member name="other_letter" value="7" c:identifier="G_UNICODE_OTHER_LETTER">
|
|
<doc xml:space="preserve">General category "Letter, Other" (Lo)</doc>
|
|
</member>
|
|
<member name="titlecase_letter" value="8" c:identifier="G_UNICODE_TITLECASE_LETTER">
|
|
<doc xml:space="preserve">General category "Letter, Titlecase" (Lt)</doc>
|
|
</member>
|
|
<member name="uppercase_letter" value="9" c:identifier="G_UNICODE_UPPERCASE_LETTER">
|
|
<doc xml:space="preserve">General category "Letter, Uppercase" (Lu)</doc>
|
|
</member>
|
|
<member name="spacing_mark" value="10" c:identifier="G_UNICODE_SPACING_MARK">
|
|
<doc xml:space="preserve">General category "Mark, Spacing" (Mc)</doc>
|
|
</member>
|
|
<member name="enclosing_mark" value="11" c:identifier="G_UNICODE_ENCLOSING_MARK">
|
|
<doc xml:space="preserve">General category "Mark, Enclosing" (Me)</doc>
|
|
</member>
|
|
<member name="non_spacing_mark" value="12" c:identifier="G_UNICODE_NON_SPACING_MARK">
|
|
<doc xml:space="preserve">General category "Mark, Nonspacing" (Mn)</doc>
|
|
</member>
|
|
<member name="decimal_number" value="13" c:identifier="G_UNICODE_DECIMAL_NUMBER">
|
|
<doc xml:space="preserve">General category "Number, Decimal Digit" (Nd)</doc>
|
|
</member>
|
|
<member name="letter_number" value="14" c:identifier="G_UNICODE_LETTER_NUMBER">
|
|
<doc xml:space="preserve">General category "Number, Letter" (Nl)</doc>
|
|
</member>
|
|
<member name="other_number" value="15" c:identifier="G_UNICODE_OTHER_NUMBER">
|
|
<doc xml:space="preserve">General category "Number, Other" (No)</doc>
|
|
</member>
|
|
<member name="connect_punctuation" value="16" c:identifier="G_UNICODE_CONNECT_PUNCTUATION">
|
|
<doc xml:space="preserve">General category "Punctuation, Connector" (Pc)</doc>
|
|
</member>
|
|
<member name="dash_punctuation" value="17" c:identifier="G_UNICODE_DASH_PUNCTUATION">
|
|
<doc xml:space="preserve">General category "Punctuation, Dash" (Pd)</doc>
|
|
</member>
|
|
<member name="close_punctuation" value="18" c:identifier="G_UNICODE_CLOSE_PUNCTUATION">
|
|
<doc xml:space="preserve">General category "Punctuation, Close" (Pe)</doc>
|
|
</member>
|
|
<member name="final_punctuation" value="19" c:identifier="G_UNICODE_FINAL_PUNCTUATION">
|
|
<doc xml:space="preserve">General category "Punctuation, Final quote" (Pf)</doc>
|
|
</member>
|
|
<member name="initial_punctuation" value="20" c:identifier="G_UNICODE_INITIAL_PUNCTUATION">
|
|
<doc xml:space="preserve">General category "Punctuation, Initial quote" (Pi)</doc>
|
|
</member>
|
|
<member name="other_punctuation" value="21" c:identifier="G_UNICODE_OTHER_PUNCTUATION">
|
|
<doc xml:space="preserve">General category "Punctuation, Other" (Po)</doc>
|
|
</member>
|
|
<member name="open_punctuation" value="22" c:identifier="G_UNICODE_OPEN_PUNCTUATION">
|
|
<doc xml:space="preserve">General category "Punctuation, Open" (Ps)</doc>
|
|
</member>
|
|
<member name="currency_symbol" value="23" c:identifier="G_UNICODE_CURRENCY_SYMBOL">
|
|
<doc xml:space="preserve">General category "Symbol, Currency" (Sc)</doc>
|
|
</member>
|
|
<member name="modifier_symbol" value="24" c:identifier="G_UNICODE_MODIFIER_SYMBOL">
|
|
<doc xml:space="preserve">General category "Symbol, Modifier" (Sk)</doc>
|
|
</member>
|
|
<member name="math_symbol" value="25" c:identifier="G_UNICODE_MATH_SYMBOL">
|
|
<doc xml:space="preserve">General category "Symbol, Math" (Sm)</doc>
|
|
</member>
|
|
<member name="other_symbol" value="26" c:identifier="G_UNICODE_OTHER_SYMBOL">
|
|
<doc xml:space="preserve">General category "Symbol, Other" (So)</doc>
|
|
</member>
|
|
<member name="line_separator" value="27" c:identifier="G_UNICODE_LINE_SEPARATOR">
|
|
<doc xml:space="preserve">General category "Separator, Line" (Zl)</doc>
|
|
</member>
|
|
<member name="paragraph_separator" value="28" c:identifier="G_UNICODE_PARAGRAPH_SEPARATOR">
|
|
<doc xml:space="preserve">General category "Separator, Paragraph" (Zp)</doc>
|
|
</member>
|
|
<member name="space_separator" value="29" c:identifier="G_UNICODE_SPACE_SEPARATOR">
|
|
<doc xml:space="preserve">General category "Separator, Space" (Zs)</doc>
|
|
</member>
|
|
</enumeration>
|
|
<callback name="UnixFDSourceFunc" c:type="GUnixFDSourceFunc">
|
|
<doc xml:space="preserve">The type of functions to be called when a UNIX fd watch source
|
|
triggers.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%FALSE if the source should be removed</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">the fd that triggered the event</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="condition" transfer-ownership="none">
|
|
<doc xml:space="preserve">the IO conditions reported on @fd</doc>
|
|
<type name="IOCondition" c:type="GIOCondition"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="2">
|
|
<doc xml:space="preserve">user data passed to g_unix_fd_add()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<record name="Uri" c:type="GUri" version="2.66" glib:type-name="GUri" glib:get-type="g_uri_get_type" c:symbol-prefix="uri">
|
|
<doc xml:space="preserve">The #GUri type and related functions can be used to parse URIs into
|
|
their components, and build valid URIs from individual components.
|
|
|
|
Note that #GUri scope is to help manipulate URIs in various applications,
|
|
following [RFC 3986](https://tools.ietf.org/html/rfc3986). In particular,
|
|
it doesn't intend to cover web browser needs, and doesn't implement the
|
|
[WHATWG URL](https://url.spec.whatwg.org/) standard. No APIs are provided to
|
|
help prevent
|
|
[homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), so
|
|
#GUri is not suitable for formatting URIs for display to the user for making
|
|
security-sensitive decisions.
|
|
|
|
## Relative and absolute URIs # {#relative-absolute-uris}
|
|
|
|
As defined in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4), the
|
|
hierarchical nature of URIs means that they can either be ‘relative
|
|
references’ (sometimes referred to as ‘relative URIs’) or ‘URIs’ (for
|
|
clarity, ‘URIs’ are referred to in this documentation as
|
|
‘absolute URIs’ — although
|
|
[in constrast to RFC 3986](https://tools.ietf.org/html/rfc3986#section-4.3),
|
|
fragment identifiers are always allowed).
|
|
|
|
Relative references have one or more components of the URI missing. In
|
|
particular, they have no scheme. Any other component, such as hostname,
|
|
query, etc. may be missing, apart from a path, which has to be specified (but
|
|
may be empty). The path may be relative, starting with `./` rather than `/`.
|
|
|
|
For example, a valid relative reference is `./path?query`,
|
|
`/?query#fragment` or `//example.com`.
|
|
|
|
Absolute URIs have a scheme specified. Any other components of the URI which
|
|
are missing are specified as explicitly unset in the URI, rather than being
|
|
resolved relative to a base URI using g_uri_parse_relative().
|
|
|
|
For example, a valid absolute URI is `file:///home/bob` or
|
|
`https://search.com?query=string`.
|
|
|
|
A #GUri instance is always an absolute URI. A string may be an absolute URI
|
|
or a relative reference; see the documentation for individual functions as to
|
|
what forms they accept.
|
|
|
|
## Parsing URIs
|
|
|
|
The most minimalist APIs for parsing URIs are g_uri_split() and
|
|
g_uri_split_with_user(). These split a URI into its component
|
|
parts, and return the parts; the difference between the two is that
|
|
g_uri_split() treats the ‘userinfo’ component of the URI as a
|
|
single element, while g_uri_split_with_user() can (depending on the
|
|
#GUriFlags you pass) treat it as containing a username, password,
|
|
and authentication parameters. Alternatively, g_uri_split_network()
|
|
can be used when you are only interested in the components that are
|
|
needed to initiate a network connection to the service (scheme,
|
|
host, and port).
|
|
|
|
g_uri_parse() is similar to g_uri_split(), but instead of returning
|
|
individual strings, it returns a #GUri structure (and it requires
|
|
that the URI be an absolute URI).
|
|
|
|
g_uri_resolve_relative() and g_uri_parse_relative() allow you to
|
|
resolve a relative URI relative to a base URI.
|
|
g_uri_resolve_relative() takes two strings and returns a string,
|
|
and g_uri_parse_relative() takes a #GUri and a string and returns a
|
|
#GUri.
|
|
|
|
All of the parsing functions take a #GUriFlags argument describing
|
|
exactly how to parse the URI; see the documentation for that type
|
|
for more details on the specific flags that you can pass. If you
|
|
need to choose different flags based on the type of URI, you can
|
|
use g_uri_peek_scheme() on the URI string to check the scheme
|
|
first, and use that to decide what flags to parse it with.
|
|
|
|
For example, you might want to use %G_URI_PARAMS_WWW_FORM when parsing the
|
|
params for a web URI, so compare the result of g_uri_peek_scheme() against
|
|
`http` and `https`.
|
|
|
|
## Building URIs
|
|
|
|
g_uri_join() and g_uri_join_with_user() can be used to construct
|
|
valid URI strings from a set of component strings. They are the
|
|
inverse of g_uri_split() and g_uri_split_with_user().
|
|
|
|
Similarly, g_uri_build() and g_uri_build_with_user() can be used to
|
|
construct a #GUri from a set of component strings.
|
|
|
|
As with the parsing functions, the building functions take a
|
|
#GUriFlags argument. In particular, it is important to keep in mind
|
|
whether the URI components you are using are already `%`-encoded. If so,
|
|
you must pass the %G_URI_FLAGS_ENCODED flag.
|
|
|
|
## `file://` URIs
|
|
|
|
Note that Windows and Unix both define special rules for parsing
|
|
`file://` URIs (involving non-UTF-8 character sets on Unix, and the
|
|
interpretation of path separators on Windows). #GUri does not
|
|
implement these rules. Use g_filename_from_uri() and
|
|
g_filename_to_uri() if you want to properly convert between
|
|
`file://` URIs and local filenames.
|
|
|
|
## URI Equality
|
|
|
|
Note that there is no `g_uri_equal ()` function, because comparing
|
|
URIs usefully requires scheme-specific knowledge that #GUri does
|
|
not have. For example, `http://example.com/` and
|
|
`http://EXAMPLE.COM:80` have exactly the same meaning according
|
|
to the HTTP specification, and `data:,foo` and
|
|
`data:;base64,Zm9v` resolve to the same thing according to the
|
|
`data:` URI specification.</doc>
|
|
<method name="get_auth_params" c:identifier="g_uri_get_auth_params" version="2.66">
|
|
<doc xml:space="preserve">Gets @uri's authentication parameters, which may contain
|
|
`%`-encoding, depending on the flags with which @uri was created.
|
|
(If @uri was not created with %G_URI_FLAGS_HAS_AUTH_PARAMS then this will
|
|
be %NULL.)
|
|
|
|
Depending on the URI scheme, g_uri_parse_params() may be useful for
|
|
further parsing this information.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">@uri's authentication parameters.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_flags" c:identifier="g_uri_get_flags" version="2.66">
|
|
<doc xml:space="preserve">Gets @uri's flags set upon construction.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@uri's flags.</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_fragment" c:identifier="g_uri_get_fragment" version="2.66">
|
|
<doc xml:space="preserve">Gets @uri's fragment, which may contain `%`-encoding, depending on
|
|
the flags with which @uri was created.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">@uri's fragment.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_host" c:identifier="g_uri_get_host" version="2.66">
|
|
<doc xml:space="preserve">Gets @uri's host. This will never have `%`-encoded characters,
|
|
unless it is non-UTF-8 (which can only be the case if @uri was
|
|
created with %G_URI_FLAGS_NON_DNS).
|
|
|
|
If @uri contained an IPv6 address literal, this value will be just
|
|
that address, without the brackets around it that are necessary in
|
|
the string form of the URI. Note that in this case there may also
|
|
be a scope ID attached to the address. Eg, `fe80::1234%``em1` (or
|
|
`fe80::1234%``25em1` if the string is still encoded).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@uri's host.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_password" c:identifier="g_uri_get_password" version="2.66">
|
|
<doc xml:space="preserve">Gets @uri's password, which may contain `%`-encoding, depending on
|
|
the flags with which @uri was created. (If @uri was not created
|
|
with %G_URI_FLAGS_HAS_PASSWORD then this will be %NULL.)</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">@uri's password.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_path" c:identifier="g_uri_get_path" version="2.66">
|
|
<doc xml:space="preserve">Gets @uri's path, which may contain `%`-encoding, depending on the
|
|
flags with which @uri was created.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@uri's path.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_port" c:identifier="g_uri_get_port" version="2.66">
|
|
<doc xml:space="preserve">Gets @uri's port.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@uri's port, or `-1` if no port was specified.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_query" c:identifier="g_uri_get_query" version="2.66">
|
|
<doc xml:space="preserve">Gets @uri's query, which may contain `%`-encoding, depending on the
|
|
flags with which @uri was created.
|
|
|
|
For queries consisting of a series of `name=value` parameters,
|
|
#GUriParamsIter or g_uri_parse_params() may be useful.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">@uri's query.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_scheme" c:identifier="g_uri_get_scheme" version="2.66">
|
|
<doc xml:space="preserve">Gets @uri's scheme. Note that this will always be all-lowercase,
|
|
regardless of the string or strings that @uri was created from.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@uri's scheme.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_user" c:identifier="g_uri_get_user" version="2.66">
|
|
<doc xml:space="preserve">Gets the ‘username’ component of @uri's userinfo, which may contain
|
|
`%`-encoding, depending on the flags with which @uri was created.
|
|
If @uri was not created with %G_URI_FLAGS_HAS_PASSWORD or
|
|
%G_URI_FLAGS_HAS_AUTH_PARAMS, this is the same as g_uri_get_userinfo().</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">@uri's user.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_userinfo" c:identifier="g_uri_get_userinfo" version="2.66">
|
|
<doc xml:space="preserve">Gets @uri's userinfo, which may contain `%`-encoding, depending on
|
|
the flags with which @uri was created.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">@uri's userinfo.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="parse_relative" c:identifier="g_uri_parse_relative" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Parses @uri_ref according to @flags and, if it is a
|
|
[relative URI][relative-absolute-uris], resolves it relative to @base_uri.
|
|
If the result is not a valid absolute URI, it will be discarded, and an error
|
|
returned.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GUri.</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="base_uri" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a base absolute URI</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</instance-parameter>
|
|
<parameter name="uri_ref" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string representing a relative or absolute URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags describing how to parse @uri_ref</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_uri_ref" version="2.66" introspectable="0">
|
|
<doc xml:space="preserve">Increments the reference count of @uri by one.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">@uri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="to_string" c:identifier="g_uri_to_string" version="2.66">
|
|
<doc xml:space="preserve">Returns a string representing @uri.
|
|
|
|
This is not guaranteed to return a string which is identical to the
|
|
string that @uri was parsed from. However, if the source URI was
|
|
syntactically correct (according to RFC 3986), and it was parsed
|
|
with %G_URI_FLAGS_ENCODED, then g_uri_to_string() is guaranteed to return
|
|
a string which is at least semantically equivalent to the source
|
|
URI (according to RFC 3986).
|
|
|
|
If @uri might contain sensitive details, such as authentication parameters,
|
|
or private data in its query string, and the returned string is going to be
|
|
logged, then consider using g_uri_to_string_partial() to redact parts.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a string representing @uri, which the caller
|
|
must free.</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="to_string_partial" c:identifier="g_uri_to_string_partial" version="2.66">
|
|
<doc xml:space="preserve">Returns a string representing @uri, subject to the options in
|
|
@flags. See g_uri_to_string() and #GUriHideFlags for more details.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a string representing @uri, which the caller
|
|
must free.</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</instance-parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags describing what parts of @uri to hide</doc>
|
|
<type name="UriHideFlags" c:type="GUriHideFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_uri_unref" version="2.66" introspectable="0">
|
|
<doc xml:space="preserve">Atomically decrements the reference count of @uri by one.
|
|
|
|
When the reference count reaches zero, the resources allocated by
|
|
@uri are freed</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="build" c:identifier="g_uri_build" version="2.66">
|
|
<doc xml:space="preserve">Creates a new #GUri from the given components according to @flags.
|
|
|
|
See also g_uri_build_with_user(), which allows specifying the
|
|
components of the "userinfo" separately.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags describing how to build the #GUri</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
<parameter name="scheme" transfer-ownership="none">
|
|
<doc xml:space="preserve">the URI scheme</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="userinfo" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the userinfo component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="host" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the host component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="port" transfer-ownership="none">
|
|
<doc xml:space="preserve">the port, or `-1`</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="path" transfer-ownership="none">
|
|
<doc xml:space="preserve">the path component</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="query" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the query component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="fragment" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the fragment, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="build_with_user" c:identifier="g_uri_build_with_user" version="2.66">
|
|
<doc xml:space="preserve">Creates a new #GUri from the given components according to @flags
|
|
(%G_URI_FLAGS_HAS_PASSWORD is added unconditionally). The @flags must be
|
|
coherent with the passed values, in particular use `%`-encoded values with
|
|
%G_URI_FLAGS_ENCODED.
|
|
|
|
In contrast to g_uri_build(), this allows specifying the components
|
|
of the ‘userinfo’ field separately. Note that @user must be non-%NULL
|
|
if either @password or @auth_params is non-%NULL.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags describing how to build the #GUri</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
<parameter name="scheme" transfer-ownership="none">
|
|
<doc xml:space="preserve">the URI scheme</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="user" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the user component of the userinfo, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="password" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the password component of the userinfo, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="auth_params" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the auth params of the userinfo, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="host" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the host component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="port" transfer-ownership="none">
|
|
<doc xml:space="preserve">the port, or `-1`</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="path" transfer-ownership="none">
|
|
<doc xml:space="preserve">the path component</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="query" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the query component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="fragment" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the fragment, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="error_quark" c:identifier="g_uri_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="escape_bytes" c:identifier="g_uri_escape_bytes" version="2.66">
|
|
<doc xml:space="preserve">Escapes arbitrary data for use in a URI.
|
|
|
|
Normally all characters that are not ‘unreserved’ (i.e. ASCII
|
|
alphanumerical characters plus dash, dot, underscore and tilde) are
|
|
escaped. But if you specify characters in @reserved_chars_allowed
|
|
they are not escaped. This is useful for the ‘reserved’ characters
|
|
in the URI specification, since those are allowed unescaped in some
|
|
portions of a URI.
|
|
|
|
Though technically incorrect, this will also allow escaping nul
|
|
bytes as `%``00`.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an escaped version of @unescaped. The returned
|
|
string should be freed when no longer needed.</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="unescaped" transfer-ownership="none">
|
|
<doc xml:space="preserve">the unescaped input data.</doc>
|
|
<array length="1" zero-terminated="0" c:type="const guint8*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @unescaped</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="reserved_chars_allowed" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string of reserved
|
|
characters that are allowed to be used, or %NULL.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="escape_string" c:identifier="g_uri_escape_string" version="2.16">
|
|
<doc xml:space="preserve">Escapes a string for use in a URI.
|
|
|
|
Normally all characters that are not "unreserved" (i.e. ASCII
|
|
alphanumerical characters plus dash, dot, underscore and tilde) are
|
|
escaped. But if you specify characters in @reserved_chars_allowed
|
|
they are not escaped. This is useful for the "reserved" characters
|
|
in the URI specification, since those are allowed unescaped in some
|
|
portions of a URI.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an escaped version of @unescaped. The returned string
|
|
should be freed when no longer needed.</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="unescaped" transfer-ownership="none">
|
|
<doc xml:space="preserve">the unescaped input string.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="reserved_chars_allowed" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string of reserved
|
|
characters that are allowed to be used, or %NULL.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="allow_utf8" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the result can include UTF-8 characters.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="is_valid" c:identifier="g_uri_is_valid" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Parses @uri_string according to @flags, to determine whether it is a valid
|
|
[absolute URI][relative-absolute-uris], i.e. it does not need to be resolved
|
|
relative to another URI using g_uri_parse_relative().
|
|
|
|
If it’s not a valid URI, an error is returned explaining how it’s invalid.
|
|
|
|
See g_uri_split(), and the definition of #GUriFlags, for more
|
|
information on the effect of @flags.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @uri_string is a valid absolute URI, %FALSE on error.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string containing an absolute URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags for parsing @uri_string</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="join" c:identifier="g_uri_join" version="2.66">
|
|
<doc xml:space="preserve">Joins the given components together according to @flags to create
|
|
an absolute URI string. @path may not be %NULL (though it may be the empty
|
|
string).
|
|
|
|
When @host is present, @path must either be empty or begin with a slash (`/`)
|
|
character. When @host is not present, @path cannot begin with two slash
|
|
characters (`//`). See
|
|
[RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3).
|
|
|
|
See also g_uri_join_with_user(), which allows specifying the
|
|
components of the ‘userinfo’ separately.
|
|
|
|
%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set
|
|
in @flags.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an absolute URI string</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags describing how to build the URI string</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
<parameter name="scheme" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the URI scheme, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="userinfo" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the userinfo component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="host" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the host component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="port" transfer-ownership="none">
|
|
<doc xml:space="preserve">the port, or `-1`</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="path" transfer-ownership="none">
|
|
<doc xml:space="preserve">the path component</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="query" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the query component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="fragment" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the fragment, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="join_with_user" c:identifier="g_uri_join_with_user" version="2.66">
|
|
<doc xml:space="preserve">Joins the given components together according to @flags to create
|
|
an absolute URI string. @path may not be %NULL (though it may be the empty
|
|
string).
|
|
|
|
In contrast to g_uri_join(), this allows specifying the components
|
|
of the ‘userinfo’ separately. It otherwise behaves the same.
|
|
|
|
%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set
|
|
in @flags.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an absolute URI string</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags describing how to build the URI string</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
<parameter name="scheme" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the URI scheme, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="user" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the user component of the userinfo, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="password" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the password component of the userinfo, or
|
|
%NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="auth_params" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the auth params of the userinfo, or
|
|
%NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="host" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the host component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="port" transfer-ownership="none">
|
|
<doc xml:space="preserve">the port, or `-1`</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="path" transfer-ownership="none">
|
|
<doc xml:space="preserve">the path component</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="query" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the query component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="fragment" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the fragment, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="list_extract_uris" c:identifier="g_uri_list_extract_uris" version="2.6">
|
|
<doc xml:space="preserve">Splits an URI list conforming to the text/uri-list
|
|
mime type defined in RFC 2483 into individual URIs,
|
|
discarding any comments. The URIs are not validated.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated %NULL-terminated list
|
|
of strings holding the individual URIs. The array should be freed
|
|
with g_strfreev().</doc>
|
|
<array c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">an URI list</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="parse" c:identifier="g_uri_parse" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Parses @uri_string according to @flags. If the result is not a
|
|
valid [absolute URI][relative-absolute-uris], it will be discarded, and an
|
|
error returned.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GUri.</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string representing an absolute URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags describing how to parse @uri_string</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="parse_params" c:identifier="g_uri_parse_params" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Many URI schemes include one or more attribute/value pairs as part of the URI
|
|
value. This method can be used to parse them into a hash table. When an
|
|
attribute has multiple occurrences, the last value is the final returned
|
|
value. If you need to handle repeated attributes differently, use
|
|
#GUriParamsIter.
|
|
|
|
The @params string is assumed to still be `%`-encoded, but the returned
|
|
values will be fully decoded. (Thus it is possible that the returned values
|
|
may contain `=` or @separators, if the value was encoded in the input.)
|
|
Invalid `%`-encoding is treated as with the %G_URI_FLAGS_PARSE_RELAXED
|
|
rules for g_uri_parse(). (However, if @params is the path or query string
|
|
from a #GUri that was parsed without %G_URI_FLAGS_PARSE_RELAXED and
|
|
%G_URI_FLAGS_ENCODED, then you already know that it does not contain any
|
|
invalid encoding.)
|
|
|
|
%G_URI_PARAMS_WWW_FORM is handled as documented for g_uri_params_iter_init().
|
|
|
|
If %G_URI_PARAMS_CASE_INSENSITIVE is passed to @flags, attributes will be
|
|
compared case-insensitively, so a params string `attr=123&Attr=456` will only
|
|
return a single attribute–value pair, `Attr=456`. Case will be preserved in
|
|
the returned attributes.
|
|
|
|
If @params cannot be parsed (for example, it contains two @separators
|
|
characters in a row), then @error is set and %NULL is returned.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">A hash table of
|
|
attribute/value pairs, with both names and values fully-decoded; or %NULL
|
|
on error.</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="utf8"/>
|
|
<type name="utf8"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="params" transfer-ownership="none">
|
|
<doc xml:space="preserve">a `%`-encoded string containing `attribute=value`
|
|
parameters</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @params, or `-1` if it is nul-terminated</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="separators" transfer-ownership="none">
|
|
<doc xml:space="preserve">the separator byte character set between parameters. (usually
|
|
`&`, but sometimes `;` or both `&;`). Note that this function works on
|
|
bytes not characters, so it can't be used to delimit UTF-8 strings for
|
|
anything but ASCII characters. You may pass an empty set, in which case
|
|
no splitting will occur.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags to modify the way the parameters are handled.</doc>
|
|
<type name="UriParamsFlags" c:type="GUriParamsFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="parse_scheme" c:identifier="g_uri_parse_scheme" version="2.16">
|
|
<doc xml:space="preserve">Gets the scheme portion of a URI string.
|
|
[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
|
|
as:
|
|
|[
|
|
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
|
|
]|
|
|
Common schemes include `file`, `https`, `svn+ssh`, etc.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">The ‘scheme’ component of the URI, or
|
|
%NULL on error. The returned string should be freed when no longer needed.</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="peek_scheme" c:identifier="g_uri_peek_scheme" version="2.66">
|
|
<doc xml:space="preserve">Gets the scheme portion of a URI string.
|
|
[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
|
|
as:
|
|
|[
|
|
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
|
|
]|
|
|
Common schemes include `file`, `https`, `svn+ssh`, etc.
|
|
|
|
Unlike g_uri_parse_scheme(), the returned scheme is normalized to
|
|
all-lowercase and does not need to be freed.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">The ‘scheme’ component of the URI, or
|
|
%NULL on error. The returned string is normalized to all-lowercase, and
|
|
interned via g_intern_string(), so it does not need to be freed.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="resolve_relative" c:identifier="g_uri_resolve_relative" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Parses @uri_ref according to @flags and, if it is a
|
|
[relative URI][relative-absolute-uris], resolves it relative to
|
|
@base_uri_string. If the result is not a valid absolute URI, it will be
|
|
discarded, and an error returned.
|
|
|
|
(If @base_uri_string is %NULL, this just returns @uri_ref, or
|
|
%NULL if @uri_ref is invalid or not absolute.)</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the resolved URI string.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="base_uri_string" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string representing a base URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="uri_ref" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string representing a relative or absolute URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags describing how to parse @uri_ref</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="split" c:identifier="g_uri_split" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Parses @uri_ref (which can be an
|
|
[absolute or relative URI][relative-absolute-uris]) according to @flags, and
|
|
returns the pieces. Any component that doesn't appear in @uri_ref will be
|
|
returned as %NULL (but note that all URIs always have a path component,
|
|
though it may be the empty string).
|
|
|
|
If @flags contains %G_URI_FLAGS_ENCODED, then `%`-encoded characters in
|
|
@uri_ref will remain encoded in the output strings. (If not,
|
|
then all such characters will be decoded.) Note that decoding will
|
|
only work if the URI components are ASCII or UTF-8, so you will
|
|
need to use %G_URI_FLAGS_ENCODED if they are not.
|
|
|
|
Note that the %G_URI_FLAGS_HAS_PASSWORD and
|
|
%G_URI_FLAGS_HAS_AUTH_PARAMS @flags are ignored by g_uri_split(),
|
|
since it always returns only the full userinfo; use
|
|
g_uri_split_with_user() if you want it split up.</doc>
|
|
<return-value transfer-ownership="none" skip="1">
|
|
<doc xml:space="preserve">%TRUE if @uri_ref parsed successfully, %FALSE
|
|
on error.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri_ref" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string containing a relative or absolute URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags for parsing @uri_ref</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
<parameter name="scheme" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the scheme (converted to lowercase), or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="userinfo" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the userinfo, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="host" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
host, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="port" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
port, or `-1`</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="path" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
path</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="query" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
query, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="fragment" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the fragment, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="split_network" c:identifier="g_uri_split_network" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Parses @uri_string (which must be an [absolute URI][relative-absolute-uris])
|
|
according to @flags, and returns the pieces relevant to connecting to a host.
|
|
See the documentation for g_uri_split() for more details; this is
|
|
mostly a wrapper around that function with simpler arguments.
|
|
However, it will return an error if @uri_string is a relative URI,
|
|
or does not contain a hostname component.</doc>
|
|
<return-value transfer-ownership="none" skip="1">
|
|
<doc xml:space="preserve">%TRUE if @uri_string parsed successfully,
|
|
%FALSE on error.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string containing an absolute URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags for parsing @uri_string</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
<parameter name="scheme" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the scheme (converted to lowercase), or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="host" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
host, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="port" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
port, or `-1`</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="split_with_user" c:identifier="g_uri_split_with_user" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Parses @uri_ref (which can be an
|
|
[absolute or relative URI][relative-absolute-uris]) according to @flags, and
|
|
returns the pieces. Any component that doesn't appear in @uri_ref will be
|
|
returned as %NULL (but note that all URIs always have a path component,
|
|
though it may be the empty string).
|
|
|
|
See g_uri_split(), and the definition of #GUriFlags, for more
|
|
information on the effect of @flags. Note that @password will only
|
|
be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and
|
|
@auth_params will only be parsed out if @flags contains
|
|
%G_URI_FLAGS_HAS_AUTH_PARAMS.</doc>
|
|
<return-value transfer-ownership="none" skip="1">
|
|
<doc xml:space="preserve">%TRUE if @uri_ref parsed successfully, %FALSE
|
|
on error.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri_ref" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string containing a relative or absolute URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags for parsing @uri_ref</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
<parameter name="scheme" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the scheme (converted to lowercase), or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="user" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the user, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="password" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the password, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="auth_params" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the auth_params, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="host" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
host, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="port" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
port, or `-1`</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="path" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
path</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="query" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
query, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="fragment" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the fragment, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unescape_bytes" c:identifier="g_uri_unescape_bytes" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Unescapes a segment of an escaped string as binary data.
|
|
|
|
Note that in contrast to g_uri_unescape_string(), this does allow
|
|
nul bytes to appear in the output.
|
|
|
|
If any of the characters in @illegal_characters appears as an escaped
|
|
character in @escaped_string, then that is an error and %NULL will be
|
|
returned. This is useful if you want to avoid for instance having a slash
|
|
being expanded in an escaped path element, which might confuse pathname
|
|
handling.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an unescaped version of @escaped_string or %NULL on
|
|
error (if decoding failed, using %G_URI_ERROR_FAILED error code). The
|
|
returned #GBytes should be unreffed when no longer needed.</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="escaped_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">A URI-escaped string</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length (in bytes) of @escaped_string to escape, or `-1` if it
|
|
is nul-terminated.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="illegal_characters" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string of illegal characters
|
|
not to be allowed, or %NULL.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unescape_segment" c:identifier="g_uri_unescape_segment" version="2.16">
|
|
<doc xml:space="preserve">Unescapes a segment of an escaped string.
|
|
|
|
If any of the characters in @illegal_characters or the NUL
|
|
character appears as an escaped character in @escaped_string, then
|
|
that is an error and %NULL will be returned. This is useful if you
|
|
want to avoid for instance having a slash being expanded in an
|
|
escaped path element, which might confuse pathname handling.
|
|
|
|
Note: `NUL` byte is not accepted in the output, in contrast to
|
|
g_uri_unescape_bytes().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an unescaped version of @escaped_string or %NULL on error.
|
|
The returned string should be freed when no longer needed. As a
|
|
special case if %NULL is given for @escaped_string, this function
|
|
will return %NULL.</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="escaped_string" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">A string, may be %NULL</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="escaped_string_end" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">Pointer to end of @escaped_string,
|
|
may be %NULL</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="illegal_characters" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">An optional string of illegal
|
|
characters not to be allowed, may be %NULL</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unescape_string" c:identifier="g_uri_unescape_string" version="2.16">
|
|
<doc xml:space="preserve">Unescapes a whole escaped string.
|
|
|
|
If any of the characters in @illegal_characters or the NUL
|
|
character appears as an escaped character in @escaped_string, then
|
|
that is an error and %NULL will be returned. This is useful if you
|
|
want to avoid for instance having a slash being expanded in an
|
|
escaped path element, which might confuse pathname handling.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an unescaped version of @escaped_string. The returned string
|
|
should be freed when no longer needed.</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="escaped_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">an escaped string to be unescaped.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="illegal_characters" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string of illegal characters
|
|
not to be allowed, or %NULL.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<enumeration name="UriError" version="2.66" c:type="GUriError" glib:error-domain="g-uri-quark">
|
|
<doc xml:space="preserve">Error codes returned by #GUri methods.</doc>
|
|
<member name="failed" value="0" c:identifier="G_URI_ERROR_FAILED">
|
|
<doc xml:space="preserve">Generic error if no more specific error is available.
|
|
See the error message for details.</doc>
|
|
</member>
|
|
<member name="bad_scheme" value="1" c:identifier="G_URI_ERROR_BAD_SCHEME">
|
|
<doc xml:space="preserve">The scheme of a URI could not be parsed.</doc>
|
|
</member>
|
|
<member name="bad_user" value="2" c:identifier="G_URI_ERROR_BAD_USER">
|
|
<doc xml:space="preserve">The user/userinfo of a URI could not be parsed.</doc>
|
|
</member>
|
|
<member name="bad_password" value="3" c:identifier="G_URI_ERROR_BAD_PASSWORD">
|
|
<doc xml:space="preserve">The password of a URI could not be parsed.</doc>
|
|
</member>
|
|
<member name="bad_auth_params" value="4" c:identifier="G_URI_ERROR_BAD_AUTH_PARAMS">
|
|
<doc xml:space="preserve">The authentication parameters of a URI could not be parsed.</doc>
|
|
</member>
|
|
<member name="bad_host" value="5" c:identifier="G_URI_ERROR_BAD_HOST">
|
|
<doc xml:space="preserve">The host of a URI could not be parsed.</doc>
|
|
</member>
|
|
<member name="bad_port" value="6" c:identifier="G_URI_ERROR_BAD_PORT">
|
|
<doc xml:space="preserve">The port of a URI could not be parsed.</doc>
|
|
</member>
|
|
<member name="bad_path" value="7" c:identifier="G_URI_ERROR_BAD_PATH">
|
|
<doc xml:space="preserve">The path of a URI could not be parsed.</doc>
|
|
</member>
|
|
<member name="bad_query" value="8" c:identifier="G_URI_ERROR_BAD_QUERY">
|
|
<doc xml:space="preserve">The query of a URI could not be parsed.</doc>
|
|
</member>
|
|
<member name="bad_fragment" value="9" c:identifier="G_URI_ERROR_BAD_FRAGMENT">
|
|
<doc xml:space="preserve">The fragment of a URI could not be parsed.</doc>
|
|
</member>
|
|
</enumeration>
|
|
<bitfield name="UriFlags" version="2.66" c:type="GUriFlags">
|
|
<doc xml:space="preserve">Flags that describe a URI.
|
|
|
|
When parsing a URI, if you need to choose different flags based on
|
|
the type of URI, you can use g_uri_peek_scheme() on the URI string
|
|
to check the scheme first, and use that to decide what flags to
|
|
parse it with.</doc>
|
|
<member name="none" value="0" c:identifier="G_URI_FLAGS_NONE">
|
|
<doc xml:space="preserve">No flags set.</doc>
|
|
</member>
|
|
<member name="parse_relaxed" value="1" c:identifier="G_URI_FLAGS_PARSE_RELAXED">
|
|
<doc xml:space="preserve">Parse the URI more relaxedly than the
|
|
[RFC 3986](https://tools.ietf.org/html/rfc3986) grammar specifies,
|
|
fixing up or ignoring common mistakes in URIs coming from external
|
|
sources. This is also needed for some obscure URI schemes where `;`
|
|
separates the host from the path. Don’t use this flag unless you need to.</doc>
|
|
</member>
|
|
<member name="has_password" value="2" c:identifier="G_URI_FLAGS_HAS_PASSWORD">
|
|
<doc xml:space="preserve">The userinfo field may contain a password,
|
|
which will be separated from the username by `:`.</doc>
|
|
</member>
|
|
<member name="has_auth_params" value="4" c:identifier="G_URI_FLAGS_HAS_AUTH_PARAMS">
|
|
<doc xml:space="preserve">The userinfo may contain additional
|
|
authentication-related parameters, which will be separated from
|
|
the username and/or password by `;`.</doc>
|
|
</member>
|
|
<member name="encoded" value="8" c:identifier="G_URI_FLAGS_ENCODED">
|
|
<doc xml:space="preserve">When parsing a URI, this indicates that `%`-encoded
|
|
characters in the userinfo, path, query, and fragment fields
|
|
should not be decoded. (And likewise the host field if
|
|
%G_URI_FLAGS_NON_DNS is also set.) When building a URI, it indicates
|
|
that you have already `%`-encoded the components, and so #GUri
|
|
should not do any encoding itself.</doc>
|
|
</member>
|
|
<member name="non_dns" value="16" c:identifier="G_URI_FLAGS_NON_DNS">
|
|
<doc xml:space="preserve">The host component should not be assumed to be a
|
|
DNS hostname or IP address (for example, for `smb` URIs with NetBIOS
|
|
hostnames).</doc>
|
|
</member>
|
|
<member name="encoded_query" value="32" c:identifier="G_URI_FLAGS_ENCODED_QUERY">
|
|
<doc xml:space="preserve">Same as %G_URI_FLAGS_ENCODED, for the query
|
|
field only.</doc>
|
|
</member>
|
|
<member name="encoded_path" value="64" c:identifier="G_URI_FLAGS_ENCODED_PATH">
|
|
<doc xml:space="preserve">Same as %G_URI_FLAGS_ENCODED, for the path only.</doc>
|
|
</member>
|
|
<member name="encoded_fragment" value="128" c:identifier="G_URI_FLAGS_ENCODED_FRAGMENT">
|
|
<doc xml:space="preserve">Same as %G_URI_FLAGS_ENCODED, for the
|
|
fragment only.</doc>
|
|
</member>
|
|
</bitfield>
|
|
<bitfield name="UriHideFlags" version="2.66" c:type="GUriHideFlags">
|
|
<doc xml:space="preserve">Flags describing what parts of the URI to hide in
|
|
g_uri_to_string_partial(). Note that %G_URI_HIDE_PASSWORD and
|
|
%G_URI_HIDE_AUTH_PARAMS will only work if the #GUri was parsed with
|
|
the corresponding flags.</doc>
|
|
<member name="none" value="0" c:identifier="G_URI_HIDE_NONE">
|
|
<doc xml:space="preserve">No flags set.</doc>
|
|
</member>
|
|
<member name="userinfo" value="1" c:identifier="G_URI_HIDE_USERINFO">
|
|
<doc xml:space="preserve">Hide the userinfo.</doc>
|
|
</member>
|
|
<member name="password" value="2" c:identifier="G_URI_HIDE_PASSWORD">
|
|
<doc xml:space="preserve">Hide the password.</doc>
|
|
</member>
|
|
<member name="auth_params" value="4" c:identifier="G_URI_HIDE_AUTH_PARAMS">
|
|
<doc xml:space="preserve">Hide the auth_params.</doc>
|
|
</member>
|
|
<member name="query" value="8" c:identifier="G_URI_HIDE_QUERY">
|
|
<doc xml:space="preserve">Hide the query.</doc>
|
|
</member>
|
|
<member name="fragment" value="16" c:identifier="G_URI_HIDE_FRAGMENT">
|
|
<doc xml:space="preserve">Hide the fragment.</doc>
|
|
</member>
|
|
</bitfield>
|
|
<bitfield name="UriParamsFlags" version="2.66" c:type="GUriParamsFlags">
|
|
<doc xml:space="preserve">Flags modifying the way parameters are handled by g_uri_parse_params() and
|
|
#GUriParamsIter.</doc>
|
|
<member name="none" value="0" c:identifier="G_URI_PARAMS_NONE">
|
|
<doc xml:space="preserve">No flags set.</doc>
|
|
</member>
|
|
<member name="case_insensitive" value="1" c:identifier="G_URI_PARAMS_CASE_INSENSITIVE">
|
|
<doc xml:space="preserve">Parameter names are case insensitive.</doc>
|
|
</member>
|
|
<member name="www_form" value="2" c:identifier="G_URI_PARAMS_WWW_FORM">
|
|
<doc xml:space="preserve">Replace `+` with space character. Only useful for
|
|
URLs on the web, using the `https` or `http` schemas.</doc>
|
|
</member>
|
|
<member name="parse_relaxed" value="4" c:identifier="G_URI_PARAMS_PARSE_RELAXED">
|
|
<doc xml:space="preserve">See %G_URI_FLAGS_PARSE_RELAXED.</doc>
|
|
</member>
|
|
</bitfield>
|
|
<record name="UriParamsIter" c:type="GUriParamsIter" version="2.66">
|
|
<doc xml:space="preserve">Many URI schemes include one or more attribute/value pairs as part of the URI
|
|
value. For example `scheme://server/path?query=string&is=there` has two
|
|
attributes – `query=string` and `is=there` – in its query part.
|
|
|
|
A #GUriParamsIter structure represents an iterator that can be used to
|
|
iterate over the attribute/value pairs of a URI query string. #GUriParamsIter
|
|
structures are typically allocated on the stack and then initialized with
|
|
g_uri_params_iter_init(). See the documentation for g_uri_params_iter_init()
|
|
for a usage example.</doc>
|
|
<field name="dummy0" readable="0" private="1">
|
|
<type name="gint" c:type="gint"/>
|
|
</field>
|
|
<field name="dummy1" readable="0" private="1">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="dummy2" readable="0" private="1">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</field>
|
|
<field name="dummy3" readable="0" private="1">
|
|
<array zero-terminated="0" fixed-size="256">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</field>
|
|
<method name="init" c:identifier="g_uri_params_iter_init" version="2.66">
|
|
<doc xml:space="preserve">Initializes an attribute/value pair iterator.
|
|
|
|
The iterator keeps pointers to the @params and @separators arguments, those
|
|
variables must thus outlive the iterator and not be modified during the
|
|
iteration.
|
|
|
|
If %G_URI_PARAMS_WWW_FORM is passed in @flags, `+` characters in the param
|
|
string will be replaced with spaces in the output. For example, `foo=bar+baz`
|
|
will give attribute `foo` with value `bar baz`. This is commonly used on the
|
|
web (the `https` and `http` schemes only), but is deprecated in favour of
|
|
the equivalent of encoding spaces as `%20`.
|
|
|
|
Unlike with g_uri_parse_params(), %G_URI_PARAMS_CASE_INSENSITIVE has no
|
|
effect if passed to @flags for g_uri_params_iter_init(). The caller is
|
|
responsible for doing their own case-insensitive comparisons.
|
|
|
|
|[<!-- language="C" -->
|
|
GUriParamsIter iter;
|
|
GError *error = NULL;
|
|
gchar *unowned_attr, *unowned_value;
|
|
|
|
g_uri_params_iter_init (&iter, "foo=bar&baz=bar&Foo=frob&baz=bar2", -1, "&", G_URI_PARAMS_NONE);
|
|
while (g_uri_params_iter_next (&iter, &unowned_attr, &unowned_value, &error))
|
|
{
|
|
g_autofree gchar *attr = g_steal_pointer (&unowned_attr);
|
|
g_autofree gchar *value = g_steal_pointer (&unowned_value);
|
|
// do something with attr and value; this code will be called 4 times
|
|
// for the params string in this example: once with attr=foo and value=bar,
|
|
// then with baz/bar, then Foo/frob, then baz/bar2.
|
|
}
|
|
if (error)
|
|
// handle parsing error
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">an uninitialized #GUriParamsIter</doc>
|
|
<type name="UriParamsIter" c:type="GUriParamsIter*"/>
|
|
</instance-parameter>
|
|
<parameter name="params" transfer-ownership="none">
|
|
<doc xml:space="preserve">a `%`-encoded string containing `attribute=value`
|
|
parameters</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @params, or `-1` if it is nul-terminated</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="separators" transfer-ownership="none">
|
|
<doc xml:space="preserve">the separator byte character set between parameters. (usually
|
|
`&`, but sometimes `;` or both `&;`). Note that this function works on
|
|
bytes not characters, so it can't be used to delimit UTF-8 strings for
|
|
anything but ASCII characters. You may pass an empty set, in which case
|
|
no splitting will occur.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags to modify the way the parameters are handled.</doc>
|
|
<type name="UriParamsFlags" c:type="GUriParamsFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="next" c:identifier="g_uri_params_iter_next" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Advances @iter and retrieves the next attribute/value. %FALSE is returned if
|
|
an error has occurred (in which case @error is set), or if the end of the
|
|
iteration is reached (in which case @attribute and @value are set to %NULL
|
|
and the iterator becomes invalid). If %TRUE is returned,
|
|
g_uri_params_iter_next() may be called again to receive another
|
|
attribute/value pair.
|
|
|
|
Note that the same @attribute may be returned multiple times, since URIs
|
|
allow repeated attributes.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%FALSE if the end of the parameters has been reached or an error was
|
|
encountered. %TRUE otherwise.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">an initialized #GUriParamsIter</doc>
|
|
<type name="UriParamsIter" c:type="GUriParamsIter*"/>
|
|
</instance-parameter>
|
|
<parameter name="attribute" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the attribute, or %NULL.</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="value" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the value, or %NULL.</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<enumeration name="UserDirectory" version="2.14" c:type="GUserDirectory">
|
|
<doc xml:space="preserve">These are logical ids for special directories which are defined
|
|
depending on the platform used. You should use g_get_user_special_dir()
|
|
to retrieve the full path associated to the logical id.
|
|
|
|
The #GUserDirectory enumeration can be extended at later date. Not
|
|
every platform has a directory for every logical id in this
|
|
enumeration.</doc>
|
|
<member name="directory_desktop" value="0" c:identifier="G_USER_DIRECTORY_DESKTOP">
|
|
<doc xml:space="preserve">the user's Desktop directory</doc>
|
|
</member>
|
|
<member name="directory_documents" value="1" c:identifier="G_USER_DIRECTORY_DOCUMENTS">
|
|
<doc xml:space="preserve">the user's Documents directory</doc>
|
|
</member>
|
|
<member name="directory_download" value="2" c:identifier="G_USER_DIRECTORY_DOWNLOAD">
|
|
<doc xml:space="preserve">the user's Downloads directory</doc>
|
|
</member>
|
|
<member name="directory_music" value="3" c:identifier="G_USER_DIRECTORY_MUSIC">
|
|
<doc xml:space="preserve">the user's Music directory</doc>
|
|
</member>
|
|
<member name="directory_pictures" value="4" c:identifier="G_USER_DIRECTORY_PICTURES">
|
|
<doc xml:space="preserve">the user's Pictures directory</doc>
|
|
</member>
|
|
<member name="directory_public_share" value="5" c:identifier="G_USER_DIRECTORY_PUBLIC_SHARE">
|
|
<doc xml:space="preserve">the user's shared directory</doc>
|
|
</member>
|
|
<member name="directory_templates" value="6" c:identifier="G_USER_DIRECTORY_TEMPLATES">
|
|
<doc xml:space="preserve">the user's Templates directory</doc>
|
|
</member>
|
|
<member name="directory_videos" value="7" c:identifier="G_USER_DIRECTORY_VIDEOS">
|
|
<doc xml:space="preserve">the user's Movies directory</doc>
|
|
</member>
|
|
<member name="n_directories" value="8" c:identifier="G_USER_N_DIRECTORIES">
|
|
<doc xml:space="preserve">the number of enum values</doc>
|
|
</member>
|
|
</enumeration>
|
|
<function-macro name="VARIANT_BUILDER_INIT" c:identifier="G_VARIANT_BUILDER_INIT" version="2.50" introspectable="0">
|
|
<doc xml:space="preserve">A stack-allocated #GVariantBuilder must be initialized if it is
|
|
used together with g_auto() to avoid warnings or crashes if
|
|
function returns before g_variant_builder_init() is called on the
|
|
builder. This macro can be used as initializer instead of an
|
|
explicit zeroing a variable when declaring it and a following
|
|
g_variant_builder_init(), but it cannot be assigned to a variable.
|
|
|
|
The passed @variant_type should be a static GVariantType to avoid
|
|
lifetime issues, as copying the @variant_type does not happen in
|
|
the G_VARIANT_BUILDER_INIT() call, but rather in functions that
|
|
make sure that #GVariantBuilder is valid.
|
|
|
|
|[
|
|
g_auto(GVariantBuilder) builder = G_VARIANT_BUILDER_INIT (G_VARIANT_TYPE_BYTESTRING);
|
|
]|</doc>
|
|
<parameters>
|
|
<parameter name="variant_type">
|
|
<doc xml:space="preserve">a const GVariantType*</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="VARIANT_DICT_INIT" c:identifier="G_VARIANT_DICT_INIT" version="2.50" introspectable="0">
|
|
<doc xml:space="preserve">A stack-allocated #GVariantDict must be initialized if it is used
|
|
together with g_auto() to avoid warnings or crashes if function
|
|
returns before g_variant_dict_init() is called on the builder.
|
|
This macro can be used as initializer instead of an explicit
|
|
zeroing a variable when declaring it and a following
|
|
g_variant_dict_init(), but it cannot be assigned to a variable.
|
|
|
|
The passed @asv has to live long enough for #GVariantDict to gather
|
|
the entries from, as the gathering does not happen in the
|
|
G_VARIANT_DICT_INIT() call, but rather in functions that make sure
|
|
that #GVariantDict is valid. In context where the initialization
|
|
value has to be a constant expression, the only possible value of
|
|
@asv is %NULL. It is still possible to call g_variant_dict_init()
|
|
safely with a different @asv right after the variable was
|
|
initialized with G_VARIANT_DICT_INIT().
|
|
|
|
|[
|
|
g_autoptr(GVariant) variant = get_asv_variant ();
|
|
g_auto(GVariantDict) dict = G_VARIANT_DICT_INIT (variant);
|
|
]|</doc>
|
|
<parameters>
|
|
<parameter name="asv">
|
|
<doc xml:space="preserve">a GVariant*</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="VARIANT_TYPE" c:identifier="G_VARIANT_TYPE" introspectable="0">
|
|
<doc xml:space="preserve">Converts a string to a const #GVariantType. Depending on the
|
|
current debugging level, this function may perform a runtime check
|
|
to ensure that @string is a valid GVariant type string.
|
|
|
|
It is always a programmer error to use this macro with an invalid
|
|
type string. If in doubt, use g_variant_type_string_is_valid() to
|
|
check if the string is valid.
|
|
|
|
Since 2.24</doc>
|
|
<parameters>
|
|
<parameter name="type_string">
|
|
<doc xml:space="preserve">a well-formed #GVariantType type string</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="VA_COPY" c:identifier="G_VA_COPY" introspectable="0">
|
|
<doc xml:space="preserve">Portable way to copy va_list variables.
|
|
|
|
In order to use this function, you must include string.h yourself,
|
|
because this macro may use memmove() and GLib does not include
|
|
string.h for you.</doc>
|
|
<parameters>
|
|
<parameter name="ap1">
|
|
<doc xml:space="preserve">the va_list variable to place a copy of @ap2 in</doc>
|
|
</parameter>
|
|
<parameter name="ap2">
|
|
<doc xml:space="preserve">a va_list</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="VA_COPY_AS_ARRAY" value="1" c:type="G_VA_COPY_AS_ARRAY">
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<constant name="VERSION_MIN_REQUIRED" value="2" c:type="GLIB_VERSION_MIN_REQUIRED" version="2.32">
|
|
<doc xml:space="preserve">A macro that should be defined by the user prior to including
|
|
the glib.h header.
|
|
The definition should be one of the predefined GLib version
|
|
macros: %GLIB_VERSION_2_26, %GLIB_VERSION_2_28,...
|
|
|
|
This macro defines the earliest version of GLib that the package is
|
|
required to be able to compile against.
|
|
|
|
If the compiler is configured to warn about the use of deprecated
|
|
functions, then using functions that were deprecated in version
|
|
%GLIB_VERSION_MIN_REQUIRED or earlier will cause warnings (but
|
|
using functions deprecated in later releases will not).</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<record name="Variant" c:type="GVariant" version="2.24" glib:type-name="GVariant" glib:get-type="intern" c:symbol-prefix="variant">
|
|
<doc xml:space="preserve">#GVariant is a variant datatype; it can contain one or more values
|
|
along with information about the type of the values.
|
|
|
|
A #GVariant may contain simple types, like an integer, or a boolean value;
|
|
or complex types, like an array of two strings, or a dictionary of key
|
|
value pairs. A #GVariant is also immutable: once it's been created neither
|
|
its type nor its content can be modified further.
|
|
|
|
GVariant is useful whenever data needs to be serialized, for example when
|
|
sending method parameters in DBus, or when saving settings using GSettings.
|
|
|
|
When creating a new #GVariant, you pass the data you want to store in it
|
|
along with a string representing the type of data you wish to pass to it.
|
|
|
|
For instance, if you want to create a #GVariant holding an integer value you
|
|
can use:
|
|
|
|
|[<!-- language="C" -->
|
|
GVariant *v = g_variant_new ("u", 40);
|
|
]|
|
|
|
|
The string "u" in the first argument tells #GVariant that the data passed to
|
|
the constructor (40) is going to be an unsigned integer.
|
|
|
|
More advanced examples of #GVariant in use can be found in documentation for
|
|
[GVariant format strings][gvariant-format-strings-pointers].
|
|
|
|
The range of possible values is determined by the type.
|
|
|
|
The type system used by #GVariant is #GVariantType.
|
|
|
|
#GVariant instances always have a type and a value (which are given
|
|
at construction time). The type and value of a #GVariant instance
|
|
can never change other than by the #GVariant itself being
|
|
destroyed. A #GVariant cannot contain a pointer.
|
|
|
|
#GVariant is reference counted using g_variant_ref() and
|
|
g_variant_unref(). #GVariant also has floating reference counts --
|
|
see g_variant_ref_sink().
|
|
|
|
#GVariant is completely threadsafe. A #GVariant instance can be
|
|
concurrently accessed in any way from any number of threads without
|
|
problems.
|
|
|
|
#GVariant is heavily optimised for dealing with data in serialised
|
|
form. It works particularly well with data located in memory-mapped
|
|
files. It can perform nearly all deserialisation operations in a
|
|
small constant time, usually touching only a single memory page.
|
|
Serialised #GVariant data can also be sent over the network.
|
|
|
|
#GVariant is largely compatible with D-Bus. Almost all types of
|
|
#GVariant instances can be sent over D-Bus. See #GVariantType for
|
|
exceptions. (However, #GVariant's serialisation format is not the same
|
|
as the serialisation format of a D-Bus message body: use #GDBusMessage,
|
|
in the gio library, for those.)
|
|
|
|
For space-efficiency, the #GVariant serialisation format does not
|
|
automatically include the variant's length, type or endianness,
|
|
which must either be implied from context (such as knowledge that a
|
|
particular file format always contains a little-endian
|
|
%G_VARIANT_TYPE_VARIANT which occupies the whole length of the file)
|
|
or supplied out-of-band (for instance, a length, type and/or endianness
|
|
indicator could be placed at the beginning of a file, network message
|
|
or network stream).
|
|
|
|
A #GVariant's size is limited mainly by any lower level operating
|
|
system constraints, such as the number of bits in #gsize. For
|
|
example, it is reasonable to have a 2GB file mapped into memory
|
|
with #GMappedFile, and call g_variant_new_from_data() on it.
|
|
|
|
For convenience to C programmers, #GVariant features powerful
|
|
varargs-based value construction and destruction. This feature is
|
|
designed to be embedded in other libraries.
|
|
|
|
There is a Python-inspired text language for describing #GVariant
|
|
values. #GVariant includes a printer for this language and a parser
|
|
with type inferencing.
|
|
|
|
## Memory Use
|
|
|
|
#GVariant tries to be quite efficient with respect to memory use.
|
|
This section gives a rough idea of how much memory is used by the
|
|
current implementation. The information here is subject to change
|
|
in the future.
|
|
|
|
The memory allocated by #GVariant can be grouped into 4 broad
|
|
purposes: memory for serialised data, memory for the type
|
|
information cache, buffer management memory and memory for the
|
|
#GVariant structure itself.
|
|
|
|
## Serialised Data Memory
|
|
|
|
This is the memory that is used for storing GVariant data in
|
|
serialised form. This is what would be sent over the network or
|
|
what would end up on disk, not counting any indicator of the
|
|
endianness, or of the length or type of the top-level variant.
|
|
|
|
The amount of memory required to store a boolean is 1 byte. 16,
|
|
32 and 64 bit integers and double precision floating point numbers
|
|
use their "natural" size. Strings (including object path and
|
|
signature strings) are stored with a nul terminator, and as such
|
|
use the length of the string plus 1 byte.
|
|
|
|
Maybe types use no space at all to represent the null value and
|
|
use the same amount of space (sometimes plus one byte) as the
|
|
equivalent non-maybe-typed value to represent the non-null case.
|
|
|
|
Arrays use the amount of space required to store each of their
|
|
members, concatenated. Additionally, if the items stored in an
|
|
array are not of a fixed-size (ie: strings, other arrays, etc)
|
|
then an additional framing offset is stored for each item. The
|
|
size of this offset is either 1, 2 or 4 bytes depending on the
|
|
overall size of the container. Additionally, extra padding bytes
|
|
are added as required for alignment of child values.
|
|
|
|
Tuples (including dictionary entries) use the amount of space
|
|
required to store each of their members, concatenated, plus one
|
|
framing offset (as per arrays) for each non-fixed-sized item in
|
|
the tuple, except for the last one. Additionally, extra padding
|
|
bytes are added as required for alignment of child values.
|
|
|
|
Variants use the same amount of space as the item inside of the
|
|
variant, plus 1 byte, plus the length of the type string for the
|
|
item inside the variant.
|
|
|
|
As an example, consider a dictionary mapping strings to variants.
|
|
In the case that the dictionary is empty, 0 bytes are required for
|
|
the serialisation.
|
|
|
|
If we add an item "width" that maps to the int32 value of 500 then
|
|
we will use 4 byte to store the int32 (so 6 for the variant
|
|
containing it) and 6 bytes for the string. The variant must be
|
|
aligned to 8 after the 6 bytes of the string, so that's 2 extra
|
|
bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used
|
|
for the dictionary entry. An additional 1 byte is added to the
|
|
array as a framing offset making a total of 15 bytes.
|
|
|
|
If we add another entry, "title" that maps to a nullable string
|
|
that happens to have a value of null, then we use 0 bytes for the
|
|
null value (and 3 bytes for the variant to contain it along with
|
|
its type string) plus 6 bytes for the string. Again, we need 2
|
|
padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes.
|
|
|
|
We now require extra padding between the two items in the array.
|
|
After the 14 bytes of the first item, that's 2 bytes required.
|
|
We now require 2 framing offsets for an extra two
|
|
bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item
|
|
dictionary.
|
|
|
|
## Type Information Cache
|
|
|
|
For each GVariant type that currently exists in the program a type
|
|
information structure is kept in the type information cache. The
|
|
type information structure is required for rapid deserialisation.
|
|
|
|
Continuing with the above example, if a #GVariant exists with the
|
|
type "a{sv}" then a type information struct will exist for
|
|
"a{sv}", "{sv}", "s", and "v". Multiple uses of the same type
|
|
will share the same type information. Additionally, all
|
|
single-digit types are stored in read-only static memory and do
|
|
not contribute to the writable memory footprint of a program using
|
|
#GVariant.
|
|
|
|
Aside from the type information structures stored in read-only
|
|
memory, there are two forms of type information. One is used for
|
|
container types where there is a single element type: arrays and
|
|
maybe types. The other is used for container types where there
|
|
are multiple element types: tuples and dictionary entries.
|
|
|
|
Array type info structures are 6 * sizeof (void *), plus the
|
|
memory required to store the type string itself. This means that
|
|
on 32-bit systems, the cache entry for "a{sv}" would require 30
|
|
bytes of memory (plus malloc overhead).
|
|
|
|
Tuple type info structures are 6 * sizeof (void *), plus 4 *
|
|
sizeof (void *) for each item in the tuple, plus the memory
|
|
required to store the type string itself. A 2-item tuple, for
|
|
example, would have a type information structure that consumed
|
|
writable memory in the size of 14 * sizeof (void *) (plus type
|
|
string) This means that on 32-bit systems, the cache entry for
|
|
"{sv}" would require 61 bytes of memory (plus malloc overhead).
|
|
|
|
This means that in total, for our "a{sv}" example, 91 bytes of
|
|
type information would be allocated.
|
|
|
|
The type information cache, additionally, uses a #GHashTable to
|
|
store and look up the cached items and stores a pointer to this
|
|
hash table in static storage. The hash table is freed when there
|
|
are zero items in the type cache.
|
|
|
|
Although these sizes may seem large it is important to remember
|
|
that a program will probably only have a very small number of
|
|
different types of values in it and that only one type information
|
|
structure is required for many different values of the same type.
|
|
|
|
## Buffer Management Memory
|
|
|
|
#GVariant uses an internal buffer management structure to deal
|
|
with the various different possible sources of serialised data
|
|
that it uses. The buffer is responsible for ensuring that the
|
|
correct call is made when the data is no longer in use by
|
|
#GVariant. This may involve a g_free() or a g_slice_free() or
|
|
even g_mapped_file_unref().
|
|
|
|
One buffer management structure is used for each chunk of
|
|
serialised data. The size of the buffer management structure
|
|
is 4 * (void *). On 32-bit systems, that's 16 bytes.
|
|
|
|
## GVariant structure
|
|
|
|
The size of a #GVariant structure is 6 * (void *). On 32-bit
|
|
systems, that's 24 bytes.
|
|
|
|
#GVariant structures only exist if they are explicitly created
|
|
with API calls. For example, if a #GVariant is constructed out of
|
|
serialised data for the example given above (with the dictionary)
|
|
then although there are 9 individual values that comprise the
|
|
entire dictionary (two keys, two values, two variants containing
|
|
the values, two dictionary entries, plus the dictionary itself),
|
|
only 1 #GVariant instance exists -- the one referring to the
|
|
dictionary.
|
|
|
|
If calls are made to start accessing the other values then
|
|
#GVariant instances will exist for those values only for as long
|
|
as they are in use (ie: until you call g_variant_unref()). The
|
|
type information is shared. The serialised data and the buffer
|
|
management structure for that serialised data is shared by the
|
|
child.
|
|
|
|
## Summary
|
|
|
|
To put the entire example together, for our dictionary mapping
|
|
strings to variants (with two entries, as given above), we are
|
|
using 91 bytes of memory for type information, 29 bytes of memory
|
|
for the serialised data, 16 bytes for buffer management and 24
|
|
bytes for the #GVariant instance, or a total of 160 bytes, plus
|
|
malloc overhead. If we were to use g_variant_get_child_value() to
|
|
access the two dictionary entries, we would use an additional 48
|
|
bytes. If we were to have other dictionaries of the same type, we
|
|
would use more memory for the serialised data and buffer
|
|
management for those dictionaries, but the type information would
|
|
be shared.</doc>
|
|
<constructor name="new" c:identifier="g_variant_new" version="2.24" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new #GVariant instance.
|
|
|
|
Think of this function as an analogue to g_strdup_printf().
|
|
|
|
The type of the created instance and the arguments that are expected
|
|
by this function are determined by @format_string. See the section on
|
|
[GVariant format strings][gvariant-format-strings]. Please note that
|
|
the syntax of the format string is very likely to be extended in the
|
|
future.
|
|
|
|
The first character of the format string must not be '*' '?' '@' or
|
|
'r'; in essence, a new #GVariant must always be constructed by this
|
|
function (and not merely passed through it unmodified).
|
|
|
|
Note that the arguments must be of the correct width for their types
|
|
specified in @format_string. This can be achieved by casting them. See
|
|
the [GVariant varargs documentation][gvariant-varargs].
|
|
|
|
|[<!-- language="C" -->
|
|
MyFlags some_flags = FLAG_ONE | FLAG_TWO;
|
|
const gchar *some_strings[] = { "a", "b", "c", NULL };
|
|
GVariant *new_variant;
|
|
|
|
new_variant = g_variant_new ("(t^as)",
|
|
// This cast is required.
|
|
(guint64) some_flags,
|
|
some_strings);
|
|
]|</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new floating #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="format_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant format string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">arguments, as per @format_string</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_array" c:identifier="g_variant_new_array" version="2.24">
|
|
<doc xml:space="preserve">Creates a new #GVariant array from @children.
|
|
|
|
@child_type must be non-%NULL if @n_children is zero. Otherwise, the
|
|
child type is determined by inspecting the first element of the
|
|
@children array. If @child_type is non-%NULL then it must be a
|
|
definite type.
|
|
|
|
The items of the array are taken from the @children array. No entry
|
|
in the @children array may be %NULL.
|
|
|
|
All items in the array must have the same type, which must be the
|
|
same as @child_type, if given.
|
|
|
|
If the @children are floating references (see g_variant_ref_sink()), the
|
|
new instance takes ownership of them as if via g_variant_ref_sink().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new #GVariant array</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="child_type" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the element type of the new array</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
<parameter name="children" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">an array of
|
|
#GVariant pointers, the children</doc>
|
|
<array length="2" zero-terminated="0" c:type="GVariant* const*">
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="n_children" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @children</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_boolean" c:identifier="g_variant_new_boolean" version="2.24">
|
|
<doc xml:space="preserve">Creates a new boolean #GVariant instance -- either %TRUE or %FALSE.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new boolean #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #gboolean value</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_byte" c:identifier="g_variant_new_byte" version="2.24">
|
|
<doc xml:space="preserve">Creates a new byte #GVariant instance.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new byte #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #guint8 value</doc>
|
|
<type name="guint8" c:type="guint8"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_bytestring" c:identifier="g_variant_new_bytestring" version="2.26">
|
|
<doc xml:space="preserve">Creates an array-of-bytes #GVariant with the contents of @string.
|
|
This function is just like g_variant_new_string() except that the
|
|
string need not be valid UTF-8.
|
|
|
|
The nul terminator character at the end of the string is stored in
|
|
the array.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new bytestring #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a normal
|
|
nul-terminated string in no particular encoding</doc>
|
|
<array c:type="const gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_bytestring_array" c:identifier="g_variant_new_bytestring_array" version="2.26">
|
|
<doc xml:space="preserve">Constructs an array of bytestring #GVariant from the given array of
|
|
strings.
|
|
|
|
If @length is -1 then @strv is %NULL-terminated.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a new floating #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="strv" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array of strings</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar* const*">
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @strv, or -1</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_dict_entry" c:identifier="g_variant_new_dict_entry" version="2.24">
|
|
<doc xml:space="preserve">Creates a new dictionary entry #GVariant. @key and @value must be
|
|
non-%NULL. @key must be a value of a basic type (ie: not a container).
|
|
|
|
If the @key or @value are floating references (see g_variant_ref_sink()),
|
|
the new instance takes ownership of them as if via g_variant_ref_sink().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new dictionary entry #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a basic #GVariant, the key</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant, the value</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_double" c:identifier="g_variant_new_double" version="2.24">
|
|
<doc xml:space="preserve">Creates a new double #GVariant instance.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new double #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #gdouble floating point value</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_fixed_array" c:identifier="g_variant_new_fixed_array" version="2.32">
|
|
<doc xml:space="preserve">Constructs a new array #GVariant instance, where the elements are
|
|
of @element_type type.
|
|
|
|
@elements must be an array with fixed-sized elements. Numeric types are
|
|
fixed-size as are tuples containing only other fixed-sized types.
|
|
|
|
@element_size must be the size of a single element in the array.
|
|
For example, if calling this function for an array of 32-bit integers,
|
|
you might say sizeof(gint32). This value isn't used except for the purpose
|
|
of a double-check that the form of the serialised data matches the caller's
|
|
expectation.
|
|
|
|
@n_elements must be the length of the @elements array.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new array #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="element_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GVariantType of each element</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
<parameter name="elements" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a pointer to the fixed array of contiguous elements</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="n_elements" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of elements</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="element_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of each element</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_from_bytes" c:identifier="g_variant_new_from_bytes" version="2.36">
|
|
<doc xml:space="preserve">Constructs a new serialised-mode #GVariant instance. This is the
|
|
inner interface for creation of new serialised values that gets
|
|
called from various functions in gvariant.c.
|
|
|
|
A reference is taken on @bytes.
|
|
|
|
The data in @bytes must be aligned appropriately for the @type being loaded.
|
|
Otherwise this function will internally create a copy of the memory (since
|
|
GLib 2.60) or (in older versions) fail and exit the process.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a new #GVariant with a floating reference</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
<parameter name="bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GBytes</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</parameter>
|
|
<parameter name="trusted" transfer-ownership="none">
|
|
<doc xml:space="preserve">if the contents of @bytes are trusted</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_from_data" c:identifier="g_variant_new_from_data" version="2.24">
|
|
<doc xml:space="preserve">Creates a new #GVariant instance from serialised data.
|
|
|
|
@type is the type of #GVariant instance that will be constructed.
|
|
The interpretation of @data depends on knowing the type.
|
|
|
|
@data is not modified by this function and must remain valid with an
|
|
unchanging value until such a time as @notify is called with
|
|
@user_data. If the contents of @data change before that time then
|
|
the result is undefined.
|
|
|
|
If @data is trusted to be serialised data in normal form then
|
|
@trusted should be %TRUE. This applies to serialised data created
|
|
within this process or read from a trusted location on the disk (such
|
|
as a file installed in /usr/lib alongside your application). You
|
|
should set trusted to %FALSE if @data is read from the network, a
|
|
file in the user's home directory, etc.
|
|
|
|
If @data was not stored in this machine's native endianness, any multi-byte
|
|
numeric values in the returned variant will also be in non-native
|
|
endianness. g_variant_byteswap() can be used to recover the original values.
|
|
|
|
@notify will be called with @user_data when @data is no longer
|
|
needed. The exact time of this call is unspecified and might even be
|
|
before this function returns.
|
|
|
|
Note: @data must be backed by memory that is aligned appropriately for the
|
|
@type being loaded. Otherwise this function will internally create a copy of
|
|
the memory (since GLib 2.60) or (in older versions) fail and exit the
|
|
process.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a new floating #GVariant of type @type</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a definite #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none">
|
|
<doc xml:space="preserve">the serialised data</doc>
|
|
<array length="2" zero-terminated="0" c:type="gconstpointer">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of @data</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="trusted" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @data is definitely in normal form</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
<parameter name="notify" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">function to call when @data is no longer needed</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data for @notify</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_handle" c:identifier="g_variant_new_handle" version="2.24">
|
|
<doc xml:space="preserve">Creates a new handle #GVariant instance.
|
|
|
|
By convention, handles are indexes into an array of file descriptors
|
|
that are sent alongside a D-Bus message. If you're not interacting
|
|
with D-Bus, you probably don't need them.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new handle #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #gint32 value</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_int16" c:identifier="g_variant_new_int16" version="2.24">
|
|
<doc xml:space="preserve">Creates a new int16 #GVariant instance.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new int16 #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #gint16 value</doc>
|
|
<type name="gint16" c:type="gint16"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_int32" c:identifier="g_variant_new_int32" version="2.24">
|
|
<doc xml:space="preserve">Creates a new int32 #GVariant instance.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new int32 #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #gint32 value</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_int64" c:identifier="g_variant_new_int64" version="2.24">
|
|
<doc xml:space="preserve">Creates a new int64 #GVariant instance.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new int64 #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #gint64 value</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_maybe" c:identifier="g_variant_new_maybe" version="2.24">
|
|
<doc xml:space="preserve">Depending on if @child is %NULL, either wraps @child inside of a
|
|
maybe container or creates a Nothing instance for the given @type.
|
|
|
|
At least one of @child_type and @child must be non-%NULL.
|
|
If @child_type is non-%NULL then it must be a definite type.
|
|
If they are both non-%NULL then @child_type must be the type
|
|
of @child.
|
|
|
|
If @child is a floating reference (see g_variant_ref_sink()), the new
|
|
instance takes ownership of @child.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new #GVariant maybe instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="child_type" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the #GVariantType of the child, or %NULL</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
<parameter name="child" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the child value, or %NULL</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_object_path" c:identifier="g_variant_new_object_path" version="2.24">
|
|
<doc xml:space="preserve">Creates a D-Bus object path #GVariant with the contents of @string.
|
|
@string must be a valid D-Bus object path. Use
|
|
g_variant_is_object_path() if you're not sure.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new object path #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="object_path" transfer-ownership="none">
|
|
<doc xml:space="preserve">a normal C nul-terminated string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_objv" c:identifier="g_variant_new_objv" version="2.30">
|
|
<doc xml:space="preserve">Constructs an array of object paths #GVariant from the given array of
|
|
strings.
|
|
|
|
Each string must be a valid #GVariant object path; see
|
|
g_variant_is_object_path().
|
|
|
|
If @length is -1 then @strv is %NULL-terminated.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a new floating #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="strv" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array of strings</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar* const*">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @strv, or -1</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_parsed" c:identifier="g_variant_new_parsed" introspectable="0">
|
|
<doc xml:space="preserve">Parses @format and returns the result.
|
|
|
|
@format must be a text format #GVariant with one extension: at any
|
|
point that a value may appear in the text, a '%' character followed
|
|
by a GVariant format string (as per g_variant_new()) may appear. In
|
|
that case, the same arguments are collected from the argument list as
|
|
g_variant_new() would have collected.
|
|
|
|
Note that the arguments must be of the correct width for their types
|
|
specified in @format. This can be achieved by casting them. See
|
|
the [GVariant varargs documentation][gvariant-varargs].
|
|
|
|
Consider this simple example:
|
|
|[<!-- language="C" -->
|
|
g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three");
|
|
]|
|
|
|
|
In the example, the variable argument parameters are collected and
|
|
filled in as if they were part of the original string to produce the
|
|
result of
|
|
|[<!-- language="C" -->
|
|
[('one', 1), ('two', 2), ('three', 3)]
|
|
]|
|
|
|
|
This function is intended only to be used with @format as a string
|
|
literal. Any parse error is fatal to the calling process. If you
|
|
want to parse data from untrusted sources, use g_variant_parse().
|
|
|
|
You may not use this function to return, unmodified, a single
|
|
#GVariant pointer from the argument list. ie: @format may not solely
|
|
be anything along the lines of "%*", "%?", "\%r", or anything starting
|
|
with "%@".</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new floating #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">a text format #GVariant</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">arguments as per @format</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_parsed_va" c:identifier="g_variant_new_parsed_va" introspectable="0">
|
|
<doc xml:space="preserve">Parses @format and returns the result.
|
|
|
|
This is the version of g_variant_new_parsed() intended to be used
|
|
from libraries.
|
|
|
|
The return value will be floating if it was a newly created GVariant
|
|
instance. In the case that @format simply specified the collection
|
|
of a #GVariant pointer (eg: @format was "%*") then the collected
|
|
#GVariant pointer will be returned unmodified, without adding any
|
|
additional references.
|
|
|
|
Note that the arguments in @app must be of the correct width for their types
|
|
specified in @format when collected into the #va_list. See
|
|
the [GVariant varargs documentation][gvariant-varargs].
|
|
|
|
In order to behave correctly in all cases it is necessary for the
|
|
calling function to g_variant_ref_sink() the return result before
|
|
returning control to the user that originally provided the pointer.
|
|
At this point, the caller will have their own full reference to the
|
|
result. This can also be done by adding the result to a container,
|
|
or by passing it to another g_variant_new() call.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new, usually floating, #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">a text format #GVariant</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="app" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #va_list</doc>
|
|
<type name="va_list" c:type="va_list*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_printf" c:identifier="g_variant_new_printf" version="2.38" introspectable="0">
|
|
<doc xml:space="preserve">Creates a string-type GVariant using printf formatting.
|
|
|
|
This is similar to calling g_strdup_printf() and then
|
|
g_variant_new_string() but it saves a temporary variable and an
|
|
unnecessary copy.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new string
|
|
#GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="format_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a printf-style format string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">arguments for @format_string</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_signature" c:identifier="g_variant_new_signature" version="2.24">
|
|
<doc xml:space="preserve">Creates a D-Bus type signature #GVariant with the contents of
|
|
@string. @string must be a valid D-Bus type signature. Use
|
|
g_variant_is_signature() if you're not sure.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new signature #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="signature" transfer-ownership="none">
|
|
<doc xml:space="preserve">a normal C nul-terminated string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_string" c:identifier="g_variant_new_string" version="2.24">
|
|
<doc xml:space="preserve">Creates a string #GVariant with the contents of @string.
|
|
|
|
@string must be valid UTF-8, and must not be %NULL. To encode
|
|
potentially-%NULL strings, use g_variant_new() with `ms` as the
|
|
[format string][gvariant-format-strings-maybe-types].</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new string #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a normal UTF-8 nul-terminated string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_strv" c:identifier="g_variant_new_strv" version="2.24">
|
|
<doc xml:space="preserve">Constructs an array of strings #GVariant from the given array of
|
|
strings.
|
|
|
|
If @length is -1 then @strv is %NULL-terminated.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a new floating #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="strv" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array of strings</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar* const*">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @strv, or -1</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_take_string" c:identifier="g_variant_new_take_string" version="2.38" introspectable="0">
|
|
<doc xml:space="preserve">Creates a string #GVariant with the contents of @string.
|
|
|
|
@string must be valid UTF-8, and must not be %NULL. To encode
|
|
potentially-%NULL strings, use this with g_variant_new_maybe().
|
|
|
|
This function consumes @string. g_free() will be called on @string
|
|
when it is no longer required.
|
|
|
|
You must not modify or access @string in any other way after passing
|
|
it to this function. It is even possible that @string is immediately
|
|
freed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new string
|
|
#GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a normal UTF-8 nul-terminated string</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_tuple" c:identifier="g_variant_new_tuple" version="2.24">
|
|
<doc xml:space="preserve">Creates a new tuple #GVariant out of the items in @children. The
|
|
type is determined from the types of @children. No entry in the
|
|
@children array may be %NULL.
|
|
|
|
If @n_children is 0 then the unit tuple is constructed.
|
|
|
|
If the @children are floating references (see g_variant_ref_sink()), the
|
|
new instance takes ownership of them as if via g_variant_ref_sink().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new #GVariant tuple</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="children" transfer-ownership="none">
|
|
<doc xml:space="preserve">the items to make the tuple out of</doc>
|
|
<array length="1" zero-terminated="0" c:type="GVariant* const*">
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="n_children" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @children</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_uint16" c:identifier="g_variant_new_uint16" version="2.24">
|
|
<doc xml:space="preserve">Creates a new uint16 #GVariant instance.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new uint16 #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #guint16 value</doc>
|
|
<type name="guint16" c:type="guint16"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_uint32" c:identifier="g_variant_new_uint32" version="2.24">
|
|
<doc xml:space="preserve">Creates a new uint32 #GVariant instance.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new uint32 #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #guint32 value</doc>
|
|
<type name="guint32" c:type="guint32"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_uint64" c:identifier="g_variant_new_uint64" version="2.24">
|
|
<doc xml:space="preserve">Creates a new uint64 #GVariant instance.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new uint64 #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #guint64 value</doc>
|
|
<type name="guint64" c:type="guint64"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_va" c:identifier="g_variant_new_va" version="2.24" introspectable="0">
|
|
<doc xml:space="preserve">This function is intended to be used by libraries based on
|
|
#GVariant that want to provide g_variant_new()-like functionality
|
|
to their users.
|
|
|
|
The API is more general than g_variant_new() to allow a wider range
|
|
of possible uses.
|
|
|
|
@format_string must still point to a valid format string, but it only
|
|
needs to be nul-terminated if @endptr is %NULL. If @endptr is
|
|
non-%NULL then it is updated to point to the first character past the
|
|
end of the format string.
|
|
|
|
@app is a pointer to a #va_list. The arguments, according to
|
|
@format_string, are collected from this #va_list and the list is left
|
|
pointing to the argument following the last.
|
|
|
|
Note that the arguments in @app must be of the correct width for their
|
|
types specified in @format_string when collected into the #va_list.
|
|
See the [GVariant varargs documentation][gvariant-varargs].
|
|
|
|
These two generalisations allow mixing of multiple calls to
|
|
g_variant_new_va() and g_variant_get_va() within a single actual
|
|
varargs call by the user.
|
|
|
|
The return value will be floating if it was a newly created GVariant
|
|
instance (for example, if the format string was "(ii)"). In the case
|
|
that the format_string was '*', '?', 'r', or a format starting with
|
|
'@' then the collected #GVariant pointer will be returned unmodified,
|
|
without adding any additional references.
|
|
|
|
In order to behave correctly in all cases it is necessary for the
|
|
calling function to g_variant_ref_sink() the return result before
|
|
returning control to the user that originally provided the pointer.
|
|
At this point, the caller will have their own full reference to the
|
|
result. This can also be done by adding the result to a container,
|
|
or by passing it to another g_variant_new() call.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new, usually floating, #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="format_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string that is prefixed with a format string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="endptr" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store the end pointer,
|
|
or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar**"/>
|
|
</parameter>
|
|
<parameter name="app" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #va_list</doc>
|
|
<type name="va_list" c:type="va_list*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_variant" c:identifier="g_variant_new_variant" version="2.24">
|
|
<doc xml:space="preserve">Boxes @value. The result is a #GVariant instance representing a
|
|
variant containing the original value.
|
|
|
|
If @child is a floating reference (see g_variant_ref_sink()), the new
|
|
instance takes ownership of @child.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a floating reference to a new variant #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<method name="byteswap" c:identifier="g_variant_byteswap" version="2.24">
|
|
<doc xml:space="preserve">Performs a byteswapping operation on the contents of @value. The
|
|
result is that all multi-byte numeric data contained in @value is
|
|
byteswapped. That includes 16, 32, and 64bit signed and unsigned
|
|
integers as well as file handles and double precision floating point
|
|
values.
|
|
|
|
This function is an identity mapping on any value that does not
|
|
contain multi-byte numeric data. That include strings, booleans,
|
|
bytes and containers containing only these things (recursively).
|
|
|
|
The returned value is always in normal form and is marked as trusted.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the byteswapped form of @value</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="check_format_string" c:identifier="g_variant_check_format_string" version="2.34">
|
|
<doc xml:space="preserve">Checks if calling g_variant_get() with @format_string on @value would
|
|
be valid from a type-compatibility standpoint. @format_string is
|
|
assumed to be a valid format string (from a syntactic standpoint).
|
|
|
|
If @copy_only is %TRUE then this function additionally checks that it
|
|
would be safe to call g_variant_unref() on @value immediately after
|
|
the call to g_variant_get() without invalidating the result. This is
|
|
only possible if deep copies are made (ie: there are no pointers to
|
|
the data inside of the soon-to-be-freed #GVariant instance). If this
|
|
check fails then a g_critical() is printed and %FALSE is returned.
|
|
|
|
This function is meant to be used by functions that wish to provide
|
|
varargs accessors to #GVariant values of uncertain values (eg:
|
|
g_variant_lookup() or g_menu_model_get_item_attribute()).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @format_string is safe to use</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="format_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid #GVariant format string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="copy_only" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE to ensure the format string makes deep copies</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="classify" c:identifier="g_variant_classify" version="2.24">
|
|
<doc xml:space="preserve">Classifies @value according to its top-level type.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GVariantClass of @value</doc>
|
|
<type name="VariantClass" c:type="GVariantClass"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="compare" c:identifier="g_variant_compare" version="2.26">
|
|
<doc xml:space="preserve">Compares @one and @two.
|
|
|
|
The types of @one and @two are #gconstpointer only to allow use of
|
|
this function with #GTree, #GPtrArray, etc. They must each be a
|
|
#GVariant.
|
|
|
|
Comparison is only defined for basic types (ie: booleans, numbers,
|
|
strings). For booleans, %FALSE is less than %TRUE. Numbers are
|
|
ordered in the usual way. Strings are in ASCII lexographical order.
|
|
|
|
It is a programmer error to attempt to compare container values or
|
|
two values that have types that are not exactly equal. For example,
|
|
you cannot compare a 32-bit signed integer with a 32-bit unsigned
|
|
integer. Also note that this function is not particularly
|
|
well-behaved when it comes to comparison of doubles; in particular,
|
|
the handling of incomparable values (ie: NaN) is undefined.
|
|
|
|
If you only require an equality comparison, g_variant_equal() is more
|
|
general.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">negative value if a < b;
|
|
zero if a = b;
|
|
positive value if a > b.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="one" transfer-ownership="none">
|
|
<doc xml:space="preserve">a basic-typed #GVariant instance</doc>
|
|
<type name="Variant" c:type="gconstpointer"/>
|
|
</instance-parameter>
|
|
<parameter name="two" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant instance of the same type</doc>
|
|
<type name="Variant" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="dup_bytestring" c:identifier="g_variant_dup_bytestring" version="2.26">
|
|
<doc xml:space="preserve">Similar to g_variant_get_bytestring() except that instead of
|
|
returning a constant string, the string is duplicated.
|
|
|
|
The return value must be freed using g_free().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">
|
|
a newly allocated string</doc>
|
|
<array length="0" zero-terminated="1" c:type="gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array-of-bytes #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">a pointer to a #gsize, to store
|
|
the length (not including the nul terminator)</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="dup_bytestring_array" c:identifier="g_variant_dup_bytestring_array" version="2.26">
|
|
<doc xml:space="preserve">Gets the contents of an array of array of bytes #GVariant. This call
|
|
makes a deep copy; the return result should be released with
|
|
g_strfreev().
|
|
|
|
If @length is non-%NULL then the number of elements in the result is
|
|
stored there. In any case, the resulting array will be
|
|
%NULL-terminated.
|
|
|
|
For an empty array, @length will be set to 0 and a pointer to a
|
|
%NULL pointer will be returned.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an array of strings</doc>
|
|
<array length="0" zero-terminated="0" c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array of array of bytes #GVariant ('aay')</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">the length of the result, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="dup_objv" c:identifier="g_variant_dup_objv" version="2.30">
|
|
<doc xml:space="preserve">Gets the contents of an array of object paths #GVariant. This call
|
|
makes a deep copy; the return result should be released with
|
|
g_strfreev().
|
|
|
|
If @length is non-%NULL then the number of elements in the result
|
|
is stored there. In any case, the resulting array will be
|
|
%NULL-terminated.
|
|
|
|
For an empty array, @length will be set to 0 and a pointer to a
|
|
%NULL pointer will be returned.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an array of strings</doc>
|
|
<array length="0" zero-terminated="1" c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array of object paths #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">the length of the result, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="dup_string" c:identifier="g_variant_dup_string" version="2.24">
|
|
<doc xml:space="preserve">Similar to g_variant_get_string() except that instead of returning
|
|
a constant string, the string is duplicated.
|
|
|
|
The string will always be UTF-8 encoded.
|
|
|
|
The return value must be freed using g_free().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string, UTF-8 encoded</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to a #gsize, to store the length</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="dup_strv" c:identifier="g_variant_dup_strv" version="2.24">
|
|
<doc xml:space="preserve">Gets the contents of an array of strings #GVariant. This call
|
|
makes a deep copy; the return result should be released with
|
|
g_strfreev().
|
|
|
|
If @length is non-%NULL then the number of elements in the result
|
|
is stored there. In any case, the resulting array will be
|
|
%NULL-terminated.
|
|
|
|
For an empty array, @length will be set to 0 and a pointer to a
|
|
%NULL pointer will be returned.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an array of strings</doc>
|
|
<array length="0" zero-terminated="1" c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array of strings #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">the length of the result, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="equal" c:identifier="g_variant_equal" version="2.24">
|
|
<doc xml:space="preserve">Checks if @one and @two have the same type and value.
|
|
|
|
The types of @one and @two are #gconstpointer only to allow use of
|
|
this function with #GHashTable. They must each be a #GVariant.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @one and @two are equal</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="one" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant instance</doc>
|
|
<type name="Variant" c:type="gconstpointer"/>
|
|
</instance-parameter>
|
|
<parameter name="two" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant instance</doc>
|
|
<type name="Variant" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get" c:identifier="g_variant_get" version="2.24" introspectable="0">
|
|
<doc xml:space="preserve">Deconstructs a #GVariant instance.
|
|
|
|
Think of this function as an analogue to scanf().
|
|
|
|
The arguments that are expected by this function are entirely
|
|
determined by @format_string. @format_string also restricts the
|
|
permissible types of @value. It is an error to give a value with
|
|
an incompatible type. See the section on
|
|
[GVariant format strings][gvariant-format-strings].
|
|
Please note that the syntax of the format string is very likely to be
|
|
extended in the future.
|
|
|
|
@format_string determines the C types that are used for unpacking
|
|
the values and also determines if the values are copied or borrowed,
|
|
see the section on
|
|
[GVariant format strings][gvariant-format-strings-pointers].</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="format_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant format string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">arguments, as per @format_string</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_boolean" c:identifier="g_variant_get_boolean" version="2.24">
|
|
<doc xml:space="preserve">Returns the boolean value of @value.
|
|
|
|
It is an error to call this function with a @value of any type
|
|
other than %G_VARIANT_TYPE_BOOLEAN.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE or %FALSE</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a boolean #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_byte" c:identifier="g_variant_get_byte" version="2.24">
|
|
<doc xml:space="preserve">Returns the byte value of @value.
|
|
|
|
It is an error to call this function with a @value of any type
|
|
other than %G_VARIANT_TYPE_BYTE.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #guint8</doc>
|
|
<type name="guint8" c:type="guint8"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a byte #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_bytestring" c:identifier="g_variant_get_bytestring" version="2.26">
|
|
<doc xml:space="preserve">Returns the string value of a #GVariant instance with an
|
|
array-of-bytes type. The string has no particular encoding.
|
|
|
|
If the array does not end with a nul terminator character, the empty
|
|
string is returned. For this reason, you can always trust that a
|
|
non-%NULL nul-terminated string will be returned by this function.
|
|
|
|
If the array contains a nul terminator character somewhere other than
|
|
the last byte then the returned string is the string, up to the first
|
|
such nul character.
|
|
|
|
g_variant_get_fixed_array() should be used instead if the array contains
|
|
arbitrary data that could not be nul-terminated or could contain nul bytes.
|
|
|
|
It is an error to call this function with a @value that is not an
|
|
array of bytes.
|
|
|
|
The return value remains valid as long as @value exists.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">
|
|
the constant string</doc>
|
|
<array c:type="const gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array-of-bytes #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_bytestring_array" c:identifier="g_variant_get_bytestring_array" version="2.26">
|
|
<doc xml:space="preserve">Gets the contents of an array of array of bytes #GVariant. This call
|
|
makes a shallow copy; the return result should be released with
|
|
g_free(), but the individual strings must not be modified.
|
|
|
|
If @length is non-%NULL then the number of elements in the result is
|
|
stored there. In any case, the resulting array will be
|
|
%NULL-terminated.
|
|
|
|
For an empty array, @length will be set to 0 and a pointer to a
|
|
%NULL pointer will be returned.</doc>
|
|
<return-value transfer-ownership="container">
|
|
<doc xml:space="preserve">an array of constant strings</doc>
|
|
<array length="0" zero-terminated="0" c:type="const gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array of array of bytes #GVariant ('aay')</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">the length of the result, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_child" c:identifier="g_variant_get_child" version="2.24" introspectable="0">
|
|
<doc xml:space="preserve">Reads a child item out of a container #GVariant instance and
|
|
deconstructs it according to @format_string. This call is
|
|
essentially a combination of g_variant_get_child_value() and
|
|
g_variant_get().
|
|
|
|
@format_string determines the C types that are used for unpacking
|
|
the values and also determines if the values are copied or borrowed,
|
|
see the section on
|
|
[GVariant format strings][gvariant-format-strings-pointers].</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a container #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="index_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the child to deconstruct</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="format_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant format string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">arguments, as per @format_string</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_child_value" c:identifier="g_variant_get_child_value" version="2.24">
|
|
<doc xml:space="preserve">Reads a child item out of a container #GVariant instance. This
|
|
includes variants, maybes, arrays, tuples and dictionary
|
|
entries. It is an error to call this function on any other type of
|
|
#GVariant.
|
|
|
|
It is an error if @index_ is greater than the number of child items
|
|
in the container. See g_variant_n_children().
|
|
|
|
The returned value is never floating. You should free it with
|
|
g_variant_unref() when you're done with it.
|
|
|
|
Note that values borrowed from the returned child are not guaranteed to
|
|
still be valid after the child is freed even if you still hold a reference
|
|
to @value, if @value has not been serialised at the time this function is
|
|
called. To avoid this, you can serialize @value by calling
|
|
g_variant_get_data() and optionally ignoring the return value.
|
|
|
|
There may be implementation specific restrictions on deeply nested values,
|
|
which would result in the unit tuple being returned as the child value,
|
|
instead of further nested children. #GVariant is guaranteed to handle
|
|
nesting up to at least 64 levels.
|
|
|
|
This function is O(1).</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the child at the specified index</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a container #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="index_" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the child to fetch</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_data" c:identifier="g_variant_get_data" version="2.24">
|
|
<doc xml:space="preserve">Returns a pointer to the serialised form of a #GVariant instance.
|
|
The returned data may not be in fully-normalised form if read from an
|
|
untrusted source. The returned data must not be freed; it remains
|
|
valid for as long as @value exists.
|
|
|
|
If @value is a fixed-sized value that was deserialised from a
|
|
corrupted serialised container then %NULL may be returned. In this
|
|
case, the proper thing to do is typically to use the appropriate
|
|
number of nul bytes in place of @value. If @value is not fixed-sized
|
|
then %NULL is never returned.
|
|
|
|
In the case that @value is already in serialised form, this function
|
|
is O(1). If the value is not already in serialised form,
|
|
serialisation occurs implicitly and is approximately O(n) in the size
|
|
of the result.
|
|
|
|
To deserialise the data returned by this function, in addition to the
|
|
serialised data, you must know the type of the #GVariant, and (if the
|
|
machine might be different) the endianness of the machine that stored
|
|
it. As a result, file formats or network messages that incorporate
|
|
serialised #GVariants must include this information either
|
|
implicitly (for instance "the file always contains a
|
|
%G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or
|
|
explicitly (by storing the type and/or endianness in addition to the
|
|
serialised data).</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the serialised form of @value, or %NULL</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_data_as_bytes" c:identifier="g_variant_get_data_as_bytes" version="2.36">
|
|
<doc xml:space="preserve">Returns a pointer to the serialised form of a #GVariant instance.
|
|
The semantics of this function are exactly the same as
|
|
g_variant_get_data(), except that the returned #GBytes holds
|
|
a reference to the variant data.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">A new #GBytes representing the variant data</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_double" c:identifier="g_variant_get_double" version="2.24">
|
|
<doc xml:space="preserve">Returns the double precision floating point value of @value.
|
|
|
|
It is an error to call this function with a @value of any type
|
|
other than %G_VARIANT_TYPE_DOUBLE.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #gdouble</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a double #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_fixed_array" c:identifier="g_variant_get_fixed_array" version="2.24" introspectable="0">
|
|
<doc xml:space="preserve">Provides access to the serialised data for an array of fixed-sized
|
|
items.
|
|
|
|
@value must be an array with fixed-sized elements. Numeric types are
|
|
fixed-size, as are tuples containing only other fixed-sized types.
|
|
|
|
@element_size must be the size of a single element in the array,
|
|
as given by the section on
|
|
[serialized data memory][gvariant-serialised-data-memory].
|
|
|
|
In particular, arrays of these fixed-sized types can be interpreted
|
|
as an array of the given C type, with @element_size set to the size
|
|
the appropriate type:
|
|
- %G_VARIANT_TYPE_INT16 (etc.): #gint16 (etc.)
|
|
- %G_VARIANT_TYPE_BOOLEAN: #guchar (not #gboolean!)
|
|
- %G_VARIANT_TYPE_BYTE: #guint8
|
|
- %G_VARIANT_TYPE_HANDLE: #guint32
|
|
- %G_VARIANT_TYPE_DOUBLE: #gdouble
|
|
|
|
For example, if calling this function for an array of 32-bit integers,
|
|
you might say `sizeof(gint32)`. This value isn't used except for the purpose
|
|
of a double-check that the form of the serialised data matches the caller's
|
|
expectation.
|
|
|
|
@n_elements, which must be non-%NULL, is set equal to the number of
|
|
items in the array.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to
|
|
the fixed array</doc>
|
|
<array length="0" zero-terminated="0" c:type="gconstpointer">
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant array with fixed-sized elements</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="n_elements" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to the location to store the number of items</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
<parameter name="element_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of each element</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_handle" c:identifier="g_variant_get_handle" version="2.24">
|
|
<doc xml:space="preserve">Returns the 32-bit signed integer value of @value.
|
|
|
|
It is an error to call this function with a @value of any type other
|
|
than %G_VARIANT_TYPE_HANDLE.
|
|
|
|
By convention, handles are indexes into an array of file descriptors
|
|
that are sent alongside a D-Bus message. If you're not interacting
|
|
with D-Bus, you probably don't need them.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #gint32</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a handle #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_int16" c:identifier="g_variant_get_int16" version="2.24">
|
|
<doc xml:space="preserve">Returns the 16-bit signed integer value of @value.
|
|
|
|
It is an error to call this function with a @value of any type
|
|
other than %G_VARIANT_TYPE_INT16.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #gint16</doc>
|
|
<type name="gint16" c:type="gint16"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">an int16 #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_int32" c:identifier="g_variant_get_int32" version="2.24">
|
|
<doc xml:space="preserve">Returns the 32-bit signed integer value of @value.
|
|
|
|
It is an error to call this function with a @value of any type
|
|
other than %G_VARIANT_TYPE_INT32.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #gint32</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">an int32 #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_int64" c:identifier="g_variant_get_int64" version="2.24">
|
|
<doc xml:space="preserve">Returns the 64-bit signed integer value of @value.
|
|
|
|
It is an error to call this function with a @value of any type
|
|
other than %G_VARIANT_TYPE_INT64.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #gint64</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">an int64 #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_maybe" c:identifier="g_variant_get_maybe" version="2.24">
|
|
<doc xml:space="preserve">Given a maybe-typed #GVariant instance, extract its value. If the
|
|
value is Nothing, then this function returns %NULL.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">the contents of @value, or %NULL</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a maybe-typed value</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_normal_form" c:identifier="g_variant_get_normal_form" version="2.24">
|
|
<doc xml:space="preserve">Gets a #GVariant instance that has the same value as @value and is
|
|
trusted to be in normal form.
|
|
|
|
If @value is already trusted to be in normal form then a new
|
|
reference to @value is returned.
|
|
|
|
If @value is not already trusted, then it is scanned to check if it
|
|
is in normal form. If it is found to be in normal form then it is
|
|
marked as trusted and a new reference to it is returned.
|
|
|
|
If @value is found not to be in normal form then a new trusted
|
|
#GVariant is created with the same value as @value.
|
|
|
|
It makes sense to call this function if you've received #GVariant
|
|
data from untrusted sources and you want to ensure your serialised
|
|
output is definitely in normal form.
|
|
|
|
If @value is already in normal form, a new reference will be returned
|
|
(which will be floating if @value is floating). If it is not in normal form,
|
|
the newly created #GVariant will be returned with a single non-floating
|
|
reference. Typically, g_variant_take_ref() should be called on the return
|
|
value from this function to guarantee ownership of a single non-floating
|
|
reference to it.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a trusted #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_objv" c:identifier="g_variant_get_objv" version="2.30">
|
|
<doc xml:space="preserve">Gets the contents of an array of object paths #GVariant. This call
|
|
makes a shallow copy; the return result should be released with
|
|
g_free(), but the individual strings must not be modified.
|
|
|
|
If @length is non-%NULL then the number of elements in the result
|
|
is stored there. In any case, the resulting array will be
|
|
%NULL-terminated.
|
|
|
|
For an empty array, @length will be set to 0 and a pointer to a
|
|
%NULL pointer will be returned.</doc>
|
|
<return-value transfer-ownership="container">
|
|
<doc xml:space="preserve">an array of constant strings</doc>
|
|
<array length="0" zero-terminated="1" c:type="const gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array of object paths #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">the length of the result, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_size" c:identifier="g_variant_get_size" version="2.24">
|
|
<doc xml:space="preserve">Determines the number of bytes that would be required to store @value
|
|
with g_variant_store().
|
|
|
|
If @value has a fixed-sized type then this function always returned
|
|
that fixed size.
|
|
|
|
In the case that @value is already in serialised form or the size has
|
|
already been calculated (ie: this function has been called before)
|
|
then this function is O(1). Otherwise, the size is calculated, an
|
|
operation which is approximately O(n) in the number of values
|
|
involved.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the serialised size of @value</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_string" c:identifier="g_variant_get_string" version="2.24">
|
|
<doc xml:space="preserve">Returns the string value of a #GVariant instance with a string
|
|
type. This includes the types %G_VARIANT_TYPE_STRING,
|
|
%G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE.
|
|
|
|
The string will always be UTF-8 encoded, will never be %NULL, and will never
|
|
contain nul bytes.
|
|
|
|
If @length is non-%NULL then the length of the string (in bytes) is
|
|
returned there. For trusted values, this information is already
|
|
known. Untrusted values will be validated and, if valid, a strlen() will be
|
|
performed. If invalid, a default value will be returned — for
|
|
%G_VARIANT_TYPE_OBJECT_PATH, this is `"/"`, and for other types it is the
|
|
empty string.
|
|
|
|
It is an error to call this function with a @value of any type
|
|
other than those three.
|
|
|
|
The return value remains valid as long as @value exists.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the constant string, UTF-8 encoded</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">a pointer to a #gsize,
|
|
to store the length</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_strv" c:identifier="g_variant_get_strv" version="2.24">
|
|
<doc xml:space="preserve">Gets the contents of an array of strings #GVariant. This call
|
|
makes a shallow copy; the return result should be released with
|
|
g_free(), but the individual strings must not be modified.
|
|
|
|
If @length is non-%NULL then the number of elements in the result
|
|
is stored there. In any case, the resulting array will be
|
|
%NULL-terminated.
|
|
|
|
For an empty array, @length will be set to 0 and a pointer to a
|
|
%NULL pointer will be returned.</doc>
|
|
<return-value transfer-ownership="container">
|
|
<doc xml:space="preserve">an array of constant strings</doc>
|
|
<array length="0" zero-terminated="1" c:type="const gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array of strings #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">the length of the result, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_type" c:identifier="g_variant_get_type" version="2.24">
|
|
<doc xml:space="preserve">Determines the type of @value.
|
|
|
|
The return value is valid for the lifetime of @value and must not
|
|
be freed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_type_string" c:identifier="g_variant_get_type_string" version="2.24">
|
|
<doc xml:space="preserve">Returns the type string of @value. Unlike the result of calling
|
|
g_variant_type_peek_string(), this string is nul-terminated. This
|
|
string belongs to #GVariant and must not be freed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the type string for the type of @value</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_uint16" c:identifier="g_variant_get_uint16" version="2.24">
|
|
<doc xml:space="preserve">Returns the 16-bit unsigned integer value of @value.
|
|
|
|
It is an error to call this function with a @value of any type
|
|
other than %G_VARIANT_TYPE_UINT16.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #guint16</doc>
|
|
<type name="guint16" c:type="guint16"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a uint16 #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_uint32" c:identifier="g_variant_get_uint32" version="2.24">
|
|
<doc xml:space="preserve">Returns the 32-bit unsigned integer value of @value.
|
|
|
|
It is an error to call this function with a @value of any type
|
|
other than %G_VARIANT_TYPE_UINT32.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #guint32</doc>
|
|
<type name="guint32" c:type="guint32"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a uint32 #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_uint64" c:identifier="g_variant_get_uint64" version="2.24">
|
|
<doc xml:space="preserve">Returns the 64-bit unsigned integer value of @value.
|
|
|
|
It is an error to call this function with a @value of any type
|
|
other than %G_VARIANT_TYPE_UINT64.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #guint64</doc>
|
|
<type name="guint64" c:type="guint64"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a uint64 #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_va" c:identifier="g_variant_get_va" version="2.24" introspectable="0">
|
|
<doc xml:space="preserve">This function is intended to be used by libraries based on #GVariant
|
|
that want to provide g_variant_get()-like functionality to their
|
|
users.
|
|
|
|
The API is more general than g_variant_get() to allow a wider range
|
|
of possible uses.
|
|
|
|
@format_string must still point to a valid format string, but it only
|
|
need to be nul-terminated if @endptr is %NULL. If @endptr is
|
|
non-%NULL then it is updated to point to the first character past the
|
|
end of the format string.
|
|
|
|
@app is a pointer to a #va_list. The arguments, according to
|
|
@format_string, are collected from this #va_list and the list is left
|
|
pointing to the argument following the last.
|
|
|
|
These two generalisations allow mixing of multiple calls to
|
|
g_variant_new_va() and g_variant_get_va() within a single actual
|
|
varargs call by the user.
|
|
|
|
@format_string determines the C types that are used for unpacking
|
|
the values and also determines if the values are copied or borrowed,
|
|
see the section on
|
|
[GVariant format strings][gvariant-format-strings-pointers].</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="format_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string that is prefixed with a format string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="endptr" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store the end pointer,
|
|
or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar**"/>
|
|
</parameter>
|
|
<parameter name="app" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #va_list</doc>
|
|
<type name="va_list" c:type="va_list*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_variant" c:identifier="g_variant_get_variant" version="2.24">
|
|
<doc xml:space="preserve">Unboxes @value. The result is the #GVariant instance that was
|
|
contained in @value.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the item contained in the variant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a variant #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="hash" c:identifier="g_variant_hash" version="2.24">
|
|
<doc xml:space="preserve">Generates a hash value for a #GVariant instance.
|
|
|
|
The output of this function is guaranteed to be the same for a given
|
|
value only per-process. It may change between different processor
|
|
architectures or even different versions of GLib. Do not use this
|
|
function as a basis for building protocols or file formats.
|
|
|
|
The type of @value is #gconstpointer only to allow use of this
|
|
function with #GHashTable. @value must be a #GVariant.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a hash value corresponding to @value</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a basic #GVariant value as a #gconstpointer</doc>
|
|
<type name="Variant" c:type="gconstpointer"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_container" c:identifier="g_variant_is_container" version="2.24">
|
|
<doc xml:space="preserve">Checks if @value is a container.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @value is a container</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_floating" c:identifier="g_variant_is_floating" version="2.26">
|
|
<doc xml:space="preserve">Checks whether @value has a floating reference count.
|
|
|
|
This function should only ever be used to assert that a given variant
|
|
is or is not floating, or for debug purposes. To acquire a reference
|
|
to a variant that might be floating, always use g_variant_ref_sink()
|
|
or g_variant_take_ref().
|
|
|
|
See g_variant_ref_sink() for more information about floating reference
|
|
counts.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">whether @value is floating</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_normal_form" c:identifier="g_variant_is_normal_form" version="2.24">
|
|
<doc xml:space="preserve">Checks if @value is in normal form.
|
|
|
|
The main reason to do this is to detect if a given chunk of
|
|
serialised data is in normal form: load the data into a #GVariant
|
|
using g_variant_new_from_data() and then use this function to
|
|
check.
|
|
|
|
If @value is found to be in normal form then it will be marked as
|
|
being trusted. If the value was already marked as being trusted then
|
|
this function will immediately return %TRUE.
|
|
|
|
There may be implementation specific restrictions on deeply nested values.
|
|
GVariant is guaranteed to handle nesting up to at least 64 levels.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @value is in normal form</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_of_type" c:identifier="g_variant_is_of_type" version="2.24">
|
|
<doc xml:space="preserve">Checks if a value has a type matching the provided type.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the type of @value matches @type</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant instance</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="iter_new" c:identifier="g_variant_iter_new" version="2.24" introspectable="0">
|
|
<doc xml:space="preserve">Creates a heap-allocated #GVariantIter for iterating over the items
|
|
in @value.
|
|
|
|
Use g_variant_iter_free() to free the return value when you no longer
|
|
need it.
|
|
|
|
A reference is taken to @value and will be released only when
|
|
g_variant_iter_free() is called.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new heap-allocated #GVariantIter</doc>
|
|
<type name="VariantIter" c:type="GVariantIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a container #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="lookup" c:identifier="g_variant_lookup" version="2.28" introspectable="0">
|
|
<doc xml:space="preserve">Looks up a value in a dictionary #GVariant.
|
|
|
|
This function is a wrapper around g_variant_lookup_value() and
|
|
g_variant_get(). In the case that %NULL would have been returned,
|
|
this function returns %FALSE. Otherwise, it unpacks the returned
|
|
value and returns %TRUE.
|
|
|
|
@format_string determines the C types that are used for unpacking
|
|
the values and also determines if the values are copied or borrowed,
|
|
see the section on
|
|
[GVariant format strings][gvariant-format-strings-pointers].
|
|
|
|
This function is currently implemented with a linear scan. If you
|
|
plan to do many lookups then #GVariantDict may be more efficient.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a value was unpacked</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="dictionary" transfer-ownership="none">
|
|
<doc xml:space="preserve">a dictionary #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">the key to look up in the dictionary</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="format_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a GVariant format string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">the arguments to unpack the value into</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="lookup_value" c:identifier="g_variant_lookup_value" version="2.28">
|
|
<doc xml:space="preserve">Looks up a value in a dictionary #GVariant.
|
|
|
|
This function works with dictionaries of the type a{s*} (and equally
|
|
well with type a{o*}, but we only further discuss the string case
|
|
for sake of clarity).
|
|
|
|
In the event that @dictionary has the type a{sv}, the @expected_type
|
|
string specifies what type of value is expected to be inside of the
|
|
variant. If the value inside the variant has a different type then
|
|
%NULL is returned. In the event that @dictionary has a value type other
|
|
than v then @expected_type must directly match the value type and it is
|
|
used to unpack the value directly or an error occurs.
|
|
|
|
In either case, if @key is not found in @dictionary, %NULL is returned.
|
|
|
|
If the key is found and the value has the correct type, it is
|
|
returned. If @expected_type was specified then any non-%NULL return
|
|
value will have this type.
|
|
|
|
This function is currently implemented with a linear scan. If you
|
|
plan to do many lookups then #GVariantDict may be more efficient.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the value of the dictionary key, or %NULL</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="dictionary" transfer-ownership="none">
|
|
<doc xml:space="preserve">a dictionary #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">the key to look up in the dictionary</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="expected_type" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GVariantType, or %NULL</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="n_children" c:identifier="g_variant_n_children" version="2.24">
|
|
<doc xml:space="preserve">Determines the number of children in a container #GVariant instance.
|
|
This includes variants, maybes, arrays, tuples and dictionary
|
|
entries. It is an error to call this function on any other type of
|
|
#GVariant.
|
|
|
|
For variants, the return value is always 1. For values with maybe
|
|
types, it is always zero or one. For arrays, it is the length of the
|
|
array. For tuples it is the number of tuple items (which depends
|
|
only on the type). For dictionary entries, it is always 2
|
|
|
|
This function is O(1).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of children in the container</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a container #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="print" c:identifier="g_variant_print" version="2.24">
|
|
<doc xml:space="preserve">Pretty-prints @value in the format understood by g_variant_parse().
|
|
|
|
The format is described [here][gvariant-text].
|
|
|
|
If @type_annotate is %TRUE, then type information is included in
|
|
the output.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated string holding the result.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="type_annotate" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if type information should be included in
|
|
the output</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="print_string" c:identifier="g_variant_print_string" version="2.24" introspectable="0">
|
|
<doc xml:space="preserve">Behaves as g_variant_print(), but operates on a #GString.
|
|
|
|
If @string is non-%NULL then it is appended to and returned. Else,
|
|
a new empty #GString is allocated and it is returned.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a #GString containing the string</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="string" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GString, or %NULL</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</parameter>
|
|
<parameter name="type_annotate" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if type information should be included in
|
|
the output</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_variant_ref" version="2.24">
|
|
<doc xml:space="preserve">Increases the reference count of @value.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the same @value</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref_sink" c:identifier="g_variant_ref_sink" version="2.24">
|
|
<doc xml:space="preserve">#GVariant uses a floating reference count system. All functions with
|
|
names starting with `g_variant_new_` return floating
|
|
references.
|
|
|
|
Calling g_variant_ref_sink() on a #GVariant with a floating reference
|
|
will convert the floating reference into a full reference. Calling
|
|
g_variant_ref_sink() on a non-floating #GVariant results in an
|
|
additional normal reference being added.
|
|
|
|
In other words, if the @value is floating, then this call "assumes
|
|
ownership" of the floating reference, converting it to a normal
|
|
reference. If the @value is not floating, then this call adds a
|
|
new normal reference increasing the reference count by one.
|
|
|
|
All calls that result in a #GVariant instance being inserted into a
|
|
container will call g_variant_ref_sink() on the instance. This means
|
|
that if the value was just created (and has only its floating
|
|
reference) then the container will assume sole ownership of the value
|
|
at that point and the caller will not need to unreference it. This
|
|
makes certain common styles of programming much easier while still
|
|
maintaining normal refcounting semantics in situations where values
|
|
are not floating.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the same @value</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="store" c:identifier="g_variant_store" version="2.24">
|
|
<doc xml:space="preserve">Stores the serialised form of @value at @data. @data should be
|
|
large enough. See g_variant_get_size().
|
|
|
|
The stored data is in machine native byte order but may not be in
|
|
fully-normalised form if read from an untrusted source. See
|
|
g_variant_get_normal_form() for a solution.
|
|
|
|
As with g_variant_get_data(), to be able to deserialise the
|
|
serialised variant successfully, its type and (if the destination
|
|
machine might be different) its endianness must also be available.
|
|
|
|
This function is approximately O(n) in the size of @data.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GVariant to store</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
<parameter name="data" transfer-ownership="none">
|
|
<doc xml:space="preserve">the location to store the serialised data at</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="take_ref" c:identifier="g_variant_take_ref">
|
|
<doc xml:space="preserve">If @value is floating, sink it. Otherwise, do nothing.
|
|
|
|
Typically you want to use g_variant_ref_sink() in order to
|
|
automatically do the correct thing with respect to floating or
|
|
non-floating references, but there is one specific scenario where
|
|
this function is helpful.
|
|
|
|
The situation where this function is helpful is when creating an API
|
|
that allows the user to provide a callback function that returns a
|
|
#GVariant. We certainly want to allow the user the flexibility to
|
|
return a non-floating reference from this callback (for the case
|
|
where the value that is being returned already exists).
|
|
|
|
At the same time, the style of the #GVariant API makes it likely that
|
|
for newly-created #GVariant instances, the user can be saved some
|
|
typing if they are allowed to return a #GVariant with a floating
|
|
reference.
|
|
|
|
Using this function on the return value of the user's callback allows
|
|
the user to do whichever is more convenient for them. The caller
|
|
will always receives exactly one full reference to the value: either
|
|
the one that was returned in the first place, or a floating reference
|
|
that has been converted to a full reference.
|
|
|
|
This function has an odd interaction when combined with
|
|
g_variant_ref_sink() running at the same time in another thread on
|
|
the same #GVariant instance. If g_variant_ref_sink() runs first then
|
|
the result will be that the floating reference is converted to a hard
|
|
reference. If g_variant_take_ref() runs first then the result will
|
|
be that the floating reference is converted to a hard reference and
|
|
an additional reference on top of that one is added. It is best to
|
|
avoid this situation.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the same @value</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_variant_unref" version="2.24">
|
|
<doc xml:space="preserve">Decreases the reference count of @value. When its reference count
|
|
drops to 0, the memory used by the variant is freed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="is_object_path" c:identifier="g_variant_is_object_path" version="2.24">
|
|
<doc xml:space="preserve">Determines if a given string is a valid D-Bus object path. You
|
|
should ensure that a string is a valid D-Bus object path before
|
|
passing it to g_variant_new_object_path().
|
|
|
|
A valid object path starts with `/` followed by zero or more
|
|
sequences of characters separated by `/` characters. Each sequence
|
|
must contain only the characters `[A-Z][a-z][0-9]_`. No sequence
|
|
(including the one following the final `/` character) may be empty.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @string is a D-Bus object path</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a normal C nul-terminated string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="is_signature" c:identifier="g_variant_is_signature" version="2.24">
|
|
<doc xml:space="preserve">Determines if a given string is a valid D-Bus type signature. You
|
|
should ensure that a string is a valid D-Bus type signature before
|
|
passing it to g_variant_new_signature().
|
|
|
|
D-Bus type signatures consist of zero or more definite #GVariantType
|
|
strings in sequence.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @string is a D-Bus type signature</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a normal C nul-terminated string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="parse" c:identifier="g_variant_parse" throws="1">
|
|
<doc xml:space="preserve">Parses a #GVariant from a text representation.
|
|
|
|
A single #GVariant is parsed from the content of @text.
|
|
|
|
The format is described [here][gvariant-text].
|
|
|
|
The memory at @limit will never be accessed and the parser behaves as
|
|
if the character at @limit is the nul terminator. This has the
|
|
effect of bounding @text.
|
|
|
|
If @endptr is non-%NULL then @text is permitted to contain data
|
|
following the value that this function parses and @endptr will be
|
|
updated to point to the first character past the end of the text
|
|
parsed by this function. If @endptr is %NULL and there is extra data
|
|
then an error is returned.
|
|
|
|
If @type is non-%NULL then the value will be parsed to have that
|
|
type. This may result in additional parse errors (in the case that
|
|
the parsed value doesn't fit the type) but may also result in fewer
|
|
errors (in the case that the type would have been ambiguous, such as
|
|
with empty arrays).
|
|
|
|
In the event that the parsing is successful, the resulting #GVariant
|
|
is returned. It is never floating, and must be freed with
|
|
g_variant_unref().
|
|
|
|
In case of any error, %NULL will be returned. If @error is non-%NULL
|
|
then it will be set to reflect the error that occurred.
|
|
|
|
Officially, the language understood by the parser is "any string
|
|
produced by g_variant_print()".
|
|
|
|
There may be implementation specific restrictions on deeply nested values,
|
|
which would result in a %G_VARIANT_PARSE_ERROR_RECURSION error. #GVariant is
|
|
guaranteed to handle nesting up to at least 64 levels.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a non-floating reference to a #GVariant, or %NULL</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="type" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GVariantType, or %NULL</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
<parameter name="text" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string containing a GVariant in text form</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="limit" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a pointer to the end of @text, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="endptr" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a location to store the end pointer, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="parse_error_print_context" c:identifier="g_variant_parse_error_print_context" version="2.40">
|
|
<doc xml:space="preserve">Pretty-prints a message showing the context of a #GVariant parse
|
|
error within the string for which parsing was attempted.
|
|
|
|
The resulting string is suitable for output to the console or other
|
|
monospace media where newlines are treated in the usual way.
|
|
|
|
The message will typically look something like one of the following:
|
|
|
|
|[
|
|
unterminated string constant:
|
|
(1, 2, 3, 'abc
|
|
^^^^
|
|
]|
|
|
|
|
or
|
|
|
|
|[
|
|
unable to find a common type:
|
|
[1, 2, 3, 'str']
|
|
^ ^^^^^
|
|
]|
|
|
|
|
The format of the message may change in a future version.
|
|
|
|
@error must have come from a failed attempt to g_variant_parse() and
|
|
@source_str must be exactly the same string that caused the error.
|
|
If @source_str was not nul-terminated when you passed it to
|
|
g_variant_parse() then you must add nul termination before using this
|
|
function.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the printed message</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="error" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GError from the #GVariantParseError domain</doc>
|
|
<type name="Error" c:type="GError*"/>
|
|
</parameter>
|
|
<parameter name="source_str" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string that was given to the parser</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="parse_error_quark" c:identifier="g_variant_parse_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="parser_get_error_quark" c:identifier="g_variant_parser_get_error_quark" deprecated="1">
|
|
<doc xml:space="preserve">Same as g_variant_error_quark().</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_variant_parse_error_quark() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
</record>
|
|
<record name="VariantBuilder" c:type="GVariantBuilder" glib:type-name="GVariantBuilder" glib:get-type="g_variant_builder_get_type" c:symbol-prefix="variant_builder">
|
|
<doc xml:space="preserve">A utility type for constructing container-type #GVariant instances.
|
|
|
|
This is an opaque structure and may only be accessed using the
|
|
following functions.
|
|
|
|
#GVariantBuilder is not threadsafe in any way. Do not attempt to
|
|
access it from more than one thread.</doc>
|
|
<union name="u" c:type="u">
|
|
<record name="s" c:type="s">
|
|
<field name="partial_magic" writable="1">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</field>
|
|
<field name="type" writable="1">
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</field>
|
|
<field name="y" writable="1">
|
|
<array zero-terminated="0" fixed-size="14">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</array>
|
|
</field>
|
|
</record>
|
|
<field name="x" writable="1">
|
|
<array zero-terminated="0" fixed-size="16">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</array>
|
|
</field>
|
|
</union>
|
|
<constructor name="new" c:identifier="g_variant_builder_new" version="2.24">
|
|
<doc xml:space="preserve">Allocates and initialises a new #GVariantBuilder.
|
|
|
|
You should call g_variant_builder_unref() on the return value when it
|
|
is no longer needed. The memory will not be automatically freed by
|
|
any other call.
|
|
|
|
In most cases it is easier to place a #GVariantBuilder directly on
|
|
the stack of the calling function and initialise it with
|
|
g_variant_builder_init().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a #GVariantBuilder</doc>
|
|
<type name="VariantBuilder" c:type="GVariantBuilder*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a container type</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<method name="add" c:identifier="g_variant_builder_add" version="2.24" introspectable="0">
|
|
<doc xml:space="preserve">Adds to a #GVariantBuilder.
|
|
|
|
This call is a convenience wrapper that is exactly equivalent to
|
|
calling g_variant_new() followed by g_variant_builder_add_value().
|
|
|
|
Note that the arguments must be of the correct width for their types
|
|
specified in @format_string. This can be achieved by casting them. See
|
|
the [GVariant varargs documentation][gvariant-varargs].
|
|
|
|
This function might be used as follows:
|
|
|
|
|[<!-- language="C" -->
|
|
GVariant *
|
|
make_pointless_dictionary (void)
|
|
{
|
|
GVariantBuilder builder;
|
|
int i;
|
|
|
|
g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY);
|
|
for (i = 0; i < 16; i++)
|
|
{
|
|
gchar buf[3];
|
|
|
|
sprintf (buf, "%d", i);
|
|
g_variant_builder_add (&builder, "{is}", i, buf);
|
|
}
|
|
|
|
return g_variant_builder_end (&builder);
|
|
}
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="builder" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantBuilder</doc>
|
|
<type name="VariantBuilder" c:type="GVariantBuilder*"/>
|
|
</instance-parameter>
|
|
<parameter name="format_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant varargs format string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">arguments, as per @format_string</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_parsed" c:identifier="g_variant_builder_add_parsed" version="2.26" introspectable="0">
|
|
<doc xml:space="preserve">Adds to a #GVariantBuilder.
|
|
|
|
This call is a convenience wrapper that is exactly equivalent to
|
|
calling g_variant_new_parsed() followed by
|
|
g_variant_builder_add_value().
|
|
|
|
Note that the arguments must be of the correct width for their types
|
|
specified in @format_string. This can be achieved by casting them. See
|
|
the [GVariant varargs documentation][gvariant-varargs].
|
|
|
|
This function might be used as follows:
|
|
|
|
|[<!-- language="C" -->
|
|
GVariant *
|
|
make_pointless_dictionary (void)
|
|
{
|
|
GVariantBuilder builder;
|
|
int i;
|
|
|
|
g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY);
|
|
g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600);
|
|
g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo");
|
|
g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}");
|
|
return g_variant_builder_end (&builder);
|
|
}
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="builder" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantBuilder</doc>
|
|
<type name="VariantBuilder" c:type="GVariantBuilder*"/>
|
|
</instance-parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">a text format #GVariant</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">arguments as per @format</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="add_value" c:identifier="g_variant_builder_add_value" version="2.24">
|
|
<doc xml:space="preserve">Adds @value to @builder.
|
|
|
|
It is an error to call this function in any way that would create an
|
|
inconsistent value to be constructed. Some examples of this are
|
|
putting different types of items into an array, putting the wrong
|
|
types or number of items in a tuple, putting more than one value into
|
|
a variant, etc.
|
|
|
|
If @value is a floating reference (see g_variant_ref_sink()),
|
|
the @builder instance takes ownership of @value.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="builder" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantBuilder</doc>
|
|
<type name="VariantBuilder" c:type="GVariantBuilder*"/>
|
|
</instance-parameter>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="clear" c:identifier="g_variant_builder_clear" version="2.24" introspectable="0">
|
|
<doc xml:space="preserve">Releases all memory associated with a #GVariantBuilder without
|
|
freeing the #GVariantBuilder structure itself.
|
|
|
|
It typically only makes sense to do this on a stack-allocated
|
|
#GVariantBuilder if you want to abort building the value part-way
|
|
through. This function need not be called if you call
|
|
g_variant_builder_end() and it also doesn't need to be called on
|
|
builders allocated with g_variant_builder_new() (see
|
|
g_variant_builder_unref() for that).
|
|
|
|
This function leaves the #GVariantBuilder structure set to all-zeros.
|
|
It is valid to call this function on either an initialised
|
|
#GVariantBuilder or one that is set to all-zeros but it is not valid
|
|
to call this function on uninitialised memory.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="builder" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantBuilder</doc>
|
|
<type name="VariantBuilder" c:type="GVariantBuilder*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="close" c:identifier="g_variant_builder_close" version="2.24">
|
|
<doc xml:space="preserve">Closes the subcontainer inside the given @builder that was opened by
|
|
the most recent call to g_variant_builder_open().
|
|
|
|
It is an error to call this function in any way that would create an
|
|
inconsistent value to be constructed (ie: too few values added to the
|
|
subcontainer).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="builder" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantBuilder</doc>
|
|
<type name="VariantBuilder" c:type="GVariantBuilder*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="end" c:identifier="g_variant_builder_end" version="2.24">
|
|
<doc xml:space="preserve">Ends the builder process and returns the constructed value.
|
|
|
|
It is not permissible to use @builder in any way after this call
|
|
except for reference counting operations (in the case of a
|
|
heap-allocated #GVariantBuilder) or by reinitialising it with
|
|
g_variant_builder_init() (in the case of stack-allocated). This
|
|
means that for the stack-allocated builders there is no need to
|
|
call g_variant_builder_clear() after the call to
|
|
g_variant_builder_end().
|
|
|
|
It is an error to call this function in any way that would create an
|
|
inconsistent value to be constructed (ie: insufficient number of
|
|
items added to a container with a specific number of children
|
|
required). It is also an error to call this function if the builder
|
|
was created with an indefinite array or maybe type and no children
|
|
have been added; in this case it is impossible to infer the type of
|
|
the empty array.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a new, floating, #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="builder" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantBuilder</doc>
|
|
<type name="VariantBuilder" c:type="GVariantBuilder*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="init" c:identifier="g_variant_builder_init" version="2.24" introspectable="0">
|
|
<doc xml:space="preserve">Initialises a #GVariantBuilder structure.
|
|
|
|
@type must be non-%NULL. It specifies the type of container to
|
|
construct. It can be an indefinite type such as
|
|
%G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)".
|
|
Maybe, array, tuple, dictionary entry and variant-typed values may be
|
|
constructed.
|
|
|
|
After the builder is initialised, values are added using
|
|
g_variant_builder_add_value() or g_variant_builder_add().
|
|
|
|
After all the child values are added, g_variant_builder_end() frees
|
|
the memory associated with the builder and returns the #GVariant that
|
|
was created.
|
|
|
|
This function completely ignores the previous contents of @builder.
|
|
On one hand this means that it is valid to pass in completely
|
|
uninitialised memory. On the other hand, this means that if you are
|
|
initialising over top of an existing #GVariantBuilder you need to
|
|
first call g_variant_builder_clear() in order to avoid leaking
|
|
memory.
|
|
|
|
You must not call g_variant_builder_ref() or
|
|
g_variant_builder_unref() on a #GVariantBuilder that was initialised
|
|
with this function. If you ever pass a reference to a
|
|
#GVariantBuilder outside of the control of your own code then you
|
|
should assume that the person receiving that reference may try to use
|
|
reference counting; you should use g_variant_builder_new() instead of
|
|
this function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="builder" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantBuilder</doc>
|
|
<type name="VariantBuilder" c:type="GVariantBuilder*"/>
|
|
</instance-parameter>
|
|
<parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a container type</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="open" c:identifier="g_variant_builder_open" version="2.24">
|
|
<doc xml:space="preserve">Opens a subcontainer inside the given @builder. When done adding
|
|
items to the subcontainer, g_variant_builder_close() must be called. @type
|
|
is the type of the container: so to build a tuple of several values, @type
|
|
must include the tuple itself.
|
|
|
|
It is an error to call this function in any way that would cause an
|
|
inconsistent value to be constructed (ie: adding too many values or
|
|
a value of an incorrect type).
|
|
|
|
Example of building a nested variant:
|
|
|[<!-- language="C" -->
|
|
GVariantBuilder builder;
|
|
guint32 some_number = get_number ();
|
|
g_autoptr (GHashTable) some_dict = get_dict ();
|
|
GHashTableIter iter;
|
|
const gchar *key;
|
|
const GVariant *value;
|
|
g_autoptr (GVariant) output = NULL;
|
|
|
|
g_variant_builder_init (&builder, G_VARIANT_TYPE ("(ua{sv})"));
|
|
g_variant_builder_add (&builder, "u", some_number);
|
|
g_variant_builder_open (&builder, G_VARIANT_TYPE ("a{sv}"));
|
|
|
|
g_hash_table_iter_init (&iter, some_dict);
|
|
while (g_hash_table_iter_next (&iter, (gpointer *) &key, (gpointer *) &value))
|
|
{
|
|
g_variant_builder_open (&builder, G_VARIANT_TYPE ("{sv}"));
|
|
g_variant_builder_add (&builder, "s", key);
|
|
g_variant_builder_add (&builder, "v", value);
|
|
g_variant_builder_close (&builder);
|
|
}
|
|
|
|
g_variant_builder_close (&builder);
|
|
|
|
output = g_variant_builder_end (&builder);
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="builder" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantBuilder</doc>
|
|
<type name="VariantBuilder" c:type="GVariantBuilder*"/>
|
|
</instance-parameter>
|
|
<parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GVariantType of the container</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_variant_builder_ref" version="2.24">
|
|
<doc xml:space="preserve">Increases the reference count on @builder.
|
|
|
|
Don't call this on stack-allocated #GVariantBuilder instances or bad
|
|
things will happen.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new reference to @builder</doc>
|
|
<type name="VariantBuilder" c:type="GVariantBuilder*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="builder" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantBuilder allocated by g_variant_builder_new()</doc>
|
|
<type name="VariantBuilder" c:type="GVariantBuilder*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_variant_builder_unref" version="2.24">
|
|
<doc xml:space="preserve">Decreases the reference count on @builder.
|
|
|
|
In the event that there are no more references, releases all memory
|
|
associated with the #GVariantBuilder.
|
|
|
|
Don't call this on stack-allocated #GVariantBuilder instances or bad
|
|
things will happen.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="builder" transfer-ownership="full">
|
|
<doc xml:space="preserve">a #GVariantBuilder allocated by g_variant_builder_new()</doc>
|
|
<type name="VariantBuilder" c:type="GVariantBuilder*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<enumeration name="VariantClass" version="2.24" c:type="GVariantClass">
|
|
<doc xml:space="preserve">The range of possible top-level types of #GVariant instances.</doc>
|
|
<member name="boolean" value="98" c:identifier="G_VARIANT_CLASS_BOOLEAN">
|
|
<doc xml:space="preserve">The #GVariant is a boolean.</doc>
|
|
</member>
|
|
<member name="byte" value="121" c:identifier="G_VARIANT_CLASS_BYTE">
|
|
<doc xml:space="preserve">The #GVariant is a byte.</doc>
|
|
</member>
|
|
<member name="int16" value="110" c:identifier="G_VARIANT_CLASS_INT16">
|
|
<doc xml:space="preserve">The #GVariant is a signed 16 bit integer.</doc>
|
|
</member>
|
|
<member name="uint16" value="113" c:identifier="G_VARIANT_CLASS_UINT16">
|
|
<doc xml:space="preserve">The #GVariant is an unsigned 16 bit integer.</doc>
|
|
</member>
|
|
<member name="int32" value="105" c:identifier="G_VARIANT_CLASS_INT32">
|
|
<doc xml:space="preserve">The #GVariant is a signed 32 bit integer.</doc>
|
|
</member>
|
|
<member name="uint32" value="117" c:identifier="G_VARIANT_CLASS_UINT32">
|
|
<doc xml:space="preserve">The #GVariant is an unsigned 32 bit integer.</doc>
|
|
</member>
|
|
<member name="int64" value="120" c:identifier="G_VARIANT_CLASS_INT64">
|
|
<doc xml:space="preserve">The #GVariant is a signed 64 bit integer.</doc>
|
|
</member>
|
|
<member name="uint64" value="116" c:identifier="G_VARIANT_CLASS_UINT64">
|
|
<doc xml:space="preserve">The #GVariant is an unsigned 64 bit integer.</doc>
|
|
</member>
|
|
<member name="handle" value="104" c:identifier="G_VARIANT_CLASS_HANDLE">
|
|
<doc xml:space="preserve">The #GVariant is a file handle index.</doc>
|
|
</member>
|
|
<member name="double" value="100" c:identifier="G_VARIANT_CLASS_DOUBLE">
|
|
<doc xml:space="preserve">The #GVariant is a double precision floating
|
|
point value.</doc>
|
|
</member>
|
|
<member name="string" value="115" c:identifier="G_VARIANT_CLASS_STRING">
|
|
<doc xml:space="preserve">The #GVariant is a normal string.</doc>
|
|
</member>
|
|
<member name="object_path" value="111" c:identifier="G_VARIANT_CLASS_OBJECT_PATH">
|
|
<doc xml:space="preserve">The #GVariant is a D-Bus object path
|
|
string.</doc>
|
|
</member>
|
|
<member name="signature" value="103" c:identifier="G_VARIANT_CLASS_SIGNATURE">
|
|
<doc xml:space="preserve">The #GVariant is a D-Bus signature string.</doc>
|
|
</member>
|
|
<member name="variant" value="118" c:identifier="G_VARIANT_CLASS_VARIANT">
|
|
<doc xml:space="preserve">The #GVariant is a variant.</doc>
|
|
</member>
|
|
<member name="maybe" value="109" c:identifier="G_VARIANT_CLASS_MAYBE">
|
|
<doc xml:space="preserve">The #GVariant is a maybe-typed value.</doc>
|
|
</member>
|
|
<member name="array" value="97" c:identifier="G_VARIANT_CLASS_ARRAY">
|
|
<doc xml:space="preserve">The #GVariant is an array.</doc>
|
|
</member>
|
|
<member name="tuple" value="40" c:identifier="G_VARIANT_CLASS_TUPLE">
|
|
<doc xml:space="preserve">The #GVariant is a tuple.</doc>
|
|
</member>
|
|
<member name="dict_entry" value="123" c:identifier="G_VARIANT_CLASS_DICT_ENTRY">
|
|
<doc xml:space="preserve">The #GVariant is a dictionary entry.</doc>
|
|
</member>
|
|
</enumeration>
|
|
<record name="VariantDict" c:type="GVariantDict" version="2.40" glib:type-name="GVariantDict" glib:get-type="g_variant_dict_get_type" c:symbol-prefix="variant_dict">
|
|
<doc xml:space="preserve">#GVariantDict is a mutable interface to #GVariant dictionaries.
|
|
|
|
It can be used for doing a sequence of dictionary lookups in an
|
|
efficient way on an existing #GVariant dictionary or it can be used
|
|
to construct new dictionaries with a hashtable-like interface. It
|
|
can also be used for taking existing dictionaries and modifying them
|
|
in order to create new ones.
|
|
|
|
#GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT
|
|
dictionaries.
|
|
|
|
It is possible to use #GVariantDict allocated on the stack or on the
|
|
heap. When using a stack-allocated #GVariantDict, you begin with a
|
|
call to g_variant_dict_init() and free the resources with a call to
|
|
g_variant_dict_clear().
|
|
|
|
Heap-allocated #GVariantDict follows normal refcounting rules: you
|
|
allocate it with g_variant_dict_new() and use g_variant_dict_ref()
|
|
and g_variant_dict_unref().
|
|
|
|
g_variant_dict_end() is used to convert the #GVariantDict back into a
|
|
dictionary-type #GVariant. When used with stack-allocated instances,
|
|
this also implicitly frees all associated memory, but for
|
|
heap-allocated instances, you must still call g_variant_dict_unref()
|
|
afterwards.
|
|
|
|
You will typically want to use a heap-allocated #GVariantDict when
|
|
you expose it as part of an API. For most other uses, the
|
|
stack-allocated form will be more convenient.
|
|
|
|
Consider the following two examples that do the same thing in each
|
|
style: take an existing dictionary and look up the "count" uint32
|
|
key, adding 1 to it if it is found, or returning an error if the
|
|
key is not found. Each returns the new dictionary as a floating
|
|
#GVariant.
|
|
|
|
## Using a stack-allocated GVariantDict
|
|
|
|
|[<!-- language="C" -->
|
|
GVariant *
|
|
add_to_count (GVariant *orig,
|
|
GError **error)
|
|
{
|
|
GVariantDict dict;
|
|
guint32 count;
|
|
|
|
g_variant_dict_init (&dict, orig);
|
|
if (!g_variant_dict_lookup (&dict, "count", "u", &count))
|
|
{
|
|
g_set_error (...);
|
|
g_variant_dict_clear (&dict);
|
|
return NULL;
|
|
}
|
|
|
|
g_variant_dict_insert (&dict, "count", "u", count + 1);
|
|
|
|
return g_variant_dict_end (&dict);
|
|
}
|
|
]|
|
|
|
|
## Using heap-allocated GVariantDict
|
|
|
|
|[<!-- language="C" -->
|
|
GVariant *
|
|
add_to_count (GVariant *orig,
|
|
GError **error)
|
|
{
|
|
GVariantDict *dict;
|
|
GVariant *result;
|
|
guint32 count;
|
|
|
|
dict = g_variant_dict_new (orig);
|
|
|
|
if (g_variant_dict_lookup (dict, "count", "u", &count))
|
|
{
|
|
g_variant_dict_insert (dict, "count", "u", count + 1);
|
|
result = g_variant_dict_end (dict);
|
|
}
|
|
else
|
|
{
|
|
g_set_error (...);
|
|
result = NULL;
|
|
}
|
|
|
|
g_variant_dict_unref (dict);
|
|
|
|
return result;
|
|
}
|
|
]|</doc>
|
|
<union name="u" c:type="u">
|
|
<record name="s" c:type="s">
|
|
<field name="asv" writable="1">
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</field>
|
|
<field name="partial_magic" writable="1">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</field>
|
|
<field name="y" writable="1">
|
|
<array zero-terminated="0" fixed-size="14">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</array>
|
|
</field>
|
|
</record>
|
|
<field name="x" writable="1">
|
|
<array zero-terminated="0" fixed-size="16">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</array>
|
|
</field>
|
|
</union>
|
|
<constructor name="new" c:identifier="g_variant_dict_new" version="2.40">
|
|
<doc xml:space="preserve">Allocates and initialises a new #GVariantDict.
|
|
|
|
You should call g_variant_dict_unref() on the return value when it
|
|
is no longer needed. The memory will not be automatically freed by
|
|
any other call.
|
|
|
|
In some cases it may be easier to place a #GVariantDict directly on
|
|
the stack of the calling function and initialise it with
|
|
g_variant_dict_init(). This is particularly useful when you are
|
|
using #GVariantDict to construct a #GVariant.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a #GVariantDict</doc>
|
|
<type name="VariantDict" c:type="GVariantDict*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="from_asv" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the #GVariant with which to initialise the
|
|
dictionary</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<method name="clear" c:identifier="g_variant_dict_clear" version="2.40">
|
|
<doc xml:space="preserve">Releases all memory associated with a #GVariantDict without freeing
|
|
the #GVariantDict structure itself.
|
|
|
|
It typically only makes sense to do this on a stack-allocated
|
|
#GVariantDict if you want to abort building the value part-way
|
|
through. This function need not be called if you call
|
|
g_variant_dict_end() and it also doesn't need to be called on dicts
|
|
allocated with g_variant_dict_new (see g_variant_dict_unref() for
|
|
that).
|
|
|
|
It is valid to call this function on either an initialised
|
|
#GVariantDict or one that was previously cleared by an earlier call
|
|
to g_variant_dict_clear() but it is not valid to call this function
|
|
on uninitialised memory.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="dict" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantDict</doc>
|
|
<type name="VariantDict" c:type="GVariantDict*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="contains" c:identifier="g_variant_dict_contains" version="2.40">
|
|
<doc xml:space="preserve">Checks if @key exists in @dict.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @key is in @dict</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="dict" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantDict</doc>
|
|
<type name="VariantDict" c:type="GVariantDict*"/>
|
|
</instance-parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">the key to look up in the dictionary</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="end" c:identifier="g_variant_dict_end" version="2.40">
|
|
<doc xml:space="preserve">Returns the current value of @dict as a #GVariant of type
|
|
%G_VARIANT_TYPE_VARDICT, clearing it in the process.
|
|
|
|
It is not permissible to use @dict in any way after this call except
|
|
for reference counting operations (in the case of a heap-allocated
|
|
#GVariantDict) or by reinitialising it with g_variant_dict_init() (in
|
|
the case of stack-allocated).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a new, floating, #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="dict" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantDict</doc>
|
|
<type name="VariantDict" c:type="GVariantDict*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="init" c:identifier="g_variant_dict_init" version="2.40" introspectable="0">
|
|
<doc xml:space="preserve">Initialises a #GVariantDict structure.
|
|
|
|
If @from_asv is given, it is used to initialise the dictionary.
|
|
|
|
This function completely ignores the previous contents of @dict. On
|
|
one hand this means that it is valid to pass in completely
|
|
uninitialised memory. On the other hand, this means that if you are
|
|
initialising over top of an existing #GVariantDict you need to first
|
|
call g_variant_dict_clear() in order to avoid leaking memory.
|
|
|
|
You must not call g_variant_dict_ref() or g_variant_dict_unref() on a
|
|
#GVariantDict that was initialised with this function. If you ever
|
|
pass a reference to a #GVariantDict outside of the control of your
|
|
own code then you should assume that the person receiving that
|
|
reference may try to use reference counting; you should use
|
|
g_variant_dict_new() instead of this function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="dict" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantDict</doc>
|
|
<type name="VariantDict" c:type="GVariantDict*"/>
|
|
</instance-parameter>
|
|
<parameter name="from_asv" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the initial value for @dict</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert" c:identifier="g_variant_dict_insert" version="2.40" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a value into a #GVariantDict.
|
|
|
|
This call is a convenience wrapper that is exactly equivalent to
|
|
calling g_variant_new() followed by g_variant_dict_insert_value().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="dict" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantDict</doc>
|
|
<type name="VariantDict" c:type="GVariantDict*"/>
|
|
</instance-parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">the key to insert a value for</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="format_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariant varargs format string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">arguments, as per @format_string</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="insert_value" c:identifier="g_variant_dict_insert_value" version="2.40">
|
|
<doc xml:space="preserve">Inserts (or replaces) a key in a #GVariantDict.
|
|
|
|
@value is consumed if it is floating.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="dict" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantDict</doc>
|
|
<type name="VariantDict" c:type="GVariantDict*"/>
|
|
</instance-parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">the key to insert a value for</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">the value to insert</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="lookup" c:identifier="g_variant_dict_lookup" version="2.40" introspectable="0">
|
|
<doc xml:space="preserve">Looks up a value in a #GVariantDict.
|
|
|
|
This function is a wrapper around g_variant_dict_lookup_value() and
|
|
g_variant_get(). In the case that %NULL would have been returned,
|
|
this function returns %FALSE. Otherwise, it unpacks the returned
|
|
value and returns %TRUE.
|
|
|
|
@format_string determines the C types that are used for unpacking the
|
|
values and also determines if the values are copied or borrowed, see the
|
|
section on [GVariant format strings][gvariant-format-strings-pointers].</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a value was unpacked</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="dict" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantDict</doc>
|
|
<type name="VariantDict" c:type="GVariantDict*"/>
|
|
</instance-parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">the key to look up in the dictionary</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="format_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a GVariant format string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">the arguments to unpack the value into</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="lookup_value" c:identifier="g_variant_dict_lookup_value" version="2.40">
|
|
<doc xml:space="preserve">Looks up a value in a #GVariantDict.
|
|
|
|
If @key is not found in @dictionary, %NULL is returned.
|
|
|
|
The @expected_type string specifies what type of value is expected.
|
|
If the value associated with @key has a different type then %NULL is
|
|
returned.
|
|
|
|
If the key is found and the value has the correct type, it is
|
|
returned. If @expected_type was specified then any non-%NULL return
|
|
value will have this type.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the value of the dictionary key, or %NULL</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="dict" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantDict</doc>
|
|
<type name="VariantDict" c:type="GVariantDict*"/>
|
|
</instance-parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">the key to look up in the dictionary</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="expected_type" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GVariantType, or %NULL</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="ref" c:identifier="g_variant_dict_ref" version="2.40">
|
|
<doc xml:space="preserve">Increases the reference count on @dict.
|
|
|
|
Don't call this on stack-allocated #GVariantDict instances or bad
|
|
things will happen.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new reference to @dict</doc>
|
|
<type name="VariantDict" c:type="GVariantDict*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="dict" transfer-ownership="none">
|
|
<doc xml:space="preserve">a heap-allocated #GVariantDict</doc>
|
|
<type name="VariantDict" c:type="GVariantDict*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="remove" c:identifier="g_variant_dict_remove" version="2.40">
|
|
<doc xml:space="preserve">Removes a key and its associated value from a #GVariantDict.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key was found and removed</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="dict" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantDict</doc>
|
|
<type name="VariantDict" c:type="GVariantDict*"/>
|
|
</instance-parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">the key to remove</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="unref" c:identifier="g_variant_dict_unref" version="2.40">
|
|
<doc xml:space="preserve">Decreases the reference count on @dict.
|
|
|
|
In the event that there are no more references, releases all memory
|
|
associated with the #GVariantDict.
|
|
|
|
Don't call this on stack-allocated #GVariantDict instances or bad
|
|
things will happen.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="dict" transfer-ownership="full">
|
|
<doc xml:space="preserve">a heap-allocated #GVariantDict</doc>
|
|
<type name="VariantDict" c:type="GVariantDict*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<record name="VariantIter" c:type="GVariantIter" introspectable="0">
|
|
<doc xml:space="preserve">#GVariantIter is an opaque data structure and can only be accessed
|
|
using the following functions.</doc>
|
|
<field name="x" readable="0" private="1">
|
|
<array zero-terminated="0" fixed-size="16">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</array>
|
|
</field>
|
|
<method name="copy" c:identifier="g_variant_iter_copy" version="2.24" introspectable="0">
|
|
<doc xml:space="preserve">Creates a new heap-allocated #GVariantIter to iterate over the
|
|
container that was being iterated over by @iter. Iteration begins on
|
|
the new iterator from the current position of the old iterator but
|
|
the two copies are independent past that point.
|
|
|
|
Use g_variant_iter_free() to free the return value when you no longer
|
|
need it.
|
|
|
|
A reference is taken to the container that @iter is iterating over
|
|
and will be related only when g_variant_iter_free() is called.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new heap-allocated #GVariantIter</doc>
|
|
<type name="VariantIter" c:type="GVariantIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantIter</doc>
|
|
<type name="VariantIter" c:type="GVariantIter*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free" c:identifier="g_variant_iter_free" version="2.24">
|
|
<doc xml:space="preserve">Frees a heap-allocated #GVariantIter. Only call this function on
|
|
iterators that were returned by g_variant_iter_new() or
|
|
g_variant_iter_copy().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="full">
|
|
<doc xml:space="preserve">a heap-allocated #GVariantIter</doc>
|
|
<type name="VariantIter" c:type="GVariantIter*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="init" c:identifier="g_variant_iter_init" version="2.24" introspectable="0">
|
|
<doc xml:space="preserve">Initialises (without allocating) a #GVariantIter. @iter may be
|
|
completely uninitialised prior to this call; its old value is
|
|
ignored.
|
|
|
|
The iterator remains valid for as long as @value exists, and need not
|
|
be freed in any way.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of items in @value</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GVariantIter</doc>
|
|
<type name="VariantIter" c:type="GVariantIter*"/>
|
|
</instance-parameter>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a container #GVariant</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="loop" c:identifier="g_variant_iter_loop" version="2.24" introspectable="0">
|
|
<doc xml:space="preserve">Gets the next item in the container and unpacks it into the variable
|
|
argument list according to @format_string, returning %TRUE.
|
|
|
|
If no more items remain then %FALSE is returned.
|
|
|
|
On the first call to this function, the pointers appearing on the
|
|
variable argument list are assumed to point at uninitialised memory.
|
|
On the second and later calls, it is assumed that the same pointers
|
|
will be given and that they will point to the memory as set by the
|
|
previous call to this function. This allows the previous values to
|
|
be freed, as appropriate.
|
|
|
|
This function is intended to be used with a while loop as
|
|
demonstrated in the following example. This function can only be
|
|
used when iterating over an array. It is only valid to call this
|
|
function with a string constant for the format string and the same
|
|
string constant must be used each time. Mixing calls to this
|
|
function and g_variant_iter_next() or g_variant_iter_next_value() on
|
|
the same iterator causes undefined behavior.
|
|
|
|
If you break out of a such a while loop using g_variant_iter_loop() then
|
|
you must free or unreference all the unpacked values as you would with
|
|
g_variant_get(). Failure to do so will cause a memory leak.
|
|
|
|
Here is an example for memory management with g_variant_iter_loop():
|
|
|[<!-- language="C" -->
|
|
// Iterates a dictionary of type 'a{sv}'
|
|
void
|
|
iterate_dictionary (GVariant *dictionary)
|
|
{
|
|
GVariantIter iter;
|
|
GVariant *value;
|
|
gchar *key;
|
|
|
|
g_variant_iter_init (&iter, dictionary);
|
|
while (g_variant_iter_loop (&iter, "{sv}", &key, &value))
|
|
{
|
|
g_print ("Item '%s' has type '%s'\n", key,
|
|
g_variant_get_type_string (value));
|
|
|
|
// no need to free 'key' and 'value' here
|
|
// unless breaking out of this loop
|
|
}
|
|
}
|
|
]|
|
|
|
|
For most cases you should use g_variant_iter_next().
|
|
|
|
This function is really only useful when unpacking into #GVariant or
|
|
#GVariantIter in order to allow you to skip the call to
|
|
g_variant_unref() or g_variant_iter_free().
|
|
|
|
For example, if you are only looping over simple integer and string
|
|
types, g_variant_iter_next() is definitely preferred. For string
|
|
types, use the '&' prefix to avoid allocating any memory at all (and
|
|
thereby avoiding the need to free anything as well).
|
|
|
|
@format_string determines the C types that are used for unpacking
|
|
the values and also determines if the values are copied or borrowed.
|
|
|
|
See the section on
|
|
[GVariant format strings][gvariant-format-strings-pointers].</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a value was unpacked, or %FALSE if there was no
|
|
value</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantIter</doc>
|
|
<type name="VariantIter" c:type="GVariantIter*"/>
|
|
</instance-parameter>
|
|
<parameter name="format_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a GVariant format string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">the arguments to unpack the value into</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="n_children" c:identifier="g_variant_iter_n_children" version="2.24">
|
|
<doc xml:space="preserve">Queries the number of child items in the container that we are
|
|
iterating over. This is the total number of items -- not the number
|
|
of items remaining.
|
|
|
|
This function might be useful for preallocation of arrays.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of children in the container</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantIter</doc>
|
|
<type name="VariantIter" c:type="GVariantIter*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="next" c:identifier="g_variant_iter_next" version="2.24" introspectable="0">
|
|
<doc xml:space="preserve">Gets the next item in the container and unpacks it into the variable
|
|
argument list according to @format_string, returning %TRUE.
|
|
|
|
If no more items remain then %FALSE is returned.
|
|
|
|
All of the pointers given on the variable arguments list of this
|
|
function are assumed to point at uninitialised memory. It is the
|
|
responsibility of the caller to free all of the values returned by
|
|
the unpacking process.
|
|
|
|
Here is an example for memory management with g_variant_iter_next():
|
|
|[<!-- language="C" -->
|
|
// Iterates a dictionary of type 'a{sv}'
|
|
void
|
|
iterate_dictionary (GVariant *dictionary)
|
|
{
|
|
GVariantIter iter;
|
|
GVariant *value;
|
|
gchar *key;
|
|
|
|
g_variant_iter_init (&iter, dictionary);
|
|
while (g_variant_iter_next (&iter, "{sv}", &key, &value))
|
|
{
|
|
g_print ("Item '%s' has type '%s'\n", key,
|
|
g_variant_get_type_string (value));
|
|
|
|
// must free data for ourselves
|
|
g_variant_unref (value);
|
|
g_free (key);
|
|
}
|
|
}
|
|
]|
|
|
|
|
For a solution that is likely to be more convenient to C programmers
|
|
when dealing with loops, see g_variant_iter_loop().
|
|
|
|
@format_string determines the C types that are used for unpacking
|
|
the values and also determines if the values are copied or borrowed.
|
|
|
|
See the section on
|
|
[GVariant format strings][gvariant-format-strings-pointers].</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a value was unpacked, or %FALSE if there as no value</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantIter</doc>
|
|
<type name="VariantIter" c:type="GVariantIter*"/>
|
|
</instance-parameter>
|
|
<parameter name="format_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a GVariant format string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">the arguments to unpack the value into</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="next_value" c:identifier="g_variant_iter_next_value" version="2.24">
|
|
<doc xml:space="preserve">Gets the next item in the container. If no more items remain then
|
|
%NULL is returned.
|
|
|
|
Use g_variant_unref() to drop your reference on the return value when
|
|
you no longer need it.
|
|
|
|
Here is an example for iterating with g_variant_iter_next_value():
|
|
|[<!-- language="C" -->
|
|
// recursively iterate a container
|
|
void
|
|
iterate_container_recursive (GVariant *container)
|
|
{
|
|
GVariantIter iter;
|
|
GVariant *child;
|
|
|
|
g_variant_iter_init (&iter, container);
|
|
while ((child = g_variant_iter_next_value (&iter)))
|
|
{
|
|
g_print ("type '%s'\n", g_variant_get_type_string (child));
|
|
|
|
if (g_variant_is_container (child))
|
|
iterate_container_recursive (child);
|
|
|
|
g_variant_unref (child);
|
|
}
|
|
}
|
|
]|</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a #GVariant, or %NULL</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantIter</doc>
|
|
<type name="VariantIter" c:type="GVariantIter*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
</record>
|
|
<enumeration name="VariantParseError" c:type="GVariantParseError" glib:error-domain="g-variant-parse-error-quark">
|
|
<doc xml:space="preserve">Error codes returned by parsing text-format GVariants.</doc>
|
|
<member name="failed" value="0" c:identifier="G_VARIANT_PARSE_ERROR_FAILED">
|
|
<doc xml:space="preserve">generic error (unused)</doc>
|
|
</member>
|
|
<member name="basic_type_expected" value="1" c:identifier="G_VARIANT_PARSE_ERROR_BASIC_TYPE_EXPECTED">
|
|
<doc xml:space="preserve">a non-basic #GVariantType was given where a basic type was expected</doc>
|
|
</member>
|
|
<member name="cannot_infer_type" value="2" c:identifier="G_VARIANT_PARSE_ERROR_CANNOT_INFER_TYPE">
|
|
<doc xml:space="preserve">cannot infer the #GVariantType</doc>
|
|
</member>
|
|
<member name="definite_type_expected" value="3" c:identifier="G_VARIANT_PARSE_ERROR_DEFINITE_TYPE_EXPECTED">
|
|
<doc xml:space="preserve">an indefinite #GVariantType was given where a definite type was expected</doc>
|
|
</member>
|
|
<member name="input_not_at_end" value="4" c:identifier="G_VARIANT_PARSE_ERROR_INPUT_NOT_AT_END">
|
|
<doc xml:space="preserve">extra data after parsing finished</doc>
|
|
</member>
|
|
<member name="invalid_character" value="5" c:identifier="G_VARIANT_PARSE_ERROR_INVALID_CHARACTER">
|
|
<doc xml:space="preserve">invalid character in number or unicode escape</doc>
|
|
</member>
|
|
<member name="invalid_format_string" value="6" c:identifier="G_VARIANT_PARSE_ERROR_INVALID_FORMAT_STRING">
|
|
<doc xml:space="preserve">not a valid #GVariant format string</doc>
|
|
</member>
|
|
<member name="invalid_object_path" value="7" c:identifier="G_VARIANT_PARSE_ERROR_INVALID_OBJECT_PATH">
|
|
<doc xml:space="preserve">not a valid object path</doc>
|
|
</member>
|
|
<member name="invalid_signature" value="8" c:identifier="G_VARIANT_PARSE_ERROR_INVALID_SIGNATURE">
|
|
<doc xml:space="preserve">not a valid type signature</doc>
|
|
</member>
|
|
<member name="invalid_type_string" value="9" c:identifier="G_VARIANT_PARSE_ERROR_INVALID_TYPE_STRING">
|
|
<doc xml:space="preserve">not a valid #GVariant type string</doc>
|
|
</member>
|
|
<member name="no_common_type" value="10" c:identifier="G_VARIANT_PARSE_ERROR_NO_COMMON_TYPE">
|
|
<doc xml:space="preserve">could not find a common type for array entries</doc>
|
|
</member>
|
|
<member name="number_out_of_range" value="11" c:identifier="G_VARIANT_PARSE_ERROR_NUMBER_OUT_OF_RANGE">
|
|
<doc xml:space="preserve">the numerical value is out of range of the given type</doc>
|
|
</member>
|
|
<member name="number_too_big" value="12" c:identifier="G_VARIANT_PARSE_ERROR_NUMBER_TOO_BIG">
|
|
<doc xml:space="preserve">the numerical value is out of range for any type</doc>
|
|
</member>
|
|
<member name="type_error" value="13" c:identifier="G_VARIANT_PARSE_ERROR_TYPE_ERROR">
|
|
<doc xml:space="preserve">cannot parse as variant of the specified type</doc>
|
|
</member>
|
|
<member name="unexpected_token" value="14" c:identifier="G_VARIANT_PARSE_ERROR_UNEXPECTED_TOKEN">
|
|
<doc xml:space="preserve">an unexpected token was encountered</doc>
|
|
</member>
|
|
<member name="unknown_keyword" value="15" c:identifier="G_VARIANT_PARSE_ERROR_UNKNOWN_KEYWORD">
|
|
<doc xml:space="preserve">an unknown keyword was encountered</doc>
|
|
</member>
|
|
<member name="unterminated_string_constant" value="16" c:identifier="G_VARIANT_PARSE_ERROR_UNTERMINATED_STRING_CONSTANT">
|
|
<doc xml:space="preserve">unterminated string constant</doc>
|
|
</member>
|
|
<member name="value_expected" value="17" c:identifier="G_VARIANT_PARSE_ERROR_VALUE_EXPECTED">
|
|
<doc xml:space="preserve">no value given</doc>
|
|
</member>
|
|
<member name="recursion" value="18" c:identifier="G_VARIANT_PARSE_ERROR_RECURSION">
|
|
<doc xml:space="preserve">variant was too deeply nested; #GVariant is only guaranteed to handle nesting up to 64 levels (Since: 2.64)</doc>
|
|
</member>
|
|
</enumeration>
|
|
<record name="VariantType" c:type="GVariantType" glib:type-name="GVariantType" glib:get-type="g_variant_type_get_gtype" c:symbol-prefix="variant_type">
|
|
<doc xml:space="preserve">This section introduces the GVariant type system. It is based, in
|
|
large part, on the D-Bus type system, with two major changes and
|
|
some minor lifting of restrictions. The
|
|
[D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html),
|
|
therefore, provides a significant amount of
|
|
information that is useful when working with GVariant.
|
|
|
|
The first major change with respect to the D-Bus type system is the
|
|
introduction of maybe (or "nullable") types. Any type in GVariant can be
|
|
converted to a maybe type, in which case, "nothing" (or "null") becomes a
|
|
valid value. Maybe types have been added by introducing the
|
|
character "m" to type strings.
|
|
|
|
The second major change is that the GVariant type system supports the
|
|
concept of "indefinite types" -- types that are less specific than
|
|
the normal types found in D-Bus. For example, it is possible to speak
|
|
of "an array of any type" in GVariant, where the D-Bus type system
|
|
would require you to speak of "an array of integers" or "an array of
|
|
strings". Indefinite types have been added by introducing the
|
|
characters "*", "?" and "r" to type strings.
|
|
|
|
Finally, all arbitrary restrictions relating to the complexity of
|
|
types are lifted along with the restriction that dictionary entries
|
|
may only appear nested inside of arrays.
|
|
|
|
Just as in D-Bus, GVariant types are described with strings ("type
|
|
strings"). Subject to the differences mentioned above, these strings
|
|
are of the same form as those found in DBus. Note, however: D-Bus
|
|
always works in terms of messages and therefore individual type
|
|
strings appear nowhere in its interface. Instead, "signatures"
|
|
are a concatenation of the strings of the type of each argument in a
|
|
message. GVariant deals with single values directly so GVariant type
|
|
strings always describe the type of exactly one value. This means
|
|
that a D-Bus signature string is generally not a valid GVariant type
|
|
string -- except in the case that it is the signature of a message
|
|
containing exactly one argument.
|
|
|
|
An indefinite type is similar in spirit to what may be called an
|
|
abstract type in other type systems. No value can exist that has an
|
|
indefinite type as its type, but values can exist that have types
|
|
that are subtypes of indefinite types. That is to say,
|
|
g_variant_get_type() will never return an indefinite type, but
|
|
calling g_variant_is_of_type() with an indefinite type may return
|
|
%TRUE. For example, you cannot have a value that represents "an
|
|
array of no particular type", but you can have an "array of integers"
|
|
which certainly matches the type of "an array of no particular type",
|
|
since "array of integers" is a subtype of "array of no particular
|
|
type".
|
|
|
|
This is similar to how instances of abstract classes may not
|
|
directly exist in other type systems, but instances of their
|
|
non-abstract subtypes may. For example, in GTK, no object that has
|
|
the type of #GtkBin can exist (since #GtkBin is an abstract class),
|
|
but a #GtkWindow can certainly be instantiated, and you would say
|
|
that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of
|
|
#GtkBin).
|
|
|
|
## GVariant Type Strings
|
|
|
|
A GVariant type string can be any of the following:
|
|
|
|
- any basic type string (listed below)
|
|
|
|
- "v", "r" or "*"
|
|
|
|
- one of the characters 'a' or 'm', followed by another type string
|
|
|
|
- the character '(', followed by a concatenation of zero or more other
|
|
type strings, followed by the character ')'
|
|
|
|
- the character '{', followed by a basic type string (see below),
|
|
followed by another type string, followed by the character '}'
|
|
|
|
A basic type string describes a basic type (as per
|
|
g_variant_type_is_basic()) and is always a single character in length.
|
|
The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t",
|
|
"h", "d", "s", "o", "g" and "?".
|
|
|
|
The above definition is recursive to arbitrary depth. "aaaaai" and
|
|
"(ui(nq((y)))s)" are both valid type strings, as is
|
|
"a(aa(ui)(qna{ya(yd)}))". In order to not hit memory limits, #GVariant
|
|
imposes a limit on recursion depth of 65 nested containers. This is the
|
|
limit in the D-Bus specification (64) plus one to allow a #GDBusMessage to
|
|
be nested in a top-level tuple.
|
|
|
|
The meaning of each of the characters is as follows:
|
|
- `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value.
|
|
- `y`: the type string of %G_VARIANT_TYPE_BYTE; a byte.
|
|
- `n`: the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit integer.
|
|
- `q`: the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit integer.
|
|
- `i`: the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit integer.
|
|
- `u`: the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit integer.
|
|
- `x`: the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit integer.
|
|
- `t`: the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit integer.
|
|
- `h`: the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit value
|
|
that, by convention, is used as an index into an array of file
|
|
descriptors that are sent alongside a D-Bus message.
|
|
- `d`: the type string of %G_VARIANT_TYPE_DOUBLE; a double precision
|
|
floating point value.
|
|
- `s`: the type string of %G_VARIANT_TYPE_STRING; a string.
|
|
- `o`: the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in the form
|
|
of a D-Bus object path.
|
|
- `g`: the type string of %G_VARIANT_TYPE_SIGNATURE; a string in the form of
|
|
a D-Bus type signature.
|
|
- `?`: the type string of %G_VARIANT_TYPE_BASIC; an indefinite type that
|
|
is a supertype of any of the basic types.
|
|
- `v`: the type string of %G_VARIANT_TYPE_VARIANT; a container type that
|
|
contain any other type of value.
|
|
- `a`: used as a prefix on another type string to mean an array of that
|
|
type; the type string "ai", for example, is the type of an array of
|
|
signed 32-bit integers.
|
|
- `m`: used as a prefix on another type string to mean a "maybe", or
|
|
"nullable", version of that type; the type string "ms", for example,
|
|
is the type of a value that maybe contains a string, or maybe contains
|
|
nothing.
|
|
- `()`: used to enclose zero or more other concatenated type strings to
|
|
create a tuple type; the type string "(is)", for example, is the type of
|
|
a pair of an integer and a string.
|
|
- `r`: the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type that is
|
|
a supertype of any tuple type, regardless of the number of items.
|
|
- `{}`: used to enclose a basic type string concatenated with another type
|
|
string to create a dictionary entry type, which usually appears inside of
|
|
an array to form a dictionary; the type string "a{sd}", for example, is
|
|
the type of a dictionary that maps strings to double precision floating
|
|
point values.
|
|
|
|
The first type (the basic type) is the key type and the second type is
|
|
the value type. The reason that the first type is restricted to being a
|
|
basic type is so that it can easily be hashed.
|
|
- `*`: the type string of %G_VARIANT_TYPE_ANY; the indefinite type that is
|
|
a supertype of all types. Note that, as with all type strings, this
|
|
character represents exactly one type. It cannot be used inside of tuples
|
|
to mean "any number of items".
|
|
|
|
Any type string of a container that contains an indefinite type is,
|
|
itself, an indefinite type. For example, the type string "a*"
|
|
(corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type
|
|
that is a supertype of every array type. "(*s)" is a supertype
|
|
of all tuples that contain exactly two items where the second
|
|
item is a string.
|
|
|
|
"a{?*}" is an indefinite type that is a supertype of all arrays
|
|
containing dictionary entries where the key is any basic type and
|
|
the value is any type at all. This is, by definition, a dictionary,
|
|
so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note
|
|
that, due to the restriction that the key of a dictionary entry must
|
|
be a basic type, "{**}" is not a valid type string.</doc>
|
|
<constructor name="new" c:identifier="g_variant_type_new" version="2.24">
|
|
<doc xml:space="preserve">Creates a new #GVariantType corresponding to the type string given
|
|
by @type_string. It is appropriate to call g_variant_type_free() on
|
|
the return value.
|
|
|
|
It is a programmer error to call this function with an invalid type
|
|
string. Use g_variant_type_string_is_valid() if you are unsure.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GVariantType</doc>
|
|
<type name="VariantType" c:type="GVariantType*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="type_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid GVariant type string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_array" c:identifier="g_variant_type_new_array">
|
|
<doc xml:space="preserve">Constructs the type corresponding to an array of elements of the
|
|
type @type.
|
|
|
|
It is appropriate to call g_variant_type_free() on the return value.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new array #GVariantType
|
|
|
|
Since 2.24</doc>
|
|
<type name="VariantType" c:type="GVariantType*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="element" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_dict_entry" c:identifier="g_variant_type_new_dict_entry">
|
|
<doc xml:space="preserve">Constructs the type corresponding to a dictionary entry with a key
|
|
of type @key and a value of type @value.
|
|
|
|
It is appropriate to call g_variant_type_free() on the return value.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new dictionary entry #GVariantType
|
|
|
|
Since 2.24</doc>
|
|
<type name="VariantType" c:type="GVariantType*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">a basic #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_maybe" c:identifier="g_variant_type_new_maybe">
|
|
<doc xml:space="preserve">Constructs the type corresponding to a maybe instance containing
|
|
type @type or Nothing.
|
|
|
|
It is appropriate to call g_variant_type_free() on the return value.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new maybe #GVariantType
|
|
|
|
Since 2.24</doc>
|
|
<type name="VariantType" c:type="GVariantType*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="element" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<constructor name="new_tuple" c:identifier="g_variant_type_new_tuple">
|
|
<doc xml:space="preserve">Constructs a new tuple type, from @items.
|
|
|
|
@length is the number of items in @items, or -1 to indicate that
|
|
@items is %NULL-terminated.
|
|
|
|
It is appropriate to call g_variant_type_free() on the return value.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new tuple #GVariantType
|
|
|
|
Since 2.24</doc>
|
|
<type name="VariantType" c:type="GVariantType*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="items" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array of #GVariantTypes, one for each item</doc>
|
|
<array length="1" zero-terminated="0" c:type="const GVariantType* const*">
|
|
<type name="VariantType" c:type="GVariantType*"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @items, or -1</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</constructor>
|
|
<method name="copy" c:identifier="g_variant_type_copy">
|
|
<doc xml:space="preserve">Makes a copy of a #GVariantType. It is appropriate to call
|
|
g_variant_type_free() on the return value. @type may not be %NULL.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GVariantType
|
|
|
|
Since 2.24</doc>
|
|
<type name="VariantType" c:type="GVariantType*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="dup_string" c:identifier="g_variant_type_dup_string">
|
|
<doc xml:space="preserve">Returns a newly-allocated copy of the type string corresponding to
|
|
@type. The returned string is nul-terminated. It is appropriate to
|
|
call g_free() on the return value.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the corresponding type string
|
|
|
|
Since 2.24</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="element" c:identifier="g_variant_type_element">
|
|
<doc xml:space="preserve">Determines the element type of an array or maybe type.
|
|
|
|
This function may only be used with array or maybe types.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the element type of @type
|
|
|
|
Since 2.24</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">an array or maybe #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="equal" c:identifier="g_variant_type_equal">
|
|
<doc xml:space="preserve">Compares @type1 and @type2 for equality.
|
|
|
|
Only returns %TRUE if the types are exactly equal. Even if one type
|
|
is an indefinite type and the other is a subtype of it, %FALSE will
|
|
be returned if they are not exactly equal. If you want to check for
|
|
subtypes, use g_variant_type_is_subtype_of().
|
|
|
|
The argument types of @type1 and @type2 are only #gconstpointer to
|
|
allow use with #GHashTable without function pointer casting. For
|
|
both arguments, a valid #GVariantType must be provided.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @type1 and @type2 are exactly equal
|
|
|
|
Since 2.24</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="gconstpointer"/>
|
|
</instance-parameter>
|
|
<parameter name="type2" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="first" c:identifier="g_variant_type_first">
|
|
<doc xml:space="preserve">Determines the first item type of a tuple or dictionary entry
|
|
type.
|
|
|
|
This function may only be used with tuple or dictionary entry types,
|
|
but must not be used with the generic tuple type
|
|
%G_VARIANT_TYPE_TUPLE.
|
|
|
|
In the case of a dictionary entry type, this returns the type of
|
|
the key.
|
|
|
|
%NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT.
|
|
|
|
This call, together with g_variant_type_next() provides an iterator
|
|
interface over tuple and dictionary entry types.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the first item type of @type, or %NULL
|
|
|
|
Since 2.24</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a tuple or dictionary entry #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="free" c:identifier="g_variant_type_free">
|
|
<doc xml:space="preserve">Frees a #GVariantType that was allocated with
|
|
g_variant_type_copy(), g_variant_type_new() or one of the container
|
|
type constructor functions.
|
|
|
|
In the case that @type is %NULL, this function does nothing.
|
|
|
|
Since 2.24</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GVariantType, or %NULL</doc>
|
|
<type name="VariantType" c:type="GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="get_string_length" c:identifier="g_variant_type_get_string_length">
|
|
<doc xml:space="preserve">Returns the length of the type string corresponding to the given
|
|
@type. This function must be used to determine the valid extent of
|
|
the memory region returned by g_variant_type_peek_string().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the corresponding type string
|
|
|
|
Since 2.24</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="hash" c:identifier="g_variant_type_hash">
|
|
<doc xml:space="preserve">Hashes @type.
|
|
|
|
The argument type of @type is only #gconstpointer to allow use with
|
|
#GHashTable without function pointer casting. A valid
|
|
#GVariantType must be provided.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the hash value
|
|
|
|
Since 2.24</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="gconstpointer"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_array" c:identifier="g_variant_type_is_array">
|
|
<doc xml:space="preserve">Determines if the given @type is an array type. This is true if the
|
|
type string for @type starts with an 'a'.
|
|
|
|
This function returns %TRUE for any indefinite type for which every
|
|
definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for
|
|
example.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @type is an array type
|
|
|
|
Since 2.24</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_basic" c:identifier="g_variant_type_is_basic">
|
|
<doc xml:space="preserve">Determines if the given @type is a basic type.
|
|
|
|
Basic types are booleans, bytes, integers, doubles, strings, object
|
|
paths and signatures.
|
|
|
|
Only a basic type may be used as the key of a dictionary entry.
|
|
|
|
This function returns %FALSE for all indefinite types except
|
|
%G_VARIANT_TYPE_BASIC.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @type is a basic type
|
|
|
|
Since 2.24</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_container" c:identifier="g_variant_type_is_container">
|
|
<doc xml:space="preserve">Determines if the given @type is a container type.
|
|
|
|
Container types are any array, maybe, tuple, or dictionary
|
|
entry types plus the variant type.
|
|
|
|
This function returns %TRUE for any indefinite type for which every
|
|
definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for
|
|
example.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @type is a container type
|
|
|
|
Since 2.24</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_definite" c:identifier="g_variant_type_is_definite">
|
|
<doc xml:space="preserve">Determines if the given @type is definite (ie: not indefinite).
|
|
|
|
A type is definite if its type string does not contain any indefinite
|
|
type characters ('*', '?', or 'r').
|
|
|
|
A #GVariant instance may not have an indefinite type, so calling
|
|
this function on the result of g_variant_get_type() will always
|
|
result in %TRUE being returned. Calling this function on an
|
|
indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in
|
|
%FALSE being returned.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @type is definite
|
|
|
|
Since 2.24</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_dict_entry" c:identifier="g_variant_type_is_dict_entry">
|
|
<doc xml:space="preserve">Determines if the given @type is a dictionary entry type. This is
|
|
true if the type string for @type starts with a '{'.
|
|
|
|
This function returns %TRUE for any indefinite type for which every
|
|
definite subtype is a dictionary entry type --
|
|
%G_VARIANT_TYPE_DICT_ENTRY, for example.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @type is a dictionary entry type
|
|
|
|
Since 2.24</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_maybe" c:identifier="g_variant_type_is_maybe">
|
|
<doc xml:space="preserve">Determines if the given @type is a maybe type. This is true if the
|
|
type string for @type starts with an 'm'.
|
|
|
|
This function returns %TRUE for any indefinite type for which every
|
|
definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for
|
|
example.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @type is a maybe type
|
|
|
|
Since 2.24</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_subtype_of" c:identifier="g_variant_type_is_subtype_of">
|
|
<doc xml:space="preserve">Checks if @type is a subtype of @supertype.
|
|
|
|
This function returns %TRUE if @type is a subtype of @supertype. All
|
|
types are considered to be subtypes of themselves. Aside from that,
|
|
only indefinite types can have subtypes.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @type is a subtype of @supertype
|
|
|
|
Since 2.24</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
<parameter name="supertype" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_tuple" c:identifier="g_variant_type_is_tuple">
|
|
<doc xml:space="preserve">Determines if the given @type is a tuple type. This is true if the
|
|
type string for @type starts with a '(' or if @type is
|
|
%G_VARIANT_TYPE_TUPLE.
|
|
|
|
This function returns %TRUE for any indefinite type for which every
|
|
definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for
|
|
example.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @type is a tuple type
|
|
|
|
Since 2.24</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="is_variant" c:identifier="g_variant_type_is_variant">
|
|
<doc xml:space="preserve">Determines if the given @type is the variant type.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @type is the variant type
|
|
|
|
Since 2.24</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="key" c:identifier="g_variant_type_key">
|
|
<doc xml:space="preserve">Determines the key type of a dictionary entry type.
|
|
|
|
This function may only be used with a dictionary entry type. Other
|
|
than the additional restriction, this call is equivalent to
|
|
g_variant_type_first().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the key type of the dictionary entry
|
|
|
|
Since 2.24</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a dictionary entry #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="n_items" c:identifier="g_variant_type_n_items">
|
|
<doc xml:space="preserve">Determines the number of items contained in a tuple or
|
|
dictionary entry type.
|
|
|
|
This function may only be used with tuple or dictionary entry types,
|
|
but must not be used with the generic tuple type
|
|
%G_VARIANT_TYPE_TUPLE.
|
|
|
|
In the case of a dictionary entry type, this function will always
|
|
return 2.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of items in @type
|
|
|
|
Since 2.24</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a tuple or dictionary entry #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="next" c:identifier="g_variant_type_next">
|
|
<doc xml:space="preserve">Determines the next item type of a tuple or dictionary entry
|
|
type.
|
|
|
|
@type must be the result of a previous call to
|
|
g_variant_type_first() or g_variant_type_next().
|
|
|
|
If called on the key type of a dictionary entry then this call
|
|
returns the value type. If called on the value type of a dictionary
|
|
entry then this call returns %NULL.
|
|
|
|
For tuples, %NULL is returned when @type is the last item in a tuple.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the next #GVariantType after @type, or %NULL
|
|
|
|
Since 2.24</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType from a previous call</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="peek_string" c:identifier="g_variant_type_peek_string" introspectable="0">
|
|
<doc xml:space="preserve">Returns the type string corresponding to the given @type. The
|
|
result is not nul-terminated; in order to determine its length you
|
|
must call g_variant_type_get_string_length().
|
|
|
|
To get a nul-terminated string, see g_variant_type_dup_string().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the corresponding type string (not nul-terminated)
|
|
|
|
Since 2.24</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="value" c:identifier="g_variant_type_value">
|
|
<doc xml:space="preserve">Determines the value type of a dictionary entry type.
|
|
|
|
This function may only be used with a dictionary entry type.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the value type of the dictionary entry
|
|
|
|
Since 2.24</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a dictionary entry #GVariantType</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="checked_" c:identifier="g_variant_type_checked_">
|
|
<return-value transfer-ownership="none">
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="arg0" transfer-ownership="none">
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="string_get_depth_" c:identifier="g_variant_type_string_get_depth_">
|
|
<return-value transfer-ownership="none">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="type_string" transfer-ownership="none">
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="string_is_valid" c:identifier="g_variant_type_string_is_valid">
|
|
<doc xml:space="preserve">Checks if @type_string is a valid GVariant type string. This call is
|
|
equivalent to calling g_variant_type_string_scan() and confirming
|
|
that the following character is a nul terminator.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @type_string is exactly one valid type string
|
|
|
|
Since 2.24</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="type_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to any string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="string_scan" c:identifier="g_variant_type_string_scan" version="2.24">
|
|
<doc xml:space="preserve">Scan for a single complete and valid GVariant type string in @string.
|
|
The memory pointed to by @limit (or bytes beyond it) is never
|
|
accessed.
|
|
|
|
If a valid type string is found, @endptr is updated to point to the
|
|
first character past the end of the string that was found and %TRUE
|
|
is returned.
|
|
|
|
If there is no valid type string starting at @string, or if the type
|
|
string does not end before @limit then %FALSE is returned.
|
|
|
|
For the simple case of checking if a string is a valid type string,
|
|
see g_variant_type_string_is_valid().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a valid type string was found</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to any string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="limit" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the end of @string, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="endptr" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store the end pointer, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
</record>
|
|
<callback name="VoidFunc" c:type="GVoidFunc">
|
|
<doc xml:space="preserve">Declares a type of function which takes no arguments
|
|
and has no return value. It is used to specify the type
|
|
function passed to g_atexit().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
</callback>
|
|
<function-macro name="WIN32_DLLMAIN_FOR_DLL_NAME" c:identifier="G_WIN32_DLLMAIN_FOR_DLL_NAME" introspectable="0">
|
|
<doc xml:space="preserve">On Windows, this macro defines a DllMain() function that stores
|
|
the actual DLL name that the code being compiled will be included in.
|
|
|
|
On non-Windows platforms, expands to nothing.</doc>
|
|
<parameters>
|
|
<parameter name="static">
|
|
<doc xml:space="preserve">empty or "static"</doc>
|
|
</parameter>
|
|
<parameter name="dll_name">
|
|
<doc xml:space="preserve">the name of the (pointer to the) char array where
|
|
the DLL name will be stored. If this is used, you must also
|
|
include `windows.h`. If you need a more complex DLL entry
|
|
point function, you cannot use this</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<constant name="WIN32_MSG_HANDLE" value="19981206" c:type="G_WIN32_MSG_HANDLE">
|
|
<type name="gint" c:type="gint"/>
|
|
</constant>
|
|
<function name="access" c:identifier="g_access" version="2.8">
|
|
<doc xml:space="preserve">A wrapper for the POSIX access() function. This function is used to
|
|
test a pathname for one or several of read, write or execute
|
|
permissions, or just existence.
|
|
|
|
On Windows, the file protection mechanism is not at all POSIX-like,
|
|
and the underlying function in the C library only checks the
|
|
FAT-style READONLY attribute, and does not look at the ACL of a
|
|
file at all. This function is this in practise almost useless on
|
|
Windows. Software that needs to handle file permissions on Windows
|
|
more exactly should use the Win32 API.
|
|
|
|
See your C library manual for more details about access().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">zero if the pathname refers to an existing file system
|
|
object that has all the tested permissions, or -1 otherwise
|
|
or on error.</doc>
|
|
<type name="gint" c:type="int"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="filename" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pathname in the GLib file name encoding
|
|
(UTF-8 on Windows)</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="mode" transfer-ownership="none">
|
|
<doc xml:space="preserve">as in access()</doc>
|
|
<type name="gint" c:type="int"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="alloca" c:identifier="g_alloca" introspectable="0">
|
|
<doc xml:space="preserve">Allocates @size bytes on the stack; these bytes will be freed when the current
|
|
stack frame is cleaned up. This macro essentially just wraps the alloca()
|
|
function present on most UNIX variants.
|
|
Thus it provides the same advantages and pitfalls as alloca():
|
|
|
|
- alloca() is very fast, as on most systems it's implemented by just adjusting
|
|
the stack pointer register.
|
|
|
|
- It doesn't cause any memory fragmentation, within its scope, separate alloca()
|
|
blocks just build up and are released together at function end.
|
|
|
|
- Allocation sizes have to fit into the current stack frame. For instance in a
|
|
threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
|
|
so be sparse with alloca() uses.
|
|
|
|
- Allocation failure due to insufficient stack space is not indicated with a %NULL
|
|
return like e.g. with malloc(). Instead, most systems probably handle it the same
|
|
way as out of stack space situations from infinite function recursion, i.e.
|
|
with a segmentation fault.
|
|
|
|
- Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
|
|
Stack space allocated with alloca() in the same scope as a variable sized array
|
|
will be freed together with the variable sized array upon exit of that scope, and
|
|
not upon exit of the enclosing function scope.</doc>
|
|
<parameters>
|
|
<parameter name="size">
|
|
<doc xml:space="preserve">number of bytes to allocate.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<docsection name="arcbox">
|
|
<doc xml:space="preserve">An "atomically reference counted box", or "ArcBox", is an opaque wrapper
|
|
data type that is guaranteed to be as big as the size of a given data type,
|
|
and which augments the given data type with thread safe reference counting
|
|
semantics for its memory management.
|
|
|
|
ArcBox is useful if you have a plain old data type, like a structure
|
|
typically placed on the stack, and you wish to provide additional API
|
|
to use it on the heap; or if you want to implement a new type to be
|
|
passed around by reference without necessarily implementing copy/free
|
|
semantics or your own reference counting.
|
|
|
|
The typical use is:
|
|
|
|
|[<!-- language="C" -->
|
|
typedef struct {
|
|
char *name;
|
|
char *address;
|
|
char *city;
|
|
char *state;
|
|
int age;
|
|
} Person;
|
|
|
|
Person *
|
|
person_new (void)
|
|
{
|
|
return g_atomic_rc_box_new0 (Person);
|
|
}
|
|
]|
|
|
|
|
Every time you wish to acquire a reference on the memory, you should
|
|
call g_atomic_rc_box_acquire(); similarly, when you wish to release a reference
|
|
you should call g_atomic_rc_box_release():
|
|
|
|
|[<!-- language="C" -->
|
|
// Add a Person to the Database; the Database acquires ownership
|
|
// of the Person instance
|
|
void
|
|
add_person_to_database (Database *db, Person *p)
|
|
{
|
|
db->persons = g_list_prepend (db->persons, g_atomic_rc_box_acquire (p));
|
|
}
|
|
|
|
// Removes a Person from the Database; the reference acquired by
|
|
// add_person_to_database() is released here
|
|
void
|
|
remove_person_from_database (Database *db, Person *p)
|
|
{
|
|
db->persons = g_list_remove (db->persons, p);
|
|
g_atomic_rc_box_release (p);
|
|
}
|
|
]|
|
|
|
|
If you have additional memory allocated inside the structure, you can
|
|
use g_atomic_rc_box_release_full(), which takes a function pointer, which
|
|
will be called if the reference released was the last:
|
|
|
|
|[<!-- language="C" -->
|
|
void
|
|
person_clear (Person *p)
|
|
{
|
|
g_free (p->name);
|
|
g_free (p->address);
|
|
g_free (p->city);
|
|
g_free (p->state);
|
|
}
|
|
|
|
void
|
|
remove_person_from_database (Database *db, Person *p)
|
|
{
|
|
db->persons = g_list_remove (db->persons, p);
|
|
g_atomic_rc_box_release_full (p, (GDestroyNotify) person_clear);
|
|
}
|
|
]|
|
|
|
|
If you wish to transfer the ownership of a reference counted data
|
|
type without increasing the reference count, you can use g_steal_pointer():
|
|
|
|
|[<!-- language="C" -->
|
|
Person *p = g_atomic_rc_box_new (Person);
|
|
|
|
fill_person_details (p);
|
|
|
|
add_person_to_database (db, g_steal_pointer (&p));
|
|
]|
|
|
|
|
## Thread safety
|
|
|
|
The reference counting operations on data allocated using g_atomic_rc_box_alloc(),
|
|
g_atomic_rc_box_new(), and g_atomic_rc_box_dup() are guaranteed to be atomic, and thus
|
|
can be safely be performed by different threads. It is important to note that
|
|
only the reference acquisition and release are atomic; changes to the content
|
|
of the data are your responsibility.
|
|
|
|
## Automatic pointer clean up
|
|
|
|
If you want to add g_autoptr() support to your plain old data type through
|
|
reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and
|
|
g_atomic_rc_box_release():
|
|
|
|
|[<!-- language="C" -->
|
|
G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_atomic_rc_box_release)
|
|
]|
|
|
|
|
If you need to clear the contents of the data, you will need to use an
|
|
ancillary function that calls g_rc_box_release_full():
|
|
|
|
|[<!-- language="C" -->
|
|
static void
|
|
my_data_struct_release (MyDataStruct *data)
|
|
{
|
|
// my_data_struct_clear() is defined elsewhere
|
|
g_atomic_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear);
|
|
}
|
|
|
|
G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_release)
|
|
]|</doc>
|
|
</docsection>
|
|
<function-macro name="array_append_val" c:identifier="g_array_append_val" introspectable="0">
|
|
<doc xml:space="preserve">Adds the value on to the end of the array. The array will grow in
|
|
size automatically if necessary.
|
|
|
|
g_array_append_val() is a macro which uses a reference to the value
|
|
parameter @v. This means that you cannot use it with literal values
|
|
such as "27". You must use variables.</doc>
|
|
<parameters>
|
|
<parameter name="a">
|
|
<doc xml:space="preserve">a #GArray</doc>
|
|
</parameter>
|
|
<parameter name="v">
|
|
<doc xml:space="preserve">the value to append to the #GArray</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="array_index" c:identifier="g_array_index" introspectable="0">
|
|
<doc xml:space="preserve">Returns the element of a #GArray at the given index. The return
|
|
value is cast to the given type. This is the main way to read or write an
|
|
element in a #GArray.
|
|
|
|
Writing an element is typically done by reference, as in the following
|
|
example. This example gets a pointer to an element in a #GArray, and then
|
|
writes to a field in it:
|
|
|[<!-- language="C" -->
|
|
EDayViewEvent *event;
|
|
// This gets a pointer to the 4th element in the array of
|
|
// EDayViewEvent structs.
|
|
event = &g_array_index (events, EDayViewEvent, 3);
|
|
event->start_time = g_get_current_time ();
|
|
]|
|
|
|
|
This example reads from and writes to an array of integers:
|
|
|[<!-- language="C" -->
|
|
g_autoptr(GArray) int_array = g_array_new (FALSE, FALSE, sizeof (guint));
|
|
for (guint i = 0; i < 10; i++)
|
|
g_array_append_val (int_array, i);
|
|
|
|
guint *my_int = &g_array_index (int_array, guint, 1);
|
|
g_print ("Int at index 1 is %u; decrementing it\n", *my_int);
|
|
*my_int = *my_int - 1;
|
|
]|</doc>
|
|
<parameters>
|
|
<parameter name="a">
|
|
<doc xml:space="preserve">a #GArray</doc>
|
|
</parameter>
|
|
<parameter name="t">
|
|
<doc xml:space="preserve">the type of the elements</doc>
|
|
</parameter>
|
|
<parameter name="i">
|
|
<doc xml:space="preserve">the index of the element to return</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="array_insert_val" c:identifier="g_array_insert_val" introspectable="0">
|
|
<doc xml:space="preserve">Inserts an element into an array at the given index.
|
|
|
|
g_array_insert_val() is a macro which uses a reference to the value
|
|
parameter @v. This means that you cannot use it with literal values
|
|
such as "27". You must use variables.</doc>
|
|
<parameters>
|
|
<parameter name="a">
|
|
<doc xml:space="preserve">a #GArray</doc>
|
|
</parameter>
|
|
<parameter name="i">
|
|
<doc xml:space="preserve">the index to place the element at</doc>
|
|
</parameter>
|
|
<parameter name="v">
|
|
<doc xml:space="preserve">the value to insert into the array</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="array_prepend_val" c:identifier="g_array_prepend_val" introspectable="0">
|
|
<doc xml:space="preserve">Adds the value on to the start of the array. The array will grow in
|
|
size automatically if necessary.
|
|
|
|
This operation is slower than g_array_append_val() since the
|
|
existing elements in the array have to be moved to make space for
|
|
the new element.
|
|
|
|
g_array_prepend_val() is a macro which uses a reference to the value
|
|
parameter @v. This means that you cannot use it with literal values
|
|
such as "27". You must use variables.</doc>
|
|
<parameters>
|
|
<parameter name="a">
|
|
<doc xml:space="preserve">a #GArray</doc>
|
|
</parameter>
|
|
<parameter name="v">
|
|
<doc xml:space="preserve">the value to prepend to the #GArray</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<docsection name="arrays">
|
|
<doc xml:space="preserve">Arrays are similar to standard C arrays, except that they grow
|
|
automatically as elements are added.
|
|
|
|
Array elements can be of any size (though all elements of one array
|
|
are the same size), and the array can be automatically cleared to
|
|
'0's and zero-terminated.
|
|
|
|
To create a new array use g_array_new().
|
|
|
|
To add elements to an array with a cost of O(n) at worst, use
|
|
g_array_append_val(), g_array_append_vals(), g_array_prepend_val(),
|
|
g_array_prepend_vals(), g_array_insert_val() and g_array_insert_vals().
|
|
|
|
To access an element of an array in O(1) (to read it or to write it),
|
|
use g_array_index().
|
|
|
|
To set the size of an array, use g_array_set_size().
|
|
|
|
To free an array, use g_array_unref() or g_array_free().
|
|
|
|
All the sort functions are internally calling a quick-sort (or similar)
|
|
function with an average cost of O(n log(n)) and a worst case
|
|
cost of O(n^2).
|
|
|
|
Here is an example that stores integers in a #GArray:
|
|
|[<!-- language="C" -->
|
|
GArray *garray;
|
|
gint i;
|
|
// We create a new array to store gint values.
|
|
// We don't want it zero-terminated or cleared to 0's.
|
|
garray = g_array_new (FALSE, FALSE, sizeof (gint));
|
|
for (i = 0; i < 10000; i++)
|
|
g_array_append_val (garray, i);
|
|
for (i = 0; i < 10000; i++)
|
|
if (g_array_index (garray, gint, i) != i)
|
|
g_print ("ERROR: got %d instead of %d\n",
|
|
g_array_index (garray, gint, i), i);
|
|
g_array_free (garray, TRUE);
|
|
]|</doc>
|
|
</docsection>
|
|
<docsection name="arrays_byte">
|
|
<doc xml:space="preserve">#GByteArray is a mutable array of bytes based on #GArray, to provide arrays
|
|
of bytes which grow automatically as elements are added.
|
|
|
|
To create a new #GByteArray use g_byte_array_new(). To add elements to a
|
|
#GByteArray, use g_byte_array_append(), and g_byte_array_prepend().
|
|
|
|
To set the size of a #GByteArray, use g_byte_array_set_size().
|
|
|
|
To free a #GByteArray, use g_byte_array_free().
|
|
|
|
An example for using a #GByteArray:
|
|
|[<!-- language="C" -->
|
|
GByteArray *gbarray;
|
|
gint i;
|
|
|
|
gbarray = g_byte_array_new ();
|
|
for (i = 0; i < 10000; i++)
|
|
g_byte_array_append (gbarray, (guint8*) "abcd", 4);
|
|
|
|
for (i = 0; i < 10000; i++)
|
|
{
|
|
g_assert (gbarray->data[4*i] == 'a');
|
|
g_assert (gbarray->data[4*i+1] == 'b');
|
|
g_assert (gbarray->data[4*i+2] == 'c');
|
|
g_assert (gbarray->data[4*i+3] == 'd');
|
|
}
|
|
|
|
g_byte_array_free (gbarray, TRUE);
|
|
]|
|
|
|
|
See #GBytes if you are interested in an immutable object representing a
|
|
sequence of bytes.</doc>
|
|
</docsection>
|
|
<docsection name="arrays_pointer">
|
|
<doc xml:space="preserve">Pointer Arrays are similar to Arrays but are used only for storing
|
|
pointers.
|
|
|
|
If you remove elements from the array, elements at the end of the
|
|
array are moved into the space previously occupied by the removed
|
|
element. This means that you should not rely on the index of particular
|
|
elements remaining the same. You should also be careful when deleting
|
|
elements while iterating over the array.
|
|
|
|
To create a pointer array, use g_ptr_array_new().
|
|
|
|
To add elements to a pointer array, use g_ptr_array_add().
|
|
|
|
To remove elements from a pointer array, use g_ptr_array_remove(),
|
|
g_ptr_array_remove_index() or g_ptr_array_remove_index_fast().
|
|
|
|
To access an element of a pointer array, use g_ptr_array_index().
|
|
|
|
To set the size of a pointer array, use g_ptr_array_set_size().
|
|
|
|
To free a pointer array, use g_ptr_array_free().
|
|
|
|
An example using a #GPtrArray:
|
|
|[<!-- language="C" -->
|
|
GPtrArray *array;
|
|
gchar *string1 = "one";
|
|
gchar *string2 = "two";
|
|
gchar *string3 = "three";
|
|
|
|
array = g_ptr_array_new ();
|
|
g_ptr_array_add (array, (gpointer) string1);
|
|
g_ptr_array_add (array, (gpointer) string2);
|
|
g_ptr_array_add (array, (gpointer) string3);
|
|
|
|
if (g_ptr_array_index (array, 0) != (gpointer) string1)
|
|
g_print ("ERROR: got %p instead of %p\n",
|
|
g_ptr_array_index (array, 0), string1);
|
|
|
|
g_ptr_array_free (array, TRUE);
|
|
]|</doc>
|
|
</docsection>
|
|
<function name="ascii_digit_value" c:identifier="g_ascii_digit_value">
|
|
<doc xml:space="preserve">Determines the numeric value of a character as a decimal digit.
|
|
Differs from g_unichar_digit_value() because it takes a char, so
|
|
there's no worry about sign extension if characters are signed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">If @c is a decimal digit (according to g_ascii_isdigit()),
|
|
its numeric value. Otherwise, -1.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">an ASCII character</doc>
|
|
<type name="gchar" c:type="gchar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ascii_dtostr" c:identifier="g_ascii_dtostr">
|
|
<doc xml:space="preserve">Converts a #gdouble to a string, using the '.' as
|
|
decimal point.
|
|
|
|
This function generates enough precision that converting
|
|
the string back using g_ascii_strtod() gives the same machine-number
|
|
(on machines with IEEE compatible 64bit doubles). It is
|
|
guaranteed that the size of the resulting string will never
|
|
be larger than @G_ASCII_DTOSTR_BUF_SIZE bytes, including the terminating
|
|
nul character, which is always added.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">The pointer to the buffer with the converted string.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="buffer" transfer-ownership="none">
|
|
<doc xml:space="preserve">A buffer to place the resulting string in</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="buf_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">The length of the buffer.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="d" transfer-ownership="none">
|
|
<doc xml:space="preserve">The #gdouble to convert</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ascii_formatd" c:identifier="g_ascii_formatd">
|
|
<doc xml:space="preserve">Converts a #gdouble to a string, using the '.' as
|
|
decimal point. To format the number you pass in
|
|
a printf()-style format string. Allowed conversion
|
|
specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.
|
|
|
|
The returned buffer is guaranteed to be nul-terminated.
|
|
|
|
If you just want to want to serialize the value into a
|
|
string, use g_ascii_dtostr().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">The pointer to the buffer with the converted string.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="buffer" transfer-ownership="none">
|
|
<doc xml:space="preserve">A buffer to place the resulting string in</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="buf_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">The length of the buffer.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">The printf()-style format to use for the
|
|
code to use for converting.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="d" transfer-ownership="none">
|
|
<doc xml:space="preserve">The #gdouble to convert</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="ascii_isalnum" c:identifier="g_ascii_isalnum" introspectable="0">
|
|
<doc xml:space="preserve">Determines whether a character is alphanumeric.
|
|
|
|
Unlike the standard C library isalnum() function, this only
|
|
recognizes standard ASCII letters and ignores the locale,
|
|
returning %FALSE for all non-ASCII characters. Also, unlike
|
|
the standard library function, this takes a char, not an int,
|
|
so don't call it on %EOF, but no need to cast to #guchar before
|
|
passing a possibly non-ASCII character in.</doc>
|
|
<parameters>
|
|
<parameter name="c">
|
|
<doc xml:space="preserve">any character</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="ascii_isalpha" c:identifier="g_ascii_isalpha" introspectable="0">
|
|
<doc xml:space="preserve">Determines whether a character is alphabetic (i.e. a letter).
|
|
|
|
Unlike the standard C library isalpha() function, this only
|
|
recognizes standard ASCII letters and ignores the locale,
|
|
returning %FALSE for all non-ASCII characters. Also, unlike
|
|
the standard library function, this takes a char, not an int,
|
|
so don't call it on %EOF, but no need to cast to #guchar before
|
|
passing a possibly non-ASCII character in.</doc>
|
|
<parameters>
|
|
<parameter name="c">
|
|
<doc xml:space="preserve">any character</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="ascii_iscntrl" c:identifier="g_ascii_iscntrl" introspectable="0">
|
|
<doc xml:space="preserve">Determines whether a character is a control character.
|
|
|
|
Unlike the standard C library iscntrl() function, this only
|
|
recognizes standard ASCII control characters and ignores the
|
|
locale, returning %FALSE for all non-ASCII characters. Also,
|
|
unlike the standard library function, this takes a char, not
|
|
an int, so don't call it on %EOF, but no need to cast to #guchar
|
|
before passing a possibly non-ASCII character in.</doc>
|
|
<parameters>
|
|
<parameter name="c">
|
|
<doc xml:space="preserve">any character</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="ascii_isdigit" c:identifier="g_ascii_isdigit" introspectable="0">
|
|
<doc xml:space="preserve">Determines whether a character is digit (0-9).
|
|
|
|
Unlike the standard C library isdigit() function, this takes
|
|
a char, not an int, so don't call it on %EOF, but no need to
|
|
cast to #guchar before passing a possibly non-ASCII character in.</doc>
|
|
<parameters>
|
|
<parameter name="c">
|
|
<doc xml:space="preserve">any character</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="ascii_isgraph" c:identifier="g_ascii_isgraph" introspectable="0">
|
|
<doc xml:space="preserve">Determines whether a character is a printing character and not a space.
|
|
|
|
Unlike the standard C library isgraph() function, this only
|
|
recognizes standard ASCII characters and ignores the locale,
|
|
returning %FALSE for all non-ASCII characters. Also, unlike
|
|
the standard library function, this takes a char, not an int,
|
|
so don't call it on %EOF, but no need to cast to #guchar before
|
|
passing a possibly non-ASCII character in.</doc>
|
|
<parameters>
|
|
<parameter name="c">
|
|
<doc xml:space="preserve">any character</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="ascii_islower" c:identifier="g_ascii_islower" introspectable="0">
|
|
<doc xml:space="preserve">Determines whether a character is an ASCII lower case letter.
|
|
|
|
Unlike the standard C library islower() function, this only
|
|
recognizes standard ASCII letters and ignores the locale,
|
|
returning %FALSE for all non-ASCII characters. Also, unlike
|
|
the standard library function, this takes a char, not an int,
|
|
so don't call it on %EOF, but no need to worry about casting
|
|
to #guchar before passing a possibly non-ASCII character in.</doc>
|
|
<parameters>
|
|
<parameter name="c">
|
|
<doc xml:space="preserve">any character</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="ascii_isprint" c:identifier="g_ascii_isprint" introspectable="0">
|
|
<doc xml:space="preserve">Determines whether a character is a printing character.
|
|
|
|
Unlike the standard C library isprint() function, this only
|
|
recognizes standard ASCII characters and ignores the locale,
|
|
returning %FALSE for all non-ASCII characters. Also, unlike
|
|
the standard library function, this takes a char, not an int,
|
|
so don't call it on %EOF, but no need to cast to #guchar before
|
|
passing a possibly non-ASCII character in.</doc>
|
|
<parameters>
|
|
<parameter name="c">
|
|
<doc xml:space="preserve">any character</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="ascii_ispunct" c:identifier="g_ascii_ispunct" introspectable="0">
|
|
<doc xml:space="preserve">Determines whether a character is a punctuation character.
|
|
|
|
Unlike the standard C library ispunct() function, this only
|
|
recognizes standard ASCII letters and ignores the locale,
|
|
returning %FALSE for all non-ASCII characters. Also, unlike
|
|
the standard library function, this takes a char, not an int,
|
|
so don't call it on %EOF, but no need to cast to #guchar before
|
|
passing a possibly non-ASCII character in.</doc>
|
|
<parameters>
|
|
<parameter name="c">
|
|
<doc xml:space="preserve">any character</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="ascii_isspace" c:identifier="g_ascii_isspace" introspectable="0">
|
|
<doc xml:space="preserve">Determines whether a character is a white-space character.
|
|
|
|
Unlike the standard C library isspace() function, this only
|
|
recognizes standard ASCII white-space and ignores the locale,
|
|
returning %FALSE for all non-ASCII characters. Also, unlike
|
|
the standard library function, this takes a char, not an int,
|
|
so don't call it on %EOF, but no need to cast to #guchar before
|
|
passing a possibly non-ASCII character in.</doc>
|
|
<parameters>
|
|
<parameter name="c">
|
|
<doc xml:space="preserve">any character</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="ascii_isupper" c:identifier="g_ascii_isupper" introspectable="0">
|
|
<doc xml:space="preserve">Determines whether a character is an ASCII upper case letter.
|
|
|
|
Unlike the standard C library isupper() function, this only
|
|
recognizes standard ASCII letters and ignores the locale,
|
|
returning %FALSE for all non-ASCII characters. Also, unlike
|
|
the standard library function, this takes a char, not an int,
|
|
so don't call it on %EOF, but no need to worry about casting
|
|
to #guchar before passing a possibly non-ASCII character in.</doc>
|
|
<parameters>
|
|
<parameter name="c">
|
|
<doc xml:space="preserve">any character</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="ascii_isxdigit" c:identifier="g_ascii_isxdigit" introspectable="0">
|
|
<doc xml:space="preserve">Determines whether a character is a hexadecimal-digit character.
|
|
|
|
Unlike the standard C library isxdigit() function, this takes
|
|
a char, not an int, so don't call it on %EOF, but no need to
|
|
cast to #guchar before passing a possibly non-ASCII character in.</doc>
|
|
<parameters>
|
|
<parameter name="c">
|
|
<doc xml:space="preserve">any character</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="ascii_strcasecmp" c:identifier="g_ascii_strcasecmp">
|
|
<doc xml:space="preserve">Compare two strings, ignoring the case of ASCII characters.
|
|
|
|
Unlike the BSD strcasecmp() function, this only recognizes standard
|
|
ASCII letters and ignores the locale, treating all non-ASCII
|
|
bytes as if they are not letters.
|
|
|
|
This function should be used only on strings that are known to be
|
|
in encodings where the bytes corresponding to ASCII letters always
|
|
represent themselves. This includes UTF-8 and the ISO-8859-*
|
|
charsets, but not for instance double-byte encodings like the
|
|
Windows Codepage 932, where the trailing bytes of double-byte
|
|
characters include all ASCII letters. If you compare two CP932
|
|
strings using this function, you will get false matches.
|
|
|
|
Both @s1 and @s2 must be non-%NULL.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">0 if the strings match, a negative value if @s1 < @s2,
|
|
or a positive value if @s1 > @s2.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="s1" transfer-ownership="none">
|
|
<doc xml:space="preserve">string to compare with @s2</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="s2" transfer-ownership="none">
|
|
<doc xml:space="preserve">string to compare with @s1</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ascii_strdown" c:identifier="g_ascii_strdown">
|
|
<doc xml:space="preserve">Converts all upper case ASCII letters to lower case ASCII letters.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated string, with all the upper case
|
|
characters in @str converted to lower case, with semantics that
|
|
exactly match g_ascii_tolower(). (Note that this is unlike the
|
|
old g_strdown(), which modified the string in place.)</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @str in bytes, or -1 if @str is nul-terminated</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ascii_string_to_signed" c:identifier="g_ascii_string_to_signed" version="2.54" throws="1">
|
|
<doc xml:space="preserve">A convenience function for converting a string to a signed number.
|
|
|
|
This function assumes that @str contains only a number of the given
|
|
@base that is within inclusive bounds limited by @min and @max. If
|
|
this is true, then the converted number is stored in @out_num. An
|
|
empty string is not a valid input. A string with leading or
|
|
trailing whitespace is also an invalid input.
|
|
|
|
@base can be between 2 and 36 inclusive. Hexadecimal numbers must
|
|
not be prefixed with "0x" or "0X". Such a problem does not exist
|
|
for octal numbers, since they were usually prefixed with a zero
|
|
which does not change the value of the parsed number.
|
|
|
|
Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR
|
|
domain. If the input is invalid, the error code will be
|
|
%G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of
|
|
bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS.
|
|
|
|
See g_ascii_strtoll() if you have more complex needs such as
|
|
parsing a string which starts with a number, but then has other
|
|
characters.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @str was a number, otherwise %FALSE.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="base" transfer-ownership="none">
|
|
<doc xml:space="preserve">base of a parsed number</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="min" transfer-ownership="none">
|
|
<doc xml:space="preserve">a lower bound (inclusive)</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</parameter>
|
|
<parameter name="max" transfer-ownership="none">
|
|
<doc xml:space="preserve">an upper bound (inclusive)</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</parameter>
|
|
<parameter name="out_num" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">a return location for a number</doc>
|
|
<type name="gint64" c:type="gint64*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ascii_string_to_unsigned" c:identifier="g_ascii_string_to_unsigned" version="2.54" throws="1">
|
|
<doc xml:space="preserve">A convenience function for converting a string to an unsigned number.
|
|
|
|
This function assumes that @str contains only a number of the given
|
|
@base that is within inclusive bounds limited by @min and @max. If
|
|
this is true, then the converted number is stored in @out_num. An
|
|
empty string is not a valid input. A string with leading or
|
|
trailing whitespace is also an invalid input. A string with a leading sign
|
|
(`-` or `+`) is not a valid input for the unsigned parser.
|
|
|
|
@base can be between 2 and 36 inclusive. Hexadecimal numbers must
|
|
not be prefixed with "0x" or "0X". Such a problem does not exist
|
|
for octal numbers, since they were usually prefixed with a zero
|
|
which does not change the value of the parsed number.
|
|
|
|
Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR
|
|
domain. If the input is invalid, the error code will be
|
|
%G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of
|
|
bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS.
|
|
|
|
See g_ascii_strtoull() if you have more complex needs such as
|
|
parsing a string which starts with a number, but then has other
|
|
characters.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @str was a number, otherwise %FALSE.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="base" transfer-ownership="none">
|
|
<doc xml:space="preserve">base of a parsed number</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="min" transfer-ownership="none">
|
|
<doc xml:space="preserve">a lower bound (inclusive)</doc>
|
|
<type name="guint64" c:type="guint64"/>
|
|
</parameter>
|
|
<parameter name="max" transfer-ownership="none">
|
|
<doc xml:space="preserve">an upper bound (inclusive)</doc>
|
|
<type name="guint64" c:type="guint64"/>
|
|
</parameter>
|
|
<parameter name="out_num" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">a return location for a number</doc>
|
|
<type name="guint64" c:type="guint64*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ascii_strncasecmp" c:identifier="g_ascii_strncasecmp">
|
|
<doc xml:space="preserve">Compare @s1 and @s2, ignoring the case of ASCII characters and any
|
|
characters after the first @n in each string.
|
|
|
|
Unlike the BSD strcasecmp() function, this only recognizes standard
|
|
ASCII letters and ignores the locale, treating all non-ASCII
|
|
characters as if they are not letters.
|
|
|
|
The same warning as in g_ascii_strcasecmp() applies: Use this
|
|
function only on strings known to be in encodings where bytes
|
|
corresponding to ASCII letters always represent themselves.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">0 if the strings match, a negative value if @s1 < @s2,
|
|
or a positive value if @s1 > @s2.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="s1" transfer-ownership="none">
|
|
<doc xml:space="preserve">string to compare with @s2</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="s2" transfer-ownership="none">
|
|
<doc xml:space="preserve">string to compare with @s1</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of characters to compare</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ascii_strtod" c:identifier="g_ascii_strtod">
|
|
<doc xml:space="preserve">Converts a string to a #gdouble value.
|
|
|
|
This function behaves like the standard strtod() function
|
|
does in the C locale. It does this without actually changing
|
|
the current locale, since that would not be thread-safe.
|
|
A limitation of the implementation is that this function
|
|
will still accept localized versions of infinities and NANs.
|
|
|
|
This function is typically used when reading configuration
|
|
files or other non-user input that should be locale independent.
|
|
To handle input from the user you should normally use the
|
|
locale-sensitive system strtod() function.
|
|
|
|
To convert from a #gdouble to a string in a locale-insensitive
|
|
way, use g_ascii_dtostr().
|
|
|
|
If the correct value would cause overflow, plus or minus %HUGE_VAL
|
|
is returned (according to the sign of the value), and %ERANGE is
|
|
stored in %errno. If the correct value would cause underflow,
|
|
zero is returned and %ERANGE is stored in %errno.
|
|
|
|
This function resets %errno before calling strtod() so that
|
|
you can reliably detect overflow and underflow.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the #gdouble value.</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="nptr" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to convert to a numeric value.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="endptr" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">if non-%NULL, it returns the
|
|
character after the last character used in the conversion.</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ascii_strtoll" c:identifier="g_ascii_strtoll" version="2.12">
|
|
<doc xml:space="preserve">Converts a string to a #gint64 value.
|
|
This function behaves like the standard strtoll() function
|
|
does in the C locale. It does this without actually
|
|
changing the current locale, since that would not be
|
|
thread-safe.
|
|
|
|
This function is typically used when reading configuration
|
|
files or other non-user input that should be locale independent.
|
|
To handle input from the user you should normally use the
|
|
locale-sensitive system strtoll() function.
|
|
|
|
If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64
|
|
is returned, and `ERANGE` is stored in `errno`.
|
|
If the base is outside the valid range, zero is returned, and
|
|
`EINVAL` is stored in `errno`. If the
|
|
string conversion fails, zero is returned, and @endptr returns @nptr
|
|
(if @endptr is non-%NULL).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the #gint64 value or zero on error.</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="nptr" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to convert to a numeric value.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="endptr" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">if non-%NULL, it returns the
|
|
character after the last character used in the conversion.</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="base" transfer-ownership="none">
|
|
<doc xml:space="preserve">to be used for the conversion, 2..36 or 0</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ascii_strtoull" c:identifier="g_ascii_strtoull" version="2.2">
|
|
<doc xml:space="preserve">Converts a string to a #guint64 value.
|
|
This function behaves like the standard strtoull() function
|
|
does in the C locale. It does this without actually
|
|
changing the current locale, since that would not be
|
|
thread-safe.
|
|
|
|
Note that input with a leading minus sign (`-`) is accepted, and will return
|
|
the negation of the parsed number, unless that would overflow a #guint64.
|
|
Critically, this means you cannot assume that a short fixed length input will
|
|
never result in a low return value, as the input could have a leading `-`.
|
|
|
|
This function is typically used when reading configuration
|
|
files or other non-user input that should be locale independent.
|
|
To handle input from the user you should normally use the
|
|
locale-sensitive system strtoull() function.
|
|
|
|
If the correct value would cause overflow, %G_MAXUINT64
|
|
is returned, and `ERANGE` is stored in `errno`.
|
|
If the base is outside the valid range, zero is returned, and
|
|
`EINVAL` is stored in `errno`.
|
|
If the string conversion fails, zero is returned, and @endptr returns
|
|
@nptr (if @endptr is non-%NULL).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the #guint64 value or zero on error.</doc>
|
|
<type name="guint64" c:type="guint64"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="nptr" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to convert to a numeric value.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="endptr" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">if non-%NULL, it returns the
|
|
character after the last character used in the conversion.</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="base" transfer-ownership="none">
|
|
<doc xml:space="preserve">to be used for the conversion, 2..36 or 0</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ascii_strup" c:identifier="g_ascii_strup">
|
|
<doc xml:space="preserve">Converts all lower case ASCII letters to upper case ASCII letters.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string, with all the lower case
|
|
characters in @str converted to upper case, with semantics that
|
|
exactly match g_ascii_toupper(). (Note that this is unlike the
|
|
old g_strup(), which modified the string in place.)</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @str in bytes, or -1 if @str is nul-terminated</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ascii_tolower" c:identifier="g_ascii_tolower">
|
|
<doc xml:space="preserve">Convert a character to ASCII lower case.
|
|
|
|
Unlike the standard C library tolower() function, this only
|
|
recognizes standard ASCII letters and ignores the locale, returning
|
|
all non-ASCII characters unchanged, even if they are lower case
|
|
letters in a particular character set. Also unlike the standard
|
|
library function, this takes and returns a char, not an int, so
|
|
don't call it on %EOF but no need to worry about casting to #guchar
|
|
before passing a possibly non-ASCII character in.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the result of converting @c to lower case. If @c is
|
|
not an ASCII upper case letter, @c is returned unchanged.</doc>
|
|
<type name="gchar" c:type="gchar"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">any character</doc>
|
|
<type name="gchar" c:type="gchar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ascii_toupper" c:identifier="g_ascii_toupper">
|
|
<doc xml:space="preserve">Convert a character to ASCII upper case.
|
|
|
|
Unlike the standard C library toupper() function, this only
|
|
recognizes standard ASCII letters and ignores the locale, returning
|
|
all non-ASCII characters unchanged, even if they are upper case
|
|
letters in a particular character set. Also unlike the standard
|
|
library function, this takes and returns a char, not an int, so
|
|
don't call it on %EOF but no need to worry about casting to #guchar
|
|
before passing a possibly non-ASCII character in.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the result of converting @c to upper case. If @c is not
|
|
an ASCII lower case letter, @c is returned unchanged.</doc>
|
|
<type name="gchar" c:type="gchar"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">any character</doc>
|
|
<type name="gchar" c:type="gchar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ascii_xdigit_value" c:identifier="g_ascii_xdigit_value">
|
|
<doc xml:space="preserve">Determines the numeric value of a character as a hexadecimal
|
|
digit. Differs from g_unichar_xdigit_value() because it takes
|
|
a char, so there's no worry about sign extension if characters
|
|
are signed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">If @c is a hex digit (according to g_ascii_isxdigit()),
|
|
its numeric value. Otherwise, -1.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">an ASCII character.</doc>
|
|
<type name="gchar" c:type="gchar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="assert" c:identifier="g_assert" introspectable="0">
|
|
<doc xml:space="preserve">Debugging macro to terminate the application if the assertion
|
|
fails. If the assertion fails (i.e. the expression is not true),
|
|
an error message is logged and the application is terminated.
|
|
|
|
The macro can be turned off in final releases of code by defining
|
|
`G_DISABLE_ASSERT` when compiling the application, so code must
|
|
not depend on any side effects from @expr. Similarly, it must not be used
|
|
in unit tests, otherwise the unit tests will be ineffective if compiled with
|
|
`G_DISABLE_ASSERT`. Use g_assert_true() and related macros in unit tests
|
|
instead.</doc>
|
|
<parameters>
|
|
<parameter name="expr">
|
|
<doc xml:space="preserve">the expression to check</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="assert_cmpfloat" c:identifier="g_assert_cmpfloat" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Debugging macro to compare two floating point numbers.
|
|
|
|
The effect of `g_assert_cmpfloat (n1, op, n2)` is
|
|
the same as `g_assert_true (n1 op n2)`. The advantage
|
|
of this macro is that it can produce a message that includes the
|
|
actual values of @n1 and @n2.</doc>
|
|
<parameters>
|
|
<parameter name="n1">
|
|
<doc xml:space="preserve">a floating point number</doc>
|
|
</parameter>
|
|
<parameter name="cmp">
|
|
<doc xml:space="preserve">The comparison operator to use.
|
|
One of `==`, `!=`, `<`, `>`, `<=`, `>=`.</doc>
|
|
</parameter>
|
|
<parameter name="n2">
|
|
<doc xml:space="preserve">another floating point number</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="assert_cmpfloat_with_epsilon" c:identifier="g_assert_cmpfloat_with_epsilon" version="2.58" introspectable="0">
|
|
<doc xml:space="preserve">Debugging macro to compare two floating point numbers within an epsilon.
|
|
|
|
The effect of `g_assert_cmpfloat_with_epsilon (n1, n2, epsilon)` is
|
|
the same as `g_assert_true (abs (n1 - n2) < epsilon)`. The advantage
|
|
of this macro is that it can produce a message that includes the
|
|
actual values of @n1 and @n2.</doc>
|
|
<parameters>
|
|
<parameter name="n1">
|
|
<doc xml:space="preserve">a floating point number</doc>
|
|
</parameter>
|
|
<parameter name="n2">
|
|
<doc xml:space="preserve">another floating point number</doc>
|
|
</parameter>
|
|
<parameter name="epsilon">
|
|
<doc xml:space="preserve">a numeric value that expresses the expected tolerance
|
|
between @n1 and @n2</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="assert_cmphex" c:identifier="g_assert_cmphex" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Debugging macro to compare to unsigned integers.
|
|
|
|
This is a variant of g_assert_cmpuint() that displays the numbers
|
|
in hexadecimal notation in the message.</doc>
|
|
<parameters>
|
|
<parameter name="n1">
|
|
<doc xml:space="preserve">an unsigned integer</doc>
|
|
</parameter>
|
|
<parameter name="cmp">
|
|
<doc xml:space="preserve">The comparison operator to use.
|
|
One of `==`, `!=`, `<`, `>`, `<=`, `>=`.</doc>
|
|
</parameter>
|
|
<parameter name="n2">
|
|
<doc xml:space="preserve">another unsigned integer</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="assert_cmpint" c:identifier="g_assert_cmpint" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Debugging macro to compare two integers.
|
|
|
|
The effect of `g_assert_cmpint (n1, op, n2)` is
|
|
the same as `g_assert_true (n1 op n2)`. The advantage
|
|
of this macro is that it can produce a message that includes the
|
|
actual values of @n1 and @n2.</doc>
|
|
<parameters>
|
|
<parameter name="n1">
|
|
<doc xml:space="preserve">an integer</doc>
|
|
</parameter>
|
|
<parameter name="cmp">
|
|
<doc xml:space="preserve">The comparison operator to use.
|
|
One of `==`, `!=`, `<`, `>`, `<=`, `>=`.</doc>
|
|
</parameter>
|
|
<parameter name="n2">
|
|
<doc xml:space="preserve">another integer</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="assert_cmpmem" c:identifier="g_assert_cmpmem" version="2.46" introspectable="0">
|
|
<doc xml:space="preserve">Debugging macro to compare memory regions. If the comparison fails,
|
|
an error message is logged and the application is either terminated
|
|
or the testcase marked as failed.
|
|
|
|
The effect of `g_assert_cmpmem (m1, l1, m2, l2)` is
|
|
the same as `g_assert_true (l1 == l2 && memcmp (m1, m2, l1) == 0)`.
|
|
The advantage of this macro is that it can produce a message that
|
|
includes the actual values of @l1 and @l2.
|
|
|
|
@m1 may be %NULL if (and only if) @l1 is zero; similarly for @m2 and @l2.
|
|
|
|
|[<!-- language="C" -->
|
|
g_assert_cmpmem (buf->data, buf->len, expected, sizeof (expected));
|
|
]|</doc>
|
|
<parameters>
|
|
<parameter name="m1">
|
|
<doc xml:space="preserve">pointer to a buffer</doc>
|
|
</parameter>
|
|
<parameter name="l1">
|
|
<doc xml:space="preserve">length of @m1</doc>
|
|
</parameter>
|
|
<parameter name="m2">
|
|
<doc xml:space="preserve">pointer to another buffer</doc>
|
|
</parameter>
|
|
<parameter name="l2">
|
|
<doc xml:space="preserve">length of @m2</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="assert_cmpstr" c:identifier="g_assert_cmpstr" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Debugging macro to compare two strings. If the comparison fails,
|
|
an error message is logged and the application is either terminated
|
|
or the testcase marked as failed.
|
|
The strings are compared using g_strcmp0().
|
|
|
|
The effect of `g_assert_cmpstr (s1, op, s2)` is
|
|
the same as `g_assert_true (g_strcmp0 (s1, s2) op 0)`.
|
|
The advantage of this macro is that it can produce a message that
|
|
includes the actual values of @s1 and @s2.
|
|
|
|
|[<!-- language="C" -->
|
|
g_assert_cmpstr (mystring, ==, "fubar");
|
|
]|</doc>
|
|
<parameters>
|
|
<parameter name="s1">
|
|
<doc xml:space="preserve">a string (may be %NULL)</doc>
|
|
</parameter>
|
|
<parameter name="cmp">
|
|
<doc xml:space="preserve">The comparison operator to use.
|
|
One of `==`, `!=`, `<`, `>`, `<=`, `>=`.</doc>
|
|
</parameter>
|
|
<parameter name="s2">
|
|
<doc xml:space="preserve">another string (may be %NULL)</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="assert_cmpuint" c:identifier="g_assert_cmpuint" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Debugging macro to compare two unsigned integers.
|
|
|
|
The effect of `g_assert_cmpuint (n1, op, n2)` is
|
|
the same as `g_assert_true (n1 op n2)`. The advantage
|
|
of this macro is that it can produce a message that includes the
|
|
actual values of @n1 and @n2.</doc>
|
|
<parameters>
|
|
<parameter name="n1">
|
|
<doc xml:space="preserve">an unsigned integer</doc>
|
|
</parameter>
|
|
<parameter name="cmp">
|
|
<doc xml:space="preserve">The comparison operator to use.
|
|
One of `==`, `!=`, `<`, `>`, `<=`, `>=`.</doc>
|
|
</parameter>
|
|
<parameter name="n2">
|
|
<doc xml:space="preserve">another unsigned integer</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="assert_cmpvariant" c:identifier="g_assert_cmpvariant" version="2.60" introspectable="0">
|
|
<doc xml:space="preserve">Debugging macro to compare two #GVariants. If the comparison fails,
|
|
an error message is logged and the application is either terminated
|
|
or the testcase marked as failed. The variants are compared using
|
|
g_variant_equal().
|
|
|
|
The effect of `g_assert_cmpvariant (v1, v2)` is the same as
|
|
`g_assert_true (g_variant_equal (v1, v2))`. The advantage of this macro is
|
|
that it can produce a message that includes the actual values of @v1 and @v2.</doc>
|
|
<parameters>
|
|
<parameter name="v1">
|
|
<doc xml:space="preserve">pointer to a #GVariant</doc>
|
|
</parameter>
|
|
<parameter name="v2">
|
|
<doc xml:space="preserve">pointer to another #GVariant</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="assert_error" c:identifier="g_assert_error" version="2.20" introspectable="0">
|
|
<doc xml:space="preserve">Debugging macro to check that a method has returned
|
|
the correct #GError.
|
|
|
|
The effect of `g_assert_error (err, dom, c)` is
|
|
the same as `g_assert_true (err != NULL && err->domain
|
|
== dom && err->code == c)`. The advantage of this
|
|
macro is that it can produce a message that includes the incorrect
|
|
error message and code.
|
|
|
|
This can only be used to test for a specific error. If you want to
|
|
test that @err is set, but don't care what it's set to, just use
|
|
`g_assert_nonnull (err)`.</doc>
|
|
<parameters>
|
|
<parameter name="err">
|
|
<doc xml:space="preserve">a #GError, possibly %NULL</doc>
|
|
</parameter>
|
|
<parameter name="dom">
|
|
<doc xml:space="preserve">the expected error domain (a #GQuark)</doc>
|
|
</parameter>
|
|
<parameter name="c">
|
|
<doc xml:space="preserve">the expected error code</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="assert_false" c:identifier="g_assert_false" version="2.38" introspectable="0">
|
|
<doc xml:space="preserve">Debugging macro to check an expression is false.
|
|
|
|
If the assertion fails (i.e. the expression is not false),
|
|
an error message is logged and the application is either
|
|
terminated or the testcase marked as failed.
|
|
|
|
Note that unlike g_assert(), this macro is unaffected by whether
|
|
`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and,
|
|
conversely, g_assert() should not be used in tests.
|
|
|
|
See g_test_set_nonfatal_assertions().</doc>
|
|
<parameters>
|
|
<parameter name="expr">
|
|
<doc xml:space="preserve">the expression to check</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="assert_no_errno" c:identifier="g_assert_no_errno" version="2.66" introspectable="0">
|
|
<doc xml:space="preserve">Debugging macro to check that an expression has a non-negative return value,
|
|
as used by traditional POSIX functions (such as `rmdir()`) to indicate
|
|
success.
|
|
|
|
If the assertion fails (i.e. the @expr returns a negative value), an error
|
|
message is logged and the testcase is marked as failed. The error message
|
|
will contain the value of `errno` and its human-readable message from
|
|
g_strerror().
|
|
|
|
This macro will clear the value of `errno` before executing @expr.</doc>
|
|
<parameters>
|
|
<parameter name="expr">
|
|
<doc xml:space="preserve">the expression to check</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="assert_no_error" c:identifier="g_assert_no_error" version="2.20" introspectable="0">
|
|
<doc xml:space="preserve">Debugging macro to check that a #GError is not set.
|
|
|
|
The effect of `g_assert_no_error (err)` is
|
|
the same as `g_assert_true (err == NULL)`. The advantage
|
|
of this macro is that it can produce a message that includes
|
|
the error message and code.</doc>
|
|
<parameters>
|
|
<parameter name="err">
|
|
<doc xml:space="preserve">a #GError, possibly %NULL</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="assert_nonnull" c:identifier="g_assert_nonnull" version="2.40" introspectable="0">
|
|
<doc xml:space="preserve">Debugging macro to check an expression is not %NULL.
|
|
|
|
If the assertion fails (i.e. the expression is %NULL),
|
|
an error message is logged and the application is either
|
|
terminated or the testcase marked as failed.
|
|
|
|
Note that unlike g_assert(), this macro is unaffected by whether
|
|
`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and,
|
|
conversely, g_assert() should not be used in tests.
|
|
|
|
See g_test_set_nonfatal_assertions().</doc>
|
|
<parameters>
|
|
<parameter name="expr">
|
|
<doc xml:space="preserve">the expression to check</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="assert_null" c:identifier="g_assert_null" version="2.38" introspectable="0">
|
|
<doc xml:space="preserve">Debugging macro to check an expression is %NULL.
|
|
|
|
If the assertion fails (i.e. the expression is not %NULL),
|
|
an error message is logged and the application is either
|
|
terminated or the testcase marked as failed.
|
|
|
|
Note that unlike g_assert(), this macro is unaffected by whether
|
|
`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and,
|
|
conversely, g_assert() should not be used in tests.
|
|
|
|
See g_test_set_nonfatal_assertions().</doc>
|
|
<parameters>
|
|
<parameter name="expr">
|
|
<doc xml:space="preserve">the expression to check</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="assert_true" c:identifier="g_assert_true" version="2.38" introspectable="0">
|
|
<doc xml:space="preserve">Debugging macro to check that an expression is true.
|
|
|
|
If the assertion fails (i.e. the expression is not true),
|
|
an error message is logged and the application is either
|
|
terminated or the testcase marked as failed.
|
|
|
|
Note that unlike g_assert(), this macro is unaffected by whether
|
|
`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and,
|
|
conversely, g_assert() should not be used in tests.
|
|
|
|
See g_test_set_nonfatal_assertions().</doc>
|
|
<parameters>
|
|
<parameter name="expr">
|
|
<doc xml:space="preserve">the expression to check</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="assert_warning" c:identifier="g_assert_warning">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_domain" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="file" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="line" transfer-ownership="none">
|
|
<type name="gint" c:type="const int"/>
|
|
</parameter>
|
|
<parameter name="pretty_function" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="expression" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="assertion_message" c:identifier="g_assertion_message">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="domain" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="file" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="line" transfer-ownership="none">
|
|
<type name="gint" c:type="int"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="message" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="assertion_message_cmpnum" c:identifier="g_assertion_message_cmpnum" introspectable="0">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="domain" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="file" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="line" transfer-ownership="none">
|
|
<type name="gint" c:type="int"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="expr" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="arg1" transfer-ownership="none">
|
|
<type name="long double" c:type="long double"/>
|
|
</parameter>
|
|
<parameter name="cmp" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="arg2" transfer-ownership="none">
|
|
<type name="long double" c:type="long double"/>
|
|
</parameter>
|
|
<parameter name="numtype" transfer-ownership="none">
|
|
<type name="gchar" c:type="char"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="assertion_message_cmpstr" c:identifier="g_assertion_message_cmpstr">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="domain" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="file" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="line" transfer-ownership="none">
|
|
<type name="gint" c:type="int"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="expr" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="arg1" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="cmp" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="arg2" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="assertion_message_error" c:identifier="g_assertion_message_error">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="domain" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="file" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="line" transfer-ownership="none">
|
|
<type name="gint" c:type="int"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="expr" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="error" transfer-ownership="none">
|
|
<type name="Error" c:type="const GError*"/>
|
|
</parameter>
|
|
<parameter name="error_domain" transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</parameter>
|
|
<parameter name="error_code" transfer-ownership="none">
|
|
<type name="gint" c:type="int"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="assertion_message_expr" c:identifier="g_assertion_message_expr" introspectable="0">
|
|
<doc xml:space="preserve">Internal function used to print messages from the public g_assert() and
|
|
g_assert_not_reached() macros.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="domain" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">log domain</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="file" transfer-ownership="none">
|
|
<doc xml:space="preserve">file containing the assertion</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="line" transfer-ownership="none">
|
|
<doc xml:space="preserve">line number of the assertion</doc>
|
|
<type name="gint" c:type="int"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<doc xml:space="preserve">function containing the assertion</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="expr" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">expression which failed</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="async_queues">
|
|
<doc xml:space="preserve">Often you need to communicate between different threads. In general
|
|
it's safer not to do this by shared memory, but by explicit message
|
|
passing. These messages only make sense asynchronously for
|
|
multi-threaded applications though, as a synchronous operation could
|
|
as well be done in the same thread.
|
|
|
|
Asynchronous queues are an exception from most other GLib data
|
|
structures, as they can be used simultaneously from multiple threads
|
|
without explicit locking and they bring their own builtin reference
|
|
counting. This is because the nature of an asynchronous queue is that
|
|
it will always be used by at least 2 concurrent threads.
|
|
|
|
For using an asynchronous queue you first have to create one with
|
|
g_async_queue_new(). #GAsyncQueue structs are reference counted,
|
|
use g_async_queue_ref() and g_async_queue_unref() to manage your
|
|
references.
|
|
|
|
A thread which wants to send a message to that queue simply calls
|
|
g_async_queue_push() to push the message to the queue.
|
|
|
|
A thread which is expecting messages from an asynchronous queue
|
|
simply calls g_async_queue_pop() for that queue. If no message is
|
|
available in the queue at that point, the thread is now put to sleep
|
|
until a message arrives. The message will be removed from the queue
|
|
and returned. The functions g_async_queue_try_pop() and
|
|
g_async_queue_timeout_pop() can be used to only check for the presence
|
|
of messages or to only wait a certain time for messages respectively.
|
|
|
|
For almost every function there exist two variants, one that locks
|
|
the queue and one that doesn't. That way you can hold the queue lock
|
|
(acquire it with g_async_queue_lock() and release it with
|
|
g_async_queue_unlock()) over multiple queue accessing instructions.
|
|
This can be necessary to ensure the integrity of the queue, but should
|
|
only be used when really necessary, as it can make your life harder
|
|
if used unwisely. Normally you should only use the locking function
|
|
variants (those without the _unlocked suffix).
|
|
|
|
In many cases, it may be more convenient to use #GThreadPool when
|
|
you need to distribute work to a set of worker threads instead of
|
|
using #GAsyncQueue manually. #GThreadPool uses a GAsyncQueue
|
|
internally.</doc>
|
|
</docsection>
|
|
<function name="atexit" c:identifier="g_atexit" deprecated="1" deprecated-version="2.32">
|
|
<doc xml:space="preserve">Specifies a function to be called at normal program termination.
|
|
|
|
Since GLib 2.8.2, on Windows g_atexit() actually is a preprocessor
|
|
macro that maps to a call to the atexit() function in the C
|
|
library. This means that in case the code that calls g_atexit(),
|
|
i.e. atexit(), is in a DLL, the function will be called when the
|
|
DLL is detached from the program. This typically makes more sense
|
|
than that the function is called when the GLib DLL is detached,
|
|
which happened earlier when g_atexit() was a function in the GLib
|
|
DLL.
|
|
|
|
The behaviour of atexit() in the context of dynamically loaded
|
|
modules is not formally specified and varies wildly.
|
|
|
|
On POSIX systems, calling g_atexit() (or atexit()) in a dynamically
|
|
loaded module which is unloaded before the program terminates might
|
|
well cause a crash at program exit.
|
|
|
|
Some POSIX systems implement atexit() like Windows, and have each
|
|
dynamically loaded module maintain an own atexit chain that is
|
|
called when the module is unloaded.
|
|
|
|
On other POSIX systems, before a dynamically loaded module is
|
|
unloaded, the registered atexit functions (if any) residing in that
|
|
module are called, regardless where the code that registered them
|
|
resided. This is presumably the most robust approach.
|
|
|
|
As can be seen from the above, for portability it's best to avoid
|
|
calling g_atexit() (or atexit()) except in the main executable of a
|
|
program.</doc>
|
|
<doc-deprecated xml:space="preserve">It is best to avoid g_atexit().</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="func" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">the function to call on normal program termination.</doc>
|
|
<type name="VoidFunc" c:type="GVoidFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_int_add" c:identifier="g_atomic_int_add" version="2.4">
|
|
<doc xml:space="preserve">Atomically adds @val to the value of @atomic.
|
|
|
|
Think of this operation as an atomic version of
|
|
`{ tmp = *atomic; *atomic += val; return tmp; }`.
|
|
|
|
This call acts as a full compiler and hardware memory barrier.
|
|
|
|
Before version 2.30, this function did not return a value
|
|
(but g_atomic_int_exchange_and_add() did, and had the same meaning).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the value of @atomic before the add, signed</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="atomic" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gint or #guint</doc>
|
|
<type name="gint" c:type="volatile gint*"/>
|
|
</parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">the value to add</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_int_and" c:identifier="g_atomic_int_and" version="2.30">
|
|
<doc xml:space="preserve">Performs an atomic bitwise 'and' of the value of @atomic and @val,
|
|
storing the result back in @atomic.
|
|
|
|
This call acts as a full compiler and hardware memory barrier.
|
|
|
|
Think of this operation as an atomic version of
|
|
`{ tmp = *atomic; *atomic &= val; return tmp; }`.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the value of @atomic before the operation, unsigned</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="atomic" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gint or #guint</doc>
|
|
<type name="guint" c:type="volatile guint*"/>
|
|
</parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">the value to 'and'</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_int_compare_and_exchange" c:identifier="g_atomic_int_compare_and_exchange" version="2.4">
|
|
<doc xml:space="preserve">Compares @atomic to @oldval and, if equal, sets it to @newval.
|
|
If @atomic was not equal to @oldval then no change occurs.
|
|
|
|
This compare and exchange is done atomically.
|
|
|
|
Think of this operation as an atomic version of
|
|
`{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`.
|
|
|
|
This call acts as a full compiler and hardware memory barrier.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the exchange took place</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="atomic" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gint or #guint</doc>
|
|
<type name="gint" c:type="volatile gint*"/>
|
|
</parameter>
|
|
<parameter name="oldval" transfer-ownership="none">
|
|
<doc xml:space="preserve">the value to compare with</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="newval" transfer-ownership="none">
|
|
<doc xml:space="preserve">the value to conditionally replace with</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_int_dec_and_test" c:identifier="g_atomic_int_dec_and_test" version="2.4">
|
|
<doc xml:space="preserve">Decrements the value of @atomic by 1.
|
|
|
|
Think of this operation as an atomic version of
|
|
`{ *atomic -= 1; return (*atomic == 0); }`.
|
|
|
|
This call acts as a full compiler and hardware memory barrier.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the resultant value is zero</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="atomic" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gint or #guint</doc>
|
|
<type name="gint" c:type="volatile gint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_int_exchange_and_add" c:identifier="g_atomic_int_exchange_and_add" version="2.4" deprecated="1" deprecated-version="2.30">
|
|
<doc xml:space="preserve">This function existed before g_atomic_int_add() returned the prior
|
|
value of the integer (which it now does). It is retained only for
|
|
compatibility reasons. Don't use this function in new code.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_atomic_int_add() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the value of @atomic before the add, signed</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="atomic" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gint</doc>
|
|
<type name="gint" c:type="volatile gint*"/>
|
|
</parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">the value to add</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_int_get" c:identifier="g_atomic_int_get" version="2.4">
|
|
<doc xml:space="preserve">Gets the current value of @atomic.
|
|
|
|
This call acts as a full compiler and hardware
|
|
memory barrier (before the get).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the value of the integer</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="atomic" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gint or #guint</doc>
|
|
<type name="gint" c:type="volatile const gint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_int_inc" c:identifier="g_atomic_int_inc" version="2.4">
|
|
<doc xml:space="preserve">Increments the value of @atomic by 1.
|
|
|
|
Think of this operation as an atomic version of `{ *atomic += 1; }`.
|
|
|
|
This call acts as a full compiler and hardware memory barrier.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="atomic" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gint or #guint</doc>
|
|
<type name="gint" c:type="volatile gint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_int_or" c:identifier="g_atomic_int_or" version="2.30">
|
|
<doc xml:space="preserve">Performs an atomic bitwise 'or' of the value of @atomic and @val,
|
|
storing the result back in @atomic.
|
|
|
|
Think of this operation as an atomic version of
|
|
`{ tmp = *atomic; *atomic |= val; return tmp; }`.
|
|
|
|
This call acts as a full compiler and hardware memory barrier.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the value of @atomic before the operation, unsigned</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="atomic" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gint or #guint</doc>
|
|
<type name="guint" c:type="volatile guint*"/>
|
|
</parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">the value to 'or'</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_int_set" c:identifier="g_atomic_int_set" version="2.4">
|
|
<doc xml:space="preserve">Sets the value of @atomic to @newval.
|
|
|
|
This call acts as a full compiler and hardware
|
|
memory barrier (after the set).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="atomic" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gint or #guint</doc>
|
|
<type name="gint" c:type="volatile gint*"/>
|
|
</parameter>
|
|
<parameter name="newval" transfer-ownership="none">
|
|
<doc xml:space="preserve">a new value to store</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_int_xor" c:identifier="g_atomic_int_xor" version="2.30">
|
|
<doc xml:space="preserve">Performs an atomic bitwise 'xor' of the value of @atomic and @val,
|
|
storing the result back in @atomic.
|
|
|
|
Think of this operation as an atomic version of
|
|
`{ tmp = *atomic; *atomic ^= val; return tmp; }`.
|
|
|
|
This call acts as a full compiler and hardware memory barrier.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the value of @atomic before the operation, unsigned</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="atomic" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gint or #guint</doc>
|
|
<type name="guint" c:type="volatile guint*"/>
|
|
</parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">the value to 'xor'</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="atomic_operations">
|
|
<doc xml:space="preserve">The following is a collection of compiler macros to provide atomic
|
|
access to integer and pointer-sized values.
|
|
|
|
The macros that have 'int' in the name will operate on pointers to
|
|
#gint and #guint. The macros with 'pointer' in the name will operate
|
|
on pointers to any pointer-sized value, including #gsize. There is
|
|
no support for 64bit operations on platforms with 32bit pointers
|
|
because it is not generally possible to perform these operations
|
|
atomically.
|
|
|
|
The get, set and exchange operations for integers and pointers
|
|
nominally operate on #gint and #gpointer, respectively. Of the
|
|
arithmetic operations, the 'add' operation operates on (and returns)
|
|
signed integer values (#gint and #gssize) and the 'and', 'or', and
|
|
'xor' operations operate on (and return) unsigned integer values
|
|
(#guint and #gsize).
|
|
|
|
All of the operations act as a full compiler and (where appropriate)
|
|
hardware memory barrier. Acquire and release or producer and
|
|
consumer barrier semantics are not available through this API.
|
|
|
|
It is very important that all accesses to a particular integer or
|
|
pointer be performed using only this API and that different sizes of
|
|
operation are not mixed or used on overlapping memory regions. Never
|
|
read or assign directly from or to a value -- always use this API.
|
|
|
|
For simple reference counting purposes you should use
|
|
g_atomic_int_inc() and g_atomic_int_dec_and_test(). Other uses that
|
|
fall outside of simple reference counting patterns are prone to
|
|
subtle bugs and occasionally undefined behaviour. It is also worth
|
|
noting that since all of these operations require global
|
|
synchronisation of the entire machine, they can be quite slow. In
|
|
the case of performing multiple atomic operations it can often be
|
|
faster to simply acquire a mutex lock around the critical area,
|
|
perform the operations normally and then release the lock.</doc>
|
|
</docsection>
|
|
<function name="atomic_pointer_add" c:identifier="g_atomic_pointer_add" version="2.30">
|
|
<doc xml:space="preserve">Atomically adds @val to the value of @atomic.
|
|
|
|
Think of this operation as an atomic version of
|
|
`{ tmp = *atomic; *atomic += val; return tmp; }`.
|
|
|
|
This call acts as a full compiler and hardware memory barrier.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the value of @atomic before the add, signed</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="atomic" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gpointer-sized value</doc>
|
|
<type name="gpointer" c:type="void*"/>
|
|
</parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">the value to add</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_pointer_and" c:identifier="g_atomic_pointer_and" version="2.30">
|
|
<doc xml:space="preserve">Performs an atomic bitwise 'and' of the value of @atomic and @val,
|
|
storing the result back in @atomic.
|
|
|
|
Think of this operation as an atomic version of
|
|
`{ tmp = *atomic; *atomic &= val; return tmp; }`.
|
|
|
|
This call acts as a full compiler and hardware memory barrier.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the value of @atomic before the operation, unsigned</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="atomic" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gpointer-sized value</doc>
|
|
<type name="gpointer" c:type="void*"/>
|
|
</parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">the value to 'and'</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_pointer_compare_and_exchange" c:identifier="g_atomic_pointer_compare_and_exchange" version="2.4">
|
|
<doc xml:space="preserve">Compares @atomic to @oldval and, if equal, sets it to @newval.
|
|
If @atomic was not equal to @oldval then no change occurs.
|
|
|
|
This compare and exchange is done atomically.
|
|
|
|
Think of this operation as an atomic version of
|
|
`{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`.
|
|
|
|
This call acts as a full compiler and hardware memory barrier.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the exchange took place</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="atomic" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gpointer-sized value</doc>
|
|
<type name="gpointer" c:type="void*"/>
|
|
</parameter>
|
|
<parameter name="oldval" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the value to compare with</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="newval" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the value to conditionally replace with</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_pointer_get" c:identifier="g_atomic_pointer_get" version="2.4">
|
|
<doc xml:space="preserve">Gets the current value of @atomic.
|
|
|
|
This call acts as a full compiler and hardware
|
|
memory barrier (before the get).</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the value of the pointer</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="atomic" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gpointer-sized value</doc>
|
|
<type name="gpointer" c:type="void*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_pointer_or" c:identifier="g_atomic_pointer_or" version="2.30">
|
|
<doc xml:space="preserve">Performs an atomic bitwise 'or' of the value of @atomic and @val,
|
|
storing the result back in @atomic.
|
|
|
|
Think of this operation as an atomic version of
|
|
`{ tmp = *atomic; *atomic |= val; return tmp; }`.
|
|
|
|
This call acts as a full compiler and hardware memory barrier.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the value of @atomic before the operation, unsigned</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="atomic" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gpointer-sized value</doc>
|
|
<type name="gpointer" c:type="void*"/>
|
|
</parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">the value to 'or'</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_pointer_set" c:identifier="g_atomic_pointer_set" version="2.4">
|
|
<doc xml:space="preserve">Sets the value of @atomic to @newval.
|
|
|
|
This call acts as a full compiler and hardware
|
|
memory barrier (after the set).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="atomic" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gpointer-sized value</doc>
|
|
<type name="gpointer" c:type="void*"/>
|
|
</parameter>
|
|
<parameter name="newval" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a new value to store</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_pointer_xor" c:identifier="g_atomic_pointer_xor" version="2.30">
|
|
<doc xml:space="preserve">Performs an atomic bitwise 'xor' of the value of @atomic and @val,
|
|
storing the result back in @atomic.
|
|
|
|
Think of this operation as an atomic version of
|
|
`{ tmp = *atomic; *atomic ^= val; return tmp; }`.
|
|
|
|
This call acts as a full compiler and hardware memory barrier.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the value of @atomic before the operation, unsigned</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="atomic" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gpointer-sized value</doc>
|
|
<type name="gpointer" c:type="void*"/>
|
|
</parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">the value to 'xor'</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_rc_box_acquire" c:identifier="g_atomic_rc_box_acquire" version="2.58">
|
|
<doc xml:space="preserve">Atomically acquires a reference on the data pointed by @mem_block.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to the data,
|
|
with its reference count increased</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mem_block" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to reference counted data</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_rc_box_alloc" c:identifier="g_atomic_rc_box_alloc" version="2.58">
|
|
<doc xml:space="preserve">Allocates @block_size bytes of memory, and adds atomic
|
|
reference counting semantics to it.
|
|
|
|
The data will be freed when its reference count drops to
|
|
zero.
|
|
|
|
The allocated data is guaranteed to be suitably aligned for any
|
|
built-in type.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to the allocated memory</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="block_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of the allocation, must be greater than 0</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_rc_box_alloc0" c:identifier="g_atomic_rc_box_alloc0" version="2.58">
|
|
<doc xml:space="preserve">Allocates @block_size bytes of memory, and adds atomic
|
|
reference counting semantics to it.
|
|
|
|
The contents of the returned data is set to zero.
|
|
|
|
The data will be freed when its reference count drops to
|
|
zero.
|
|
|
|
The allocated data is guaranteed to be suitably aligned for any
|
|
built-in type.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to the allocated memory</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="block_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of the allocation, must be greater than 0</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_rc_box_dup" c:identifier="g_atomic_rc_box_dup" version="2.58">
|
|
<doc xml:space="preserve">Allocates a new block of data with atomic reference counting
|
|
semantics, and copies @block_size bytes of @mem_block
|
|
into it.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to the allocated
|
|
memory</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="block_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes to copy, must be greater than 0</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="mem_block" transfer-ownership="none">
|
|
<doc xml:space="preserve">the memory to copy</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_rc_box_get_size" c:identifier="g_atomic_rc_box_get_size" version="2.58">
|
|
<doc xml:space="preserve">Retrieves the size of the reference counted data pointed by @mem_block.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of the data, in bytes</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mem_block" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to reference counted data</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="atomic_rc_box_new" c:identifier="g_atomic_rc_box_new" version="2.58" introspectable="0">
|
|
<doc xml:space="preserve">A convenience macro to allocate atomically reference counted
|
|
data with the size of the given @type.
|
|
|
|
This macro calls g_atomic_rc_box_alloc() with `sizeof (@type)` and
|
|
casts the returned pointer to a pointer of the given @type,
|
|
avoiding a type cast in the source code.</doc>
|
|
<parameters>
|
|
<parameter name="type">
|
|
<doc xml:space="preserve">the type to allocate, typically a structure name</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="atomic_rc_box_new0" c:identifier="g_atomic_rc_box_new0" version="2.58" introspectable="0">
|
|
<doc xml:space="preserve">A convenience macro to allocate atomically reference counted
|
|
data with the size of the given @type, and set its contents
|
|
to zero.
|
|
|
|
This macro calls g_atomic_rc_box_alloc0() with `sizeof (@type)` and
|
|
casts the returned pointer to a pointer of the given @type,
|
|
avoiding a type cast in the source code.</doc>
|
|
<parameters>
|
|
<parameter name="type">
|
|
<doc xml:space="preserve">the type to allocate, typically a structure name</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="atomic_rc_box_release" c:identifier="g_atomic_rc_box_release" version="2.58">
|
|
<doc xml:space="preserve">Atomically releases a reference on the data pointed by @mem_block.
|
|
|
|
If the reference was the last one, it will free the
|
|
resources allocated for @mem_block.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mem_block" transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to reference counted data</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_rc_box_release_full" c:identifier="g_atomic_rc_box_release_full" version="2.58">
|
|
<doc xml:space="preserve">Atomically releases a reference on the data pointed by @mem_block.
|
|
|
|
If the reference was the last one, it will call @clear_func
|
|
to clear the contents of @mem_block, and then will free the
|
|
resources allocated for @mem_block.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mem_block" transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to reference counted data</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="clear_func" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">a function to call when clearing the data</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_ref_count_compare" c:identifier="g_atomic_ref_count_compare" version="2.58">
|
|
<doc xml:space="preserve">Atomically compares the current value of @arc with @val.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the reference count is the same
|
|
as the given value</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="arc" transfer-ownership="none">
|
|
<doc xml:space="preserve">the address of an atomic reference count variable</doc>
|
|
<type name="gint" c:type="gatomicrefcount*"/>
|
|
</parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">the value to compare</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_ref_count_dec" c:identifier="g_atomic_ref_count_dec" version="2.58">
|
|
<doc xml:space="preserve">Atomically decreases the reference count.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the reference count reached 0, and %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="arc" transfer-ownership="none">
|
|
<doc xml:space="preserve">the address of an atomic reference count variable</doc>
|
|
<type name="gint" c:type="gatomicrefcount*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_ref_count_inc" c:identifier="g_atomic_ref_count_inc" version="2.58">
|
|
<doc xml:space="preserve">Atomically increases the reference count.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="arc" transfer-ownership="none">
|
|
<doc xml:space="preserve">the address of an atomic reference count variable</doc>
|
|
<type name="gint" c:type="gatomicrefcount*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="atomic_ref_count_init" c:identifier="g_atomic_ref_count_init" version="2.58">
|
|
<doc xml:space="preserve">Initializes a reference count variable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="arc" transfer-ownership="none">
|
|
<doc xml:space="preserve">the address of an atomic reference count variable</doc>
|
|
<type name="gint" c:type="gatomicrefcount*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="base64">
|
|
<doc xml:space="preserve">Base64 is an encoding that allows a sequence of arbitrary bytes to be
|
|
encoded as a sequence of printable ASCII characters. For the definition
|
|
of Base64, see
|
|
[RFC 1421](http://www.ietf.org/rfc/rfc1421.txt)
|
|
or
|
|
[RFC 2045](http://www.ietf.org/rfc/rfc2045.txt).
|
|
Base64 is most commonly used as a MIME transfer encoding
|
|
for email.
|
|
|
|
GLib supports incremental encoding using g_base64_encode_step() and
|
|
g_base64_encode_close(). Incremental decoding can be done with
|
|
g_base64_decode_step(). To encode or decode data in one go, use
|
|
g_base64_encode() or g_base64_decode(). To avoid memory allocation when
|
|
decoding, you can use g_base64_decode_inplace().
|
|
|
|
Support for Base64 encoding has been added in GLib 2.12.</doc>
|
|
</docsection>
|
|
<function name="base64_decode" c:identifier="g_base64_decode" version="2.12">
|
|
<doc xml:space="preserve">Decode a sequence of Base-64 encoded text into binary data. Note
|
|
that the returned binary data is not necessarily zero-terminated,
|
|
so it should not be used as a character string.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">
|
|
newly allocated buffer containing the binary data
|
|
that @text represents. The returned buffer must
|
|
be freed with g_free().</doc>
|
|
<array length="1" zero-terminated="0" c:type="guchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="text" transfer-ownership="none">
|
|
<doc xml:space="preserve">zero-terminated string with base64 text to decode</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="out_len" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">The length of the decoded data is written here</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="base64_decode_inplace" c:identifier="g_base64_decode_inplace" version="2.20">
|
|
<doc xml:space="preserve">Decode a sequence of Base-64 encoded text into binary data
|
|
by overwriting the input data.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">The binary data that @text responds. This pointer
|
|
is the same as the input @text.</doc>
|
|
<type name="guint8" c:type="guchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="text" direction="inout" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">zero-terminated
|
|
string with base64 text to decode</doc>
|
|
<array length="1" zero-terminated="0" c:type="gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="out_len" direction="inout" caller-allocates="0" transfer-ownership="none">
|
|
<doc xml:space="preserve">The length of the decoded data is written here</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="base64_decode_step" c:identifier="g_base64_decode_step" version="2.12" introspectable="0">
|
|
<doc xml:space="preserve">Incrementally decode a sequence of binary data from its Base-64 stringified
|
|
representation. By calling this function multiple times you can convert
|
|
data in chunks to avoid having to have the full encoded data in memory.
|
|
|
|
The output buffer must be large enough to fit all the data that will
|
|
be written to it. Since base64 encodes 3 bytes in 4 chars you need
|
|
at least: (@len / 4) * 3 + 3 bytes (+ 3 may be needed in case of non-zero
|
|
state).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">The number of bytes of output that was written</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="in" transfer-ownership="none">
|
|
<doc xml:space="preserve">binary input data</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">max length of @in data to decode</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="out" direction="out" caller-allocates="1" transfer-ownership="none">
|
|
<doc xml:space="preserve">output buffer</doc>
|
|
<array zero-terminated="0" c:type="guchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="state" direction="inout" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">Saved state between steps, initialize to 0</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="save" direction="inout" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">Saved state between steps, initialize to 0</doc>
|
|
<type name="guint" c:type="guint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="base64_encode" c:identifier="g_base64_encode" version="2.12">
|
|
<doc xml:space="preserve">Encode a sequence of binary data into its Base-64 stringified
|
|
representation.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated, zero-terminated Base-64
|
|
encoded string representing @data. The returned string must
|
|
be freed with g_free().</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the binary data to encode</doc>
|
|
<array length="1" zero-terminated="0" c:type="const guchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @data</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="base64_encode_close" c:identifier="g_base64_encode_close" version="2.12">
|
|
<doc xml:space="preserve">Flush the status from a sequence of calls to g_base64_encode_step().
|
|
|
|
The output buffer must be large enough to fit all the data that will
|
|
be written to it. It will need up to 4 bytes, or up to 5 bytes if
|
|
line-breaking is enabled.
|
|
|
|
The @out array will not be automatically nul-terminated.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">The number of bytes of output that was written</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="break_lines" transfer-ownership="none">
|
|
<doc xml:space="preserve">whether to break long lines</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
<parameter name="out" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">pointer to destination buffer</doc>
|
|
<array zero-terminated="0" c:type="gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="state" direction="inout" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">Saved state from g_base64_encode_step()</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="save" direction="inout" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">Saved state from g_base64_encode_step()</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="base64_encode_step" c:identifier="g_base64_encode_step" version="2.12">
|
|
<doc xml:space="preserve">Incrementally encode a sequence of binary data into its Base-64 stringified
|
|
representation. By calling this function multiple times you can convert
|
|
data in chunks to avoid having to have the full encoded data in memory.
|
|
|
|
When all of the data has been converted you must call
|
|
g_base64_encode_close() to flush the saved state.
|
|
|
|
The output buffer must be large enough to fit all the data that will
|
|
be written to it. Due to the way base64 encodes you will need
|
|
at least: (@len / 3 + 1) * 4 + 4 bytes (+ 4 may be needed in case of
|
|
non-zero state). If you enable line-breaking you will need at least:
|
|
((@len / 3 + 1) * 4 + 4) / 76 + 1 bytes of extra space.
|
|
|
|
@break_lines is typically used when putting base64-encoded data in emails.
|
|
It breaks the lines at 76 columns instead of putting all of the text on
|
|
the same line. This avoids problems with long lines in the email system.
|
|
Note however that it breaks the lines with `LF` characters, not
|
|
`CR LF` sequences, so the result cannot be passed directly to SMTP
|
|
or certain other protocols.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">The number of bytes of output that was written</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="in" transfer-ownership="none">
|
|
<doc xml:space="preserve">the binary data to encode</doc>
|
|
<array length="1" zero-terminated="0" c:type="const guchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @in</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="break_lines" transfer-ownership="none">
|
|
<doc xml:space="preserve">whether to break long lines</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
<parameter name="out" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">pointer to destination buffer</doc>
|
|
<array zero-terminated="0" c:type="gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="state" direction="inout" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">Saved state between steps, initialize to 0</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="save" direction="inout" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">Saved state between steps, initialize to 0</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="basename" c:identifier="g_basename" deprecated="1" deprecated-version="2.2">
|
|
<doc xml:space="preserve">Gets the name of the file without any leading directory
|
|
components. It returns a pointer into the given file name
|
|
string.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_path_get_basename() instead, but notice
|
|
that g_path_get_basename() allocates new memory for the
|
|
returned string, unlike this function which returns a pointer
|
|
into the argument.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the name of the file without any leading
|
|
directory components</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="file_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">the name of the file</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="bit_lock" c:identifier="g_bit_lock" version="2.24">
|
|
<doc xml:space="preserve">Sets the indicated @lock_bit in @address. If the bit is already
|
|
set, this call will block until g_bit_unlock() unsets the
|
|
corresponding bit.
|
|
|
|
Attempting to lock on two different bits within the same integer is
|
|
not supported and will very probably cause deadlocks.
|
|
|
|
The value of the bit that is set is (1u << @bit). If @bit is not
|
|
between 0 and 31 then the result is undefined.
|
|
|
|
This function accesses @address atomically. All other accesses to
|
|
@address must be atomic in order for this function to work
|
|
reliably.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="address" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to an integer</doc>
|
|
<type name="gint" c:type="volatile gint*"/>
|
|
</parameter>
|
|
<parameter name="lock_bit" transfer-ownership="none">
|
|
<doc xml:space="preserve">a bit value between 0 and 31</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="bit_nth_lsf" c:identifier="g_bit_nth_lsf">
|
|
<doc xml:space="preserve">Find the position of the first bit set in @mask, searching
|
|
from (but not including) @nth_bit upwards. Bits are numbered
|
|
from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63,
|
|
usually). To start searching from the 0th bit, set @nth_bit to -1.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the first bit set which is higher than @nth_bit, or -1
|
|
if no higher bits are set</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mask" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #gulong containing flags</doc>
|
|
<type name="gulong" c:type="gulong"/>
|
|
</parameter>
|
|
<parameter name="nth_bit" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the bit to start the search from</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="bit_nth_msf" c:identifier="g_bit_nth_msf">
|
|
<doc xml:space="preserve">Find the position of the first bit set in @mask, searching
|
|
from (but not including) @nth_bit downwards. Bits are numbered
|
|
from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63,
|
|
usually). To start searching from the last bit, set @nth_bit to
|
|
-1 or GLIB_SIZEOF_LONG * 8.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the first bit set which is lower than @nth_bit, or -1
|
|
if no lower bits are set</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mask" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #gulong containing flags</doc>
|
|
<type name="gulong" c:type="gulong"/>
|
|
</parameter>
|
|
<parameter name="nth_bit" transfer-ownership="none">
|
|
<doc xml:space="preserve">the index of the bit to start the search from</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="bit_storage" c:identifier="g_bit_storage">
|
|
<doc xml:space="preserve">Gets the number of bits used to hold @number,
|
|
e.g. if @number is 4, 3 bits are needed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bits used to hold @number</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="number" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #guint</doc>
|
|
<type name="gulong" c:type="gulong"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="bit_trylock" c:identifier="g_bit_trylock" version="2.24">
|
|
<doc xml:space="preserve">Sets the indicated @lock_bit in @address, returning %TRUE if
|
|
successful. If the bit is already set, returns %FALSE immediately.
|
|
|
|
Attempting to lock on two different bits within the same integer is
|
|
not supported.
|
|
|
|
The value of the bit that is set is (1u << @bit). If @bit is not
|
|
between 0 and 31 then the result is undefined.
|
|
|
|
This function accesses @address atomically. All other accesses to
|
|
@address must be atomic in order for this function to work
|
|
reliably.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the lock was acquired</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="address" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to an integer</doc>
|
|
<type name="gint" c:type="volatile gint*"/>
|
|
</parameter>
|
|
<parameter name="lock_bit" transfer-ownership="none">
|
|
<doc xml:space="preserve">a bit value between 0 and 31</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="bit_unlock" c:identifier="g_bit_unlock" version="2.24">
|
|
<doc xml:space="preserve">Clears the indicated @lock_bit in @address. If another thread is
|
|
currently blocked in g_bit_lock() on this same bit then it will be
|
|
woken up.
|
|
|
|
This function accesses @address atomically. All other accesses to
|
|
@address must be atomic in order for this function to work
|
|
reliably.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="address" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to an integer</doc>
|
|
<type name="gint" c:type="volatile gint*"/>
|
|
</parameter>
|
|
<parameter name="lock_bit" transfer-ownership="none">
|
|
<doc xml:space="preserve">a bit value between 0 and 31</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="bookmark_file_error_quark" c:identifier="g_bookmark_file_error_quark" moved-to="BookmarkFile.error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<docsection name="bookmarkfile">
|
|
<doc xml:space="preserve">GBookmarkFile lets you parse, edit or create files containing bookmarks
|
|
to URI, along with some meta-data about the resource pointed by the URI
|
|
like its MIME type, the application that is registering the bookmark and
|
|
the icon that should be used to represent the bookmark. The data is stored
|
|
using the
|
|
[Desktop Bookmark Specification](http://www.gnome.org/~ebassi/bookmark-spec).
|
|
|
|
The syntax of the bookmark files is described in detail inside the
|
|
Desktop Bookmark Specification, here is a quick summary: bookmark
|
|
files use a sub-class of the XML Bookmark Exchange Language
|
|
specification, consisting of valid UTF-8 encoded XML, under the
|
|
<xbel> root element; each bookmark is stored inside a
|
|
<bookmark> element, using its URI: no relative paths can
|
|
be used inside a bookmark file. The bookmark may have a user defined
|
|
title and description, to be used instead of the URI. Under the
|
|
<metadata> element, with its owner attribute set to
|
|
`http://freedesktop.org`, is stored the meta-data about a resource
|
|
pointed by its URI. The meta-data consists of the resource's MIME
|
|
type; the applications that have registered a bookmark; the groups
|
|
to which a bookmark belongs to; a visibility flag, used to set the
|
|
bookmark as "private" to the applications and groups that has it
|
|
registered; the URI and MIME type of an icon, to be used when
|
|
displaying the bookmark inside a GUI.
|
|
|
|
Here is an example of a bookmark file:
|
|
[bookmarks.xbel](https://git.gnome.org/browse/glib/tree/glib/tests/bookmarks.xbel)
|
|
|
|
A bookmark file might contain more than one bookmark; each bookmark
|
|
is accessed through its URI.
|
|
|
|
The important caveat of bookmark files is that when you add a new
|
|
bookmark you must also add the application that is registering it, using
|
|
g_bookmark_file_add_application() or g_bookmark_file_set_application_info().
|
|
If a bookmark has no applications then it won't be dumped when creating
|
|
the on disk representation, using g_bookmark_file_to_data() or
|
|
g_bookmark_file_to_file().
|
|
|
|
The #GBookmarkFile parser was added in GLib 2.12.</doc>
|
|
</docsection>
|
|
<function name="build_filename" c:identifier="g_build_filename" introspectable="0">
|
|
<doc xml:space="preserve">Creates a filename from a series of elements using the correct
|
|
separator for filenames.
|
|
|
|
On Unix, this function behaves identically to `g_build_path
|
|
(G_DIR_SEPARATOR_S, first_element, ....)`.
|
|
|
|
On Windows, it takes into account that either the backslash
|
|
(`\` or slash (`/`) can be used as separator in filenames, but
|
|
otherwise behaves as on UNIX. When file pathname separators need
|
|
to be inserted, the one that last previously occurred in the
|
|
parameters (reading from left to right) is used.
|
|
|
|
No attempt is made to force the resulting filename to be an absolute
|
|
path. If the first element is a relative path, the result will
|
|
be a relative path.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated string that must be freed with
|
|
g_free().</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="first_element" transfer-ownership="none">
|
|
<doc xml:space="preserve">the first element in the path</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">remaining elements in path, terminated by %NULL</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="build_filename_valist" c:identifier="g_build_filename_valist" version="2.56" introspectable="0">
|
|
<doc xml:space="preserve">Behaves exactly like g_build_filename(), but takes the path elements
|
|
as a va_list. This function is mainly meant for language bindings.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated string that must be freed
|
|
with g_free().</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="first_element" transfer-ownership="none">
|
|
<doc xml:space="preserve">the first element in the path</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="args" transfer-ownership="none">
|
|
<doc xml:space="preserve">va_list of remaining elements in path</doc>
|
|
<type name="va_list" c:type="va_list*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="build_filenamev" c:identifier="g_build_filenamev" version="2.8">
|
|
<doc xml:space="preserve">Behaves exactly like g_build_filename(), but takes the path elements
|
|
as a string array, instead of varargs. This function is mainly
|
|
meant for language bindings.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated string that must be freed
|
|
with g_free().</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="args" transfer-ownership="none">
|
|
<doc xml:space="preserve">%NULL-terminated
|
|
array of strings containing the path elements.</doc>
|
|
<array c:type="gchar**">
|
|
<type name="filename"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="build_path" c:identifier="g_build_path" introspectable="0">
|
|
<doc xml:space="preserve">Creates a path from a series of elements using @separator as the
|
|
separator between elements. At the boundary between two elements,
|
|
any trailing occurrences of separator in the first element, or
|
|
leading occurrences of separator in the second element are removed
|
|
and exactly one copy of the separator is inserted.
|
|
|
|
Empty elements are ignored.
|
|
|
|
The number of leading copies of the separator on the result is
|
|
the same as the number of leading copies of the separator on
|
|
the first non-empty element.
|
|
|
|
The number of trailing copies of the separator on the result is
|
|
the same as the number of trailing copies of the separator on
|
|
the last non-empty element. (Determination of the number of
|
|
trailing copies is done without stripping leading copies, so
|
|
if the separator is `ABA`, then `ABABA` has 1 trailing copy.)
|
|
|
|
However, if there is only a single non-empty element, and there
|
|
are no characters in that element not part of the leading or
|
|
trailing separators, then the result is exactly the original value
|
|
of that element.
|
|
|
|
Other than for determination of the number of leading and trailing
|
|
copies of the separator, elements consisting only of copies
|
|
of the separator are ignored.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated string that must be freed with
|
|
g_free().</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="separator" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string used to separator the elements of the path.</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="first_element" transfer-ownership="none">
|
|
<doc xml:space="preserve">the first element in the path</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">remaining elements in path, terminated by %NULL</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="build_pathv" c:identifier="g_build_pathv" version="2.8">
|
|
<doc xml:space="preserve">Behaves exactly like g_build_path(), but takes the path elements
|
|
as a string array, instead of varargs. This function is mainly
|
|
meant for language bindings.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated string that must be freed
|
|
with g_free().</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="separator" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string used to separator the elements of the path.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="args" transfer-ownership="none">
|
|
<doc xml:space="preserve">%NULL-terminated
|
|
array of strings containing the path elements.</doc>
|
|
<array c:type="gchar**">
|
|
<type name="filename"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="byte_array_free" c:identifier="g_byte_array_free" moved-to="ByteArray.free">
|
|
<doc xml:space="preserve">Frees the memory allocated by the #GByteArray. If @free_segment is
|
|
%TRUE it frees the actual byte data. If the reference count of
|
|
@array is greater than one, the #GByteArray wrapper is preserved but
|
|
the size of @array will be set to zero.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the element data if @free_segment is %FALSE, otherwise
|
|
%NULL. The element data should be freed using g_free().</doc>
|
|
<type name="guint8" c:type="guint8*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="free_segment" transfer-ownership="none">
|
|
<doc xml:space="preserve">if %TRUE the actual byte data is freed as well</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="byte_array_free_to_bytes" c:identifier="g_byte_array_free_to_bytes" moved-to="ByteArray.free_to_bytes" version="2.32">
|
|
<doc xml:space="preserve">Transfers the data from the #GByteArray into a new immutable #GBytes.
|
|
|
|
The #GByteArray is freed unless the reference count of @array is greater
|
|
than one, the #GByteArray wrapper is preserved but the size of @array
|
|
will be set to zero.
|
|
|
|
This is identical to using g_bytes_new_take() and g_byte_array_free()
|
|
together.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new immutable #GBytes representing same
|
|
byte data that was in the array</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="full">
|
|
<doc xml:space="preserve">a #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="byte_array_new" c:identifier="g_byte_array_new" moved-to="ByteArray.new">
|
|
<doc xml:space="preserve">Creates a new #GByteArray with a reference count of 1.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the new #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
</function>
|
|
<function name="byte_array_new_take" c:identifier="g_byte_array_new_take" moved-to="ByteArray.new_take" version="2.32">
|
|
<doc xml:space="preserve">Create byte array containing the data. The data will be owned by the array
|
|
and will be freed with g_free(), i.e. it could be allocated using g_strdup().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="data" transfer-ownership="full">
|
|
<doc xml:space="preserve">byte data for the array</doc>
|
|
<array length="1" zero-terminated="0" c:type="guint8*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @data</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="byte_array_steal" c:identifier="g_byte_array_steal" moved-to="ByteArray.steal" version="2.64">
|
|
<doc xml:space="preserve">Frees the data in the array and resets the size to zero, while
|
|
the underlying array is preserved for use elsewhere and returned
|
|
to the caller.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the element data, which should be
|
|
freed using g_free().</doc>
|
|
<type name="guint8" c:type="guint8*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GByteArray.</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="len" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">pointer to retrieve the number of
|
|
elements of the original array</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="byte_array_unref" c:identifier="g_byte_array_unref" moved-to="ByteArray.unref" version="2.22">
|
|
<doc xml:space="preserve">Atomically decrements the reference count of @array by one. If the
|
|
reference count drops to 0, all memory allocated by the array is
|
|
released. This function is thread-safe and may be called from any
|
|
thread.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="array" transfer-ownership="none">
|
|
<doc xml:space="preserve">A #GByteArray</doc>
|
|
<array name="GLib.ByteArray" c:type="GByteArray*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="byte_order">
|
|
<doc xml:space="preserve">These macros provide a portable way to determine the host byte order
|
|
and to convert values between different byte orders.
|
|
|
|
The byte order is the order in which bytes are stored to create larger
|
|
data types such as the #gint and #glong values.
|
|
The host byte order is the byte order used on the current machine.
|
|
|
|
Some processors store the most significant bytes (i.e. the bytes that
|
|
hold the largest part of the value) first. These are known as big-endian
|
|
processors. Other processors (notably the x86 family) store the most
|
|
significant byte last. These are known as little-endian processors.
|
|
|
|
Finally, to complicate matters, some other processors store the bytes in
|
|
a rather curious order known as PDP-endian. For a 4-byte word, the 3rd
|
|
most significant byte is stored first, then the 4th, then the 1st and
|
|
finally the 2nd.
|
|
|
|
Obviously there is a problem when these different processors communicate
|
|
with each other, for example over networks or by using binary file formats.
|
|
This is where these macros come in. They are typically used to convert
|
|
values into a byte order which has been agreed on for use when
|
|
communicating between different processors. The Internet uses what is
|
|
known as 'network byte order' as the standard byte order (which is in
|
|
fact the big-endian byte order).
|
|
|
|
Note that the byte order conversion macros may evaluate their arguments
|
|
multiple times, thus you should not use them with arguments which have
|
|
side-effects.</doc>
|
|
</docsection>
|
|
<function name="canonicalize_filename" c:identifier="g_canonicalize_filename" version="2.58">
|
|
<doc xml:space="preserve">Gets the canonical file name from @filename. All triple slashes are turned into
|
|
single slashes, and all `..` and `.`s resolved against @relative_to.
|
|
|
|
Symlinks are not followed, and the returned path is guaranteed to be absolute.
|
|
|
|
If @filename is an absolute path, @relative_to is ignored. Otherwise,
|
|
@relative_to will be prepended to @filename to make it absolute. @relative_to
|
|
must be an absolute path, or %NULL. If @relative_to is %NULL, it'll fallback
|
|
to g_get_current_dir().
|
|
|
|
This function never fails, and will canonicalize file paths even if they don't
|
|
exist.
|
|
|
|
No file system I/O is done.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string with the
|
|
canonical file path</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="filename" transfer-ownership="none">
|
|
<doc xml:space="preserve">the name of the file</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="relative_to" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the relative directory, or %NULL
|
|
to use the current working directory</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="chdir" c:identifier="g_chdir" version="2.8">
|
|
<doc xml:space="preserve">A wrapper for the POSIX chdir() function. The function changes the
|
|
current directory of the process to @path.
|
|
|
|
See your C library manual for more details about chdir().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">0 on success, -1 if an error occurred.</doc>
|
|
<type name="gint" c:type="int"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="path" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pathname in the GLib file name encoding
|
|
(UTF-8 on Windows)</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="check_version" c:identifier="glib_check_version" version="2.6">
|
|
<doc xml:space="preserve">Checks that the GLib library in use is compatible with the
|
|
given version. Generally you would pass in the constants
|
|
#GLIB_MAJOR_VERSION, #GLIB_MINOR_VERSION, #GLIB_MICRO_VERSION
|
|
as the three arguments to this function; that produces
|
|
a check that the library in use is compatible with
|
|
the version of GLib the application or module was compiled
|
|
against.
|
|
|
|
Compatibility is defined by two things: first the version
|
|
of the running library is newer than the version
|
|
@required_major.required_minor.@required_micro. Second
|
|
the running library must be binary compatible with the
|
|
version @required_major.required_minor.@required_micro
|
|
(same major version.)</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%NULL if the GLib library is compatible with the
|
|
given version, or a string describing the version mismatch.
|
|
The returned string is owned by GLib and must not be modified
|
|
or freed.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="required_major" transfer-ownership="none">
|
|
<doc xml:space="preserve">the required major version</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="required_minor" transfer-ownership="none">
|
|
<doc xml:space="preserve">the required minor version</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="required_micro" transfer-ownership="none">
|
|
<doc xml:space="preserve">the required micro version</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="checkedmath">
|
|
<doc xml:space="preserve">GLib offers a set of macros for doing additions and multiplications
|
|
of unsigned integers, with checks for overflows.
|
|
|
|
The helpers all have three arguments. A pointer to the destination
|
|
is always the first argument and the operands to the operation are
|
|
the other two.
|
|
|
|
Following standard GLib convention, the helpers return %TRUE in case
|
|
of success (ie: no overflow).
|
|
|
|
The helpers may be macros, normal functions or inlines. They may be
|
|
implemented with inline assembly or compiler intrinsics where
|
|
available.</doc>
|
|
</docsection>
|
|
<docsection name="checksum">
|
|
<doc xml:space="preserve">GLib provides a generic API for computing checksums (or "digests")
|
|
for a sequence of arbitrary bytes, using various hashing algorithms
|
|
like MD5, SHA-1 and SHA-256. Checksums are commonly used in various
|
|
environments and specifications.
|
|
|
|
GLib supports incremental checksums using the GChecksum data
|
|
structure, by calling g_checksum_update() as long as there's data
|
|
available and then using g_checksum_get_string() or
|
|
g_checksum_get_digest() to compute the checksum and return it either
|
|
as a string in hexadecimal form, or as a raw sequence of bytes. To
|
|
compute the checksum for binary blobs and NUL-terminated strings in
|
|
one go, use the convenience functions g_compute_checksum_for_data()
|
|
and g_compute_checksum_for_string(), respectively.
|
|
|
|
Support for checksums has been added in GLib 2.16</doc>
|
|
</docsection>
|
|
<function name="checksum_type_get_length" c:identifier="g_checksum_type_get_length" moved-to="Checksum.type_get_length" version="2.16">
|
|
<doc xml:space="preserve">Gets the length in bytes of digests of type @checksum_type</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the checksum length, or -1 if @checksum_type is
|
|
not supported.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="checksum_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GChecksumType</doc>
|
|
<type name="ChecksumType" c:type="GChecksumType"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="child_watch_add" c:identifier="g_child_watch_add" shadowed-by="child_watch_add_full" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Sets a function to be called when the child indicated by @pid
|
|
exits, at a default priority, #G_PRIORITY_DEFAULT.
|
|
|
|
If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes()
|
|
you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to
|
|
the spawn function for the child watching to work.
|
|
|
|
Note that on platforms where #GPid must be explicitly closed
|
|
(see g_spawn_close_pid()) @pid must not be closed while the
|
|
source is still active. Typically, you will want to call
|
|
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
|
|
using g_source_attach(). You can do these steps manually if you
|
|
need greater control.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the ID (greater than 0) of the event source.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="pid" transfer-ownership="none">
|
|
<doc xml:space="preserve">process id to watch. On POSIX the positive pid of a child
|
|
process. On Windows a handle for a process (which doesn't have to be
|
|
a child).</doc>
|
|
<type name="Pid" c:type="GPid"/>
|
|
</parameter>
|
|
<parameter name="function" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">function to call</doc>
|
|
<type name="ChildWatchFunc" c:type="GChildWatchFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="child_watch_add_full" c:identifier="g_child_watch_add_full" shadows="child_watch_add" version="2.4">
|
|
<doc xml:space="preserve">Sets a function to be called when the child indicated by @pid
|
|
exits, at the priority @priority.
|
|
|
|
If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes()
|
|
you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to
|
|
the spawn function for the child watching to work.
|
|
|
|
In many programs, you will want to call g_spawn_check_exit_status()
|
|
in the callback to determine whether or not the child exited
|
|
successfully.
|
|
|
|
Also, note that on platforms where #GPid must be explicitly closed
|
|
(see g_spawn_close_pid()) @pid must not be closed while the source
|
|
is still active. Typically, you should invoke 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
|
|
using g_source_attach(). You can do these steps manually if you
|
|
need greater control.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the ID (greater than 0) of the event source.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="priority" transfer-ownership="none">
|
|
<doc xml:space="preserve">the priority of the idle source. Typically this will be in the
|
|
range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="pid" transfer-ownership="none">
|
|
<doc xml:space="preserve">process to watch. On POSIX the positive pid of a child process. On
|
|
Windows a handle for a process (which doesn't have to be a child).</doc>
|
|
<type name="Pid" c:type="GPid"/>
|
|
</parameter>
|
|
<parameter name="function" transfer-ownership="none" scope="notified" closure="3" destroy="4">
|
|
<doc xml:space="preserve">function to call</doc>
|
|
<type name="ChildWatchFunc" c:type="GChildWatchFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">function to call when the idle is removed, or %NULL</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="child_watch_source_new" c:identifier="g_child_watch_source_new" version="2.4">
|
|
<doc xml:space="preserve">Creates a new child_watch source.
|
|
|
|
The source will not initially be associated with any #GMainContext
|
|
and must be added to one with g_source_attach() before it will be
|
|
executed.
|
|
|
|
Note that child watch sources can only be used in conjunction with
|
|
`g_spawn...` when the %G_SPAWN_DO_NOT_REAP_CHILD flag is used.
|
|
|
|
Note that on platforms where #GPid must be explicitly closed
|
|
(see g_spawn_close_pid()) @pid must not be closed while the
|
|
source is still active. Typically, you will want to call
|
|
g_spawn_close_pid() in the callback function for the source.
|
|
|
|
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`.
|
|
|
|
Calling `waitpid` for specific processes other than @pid remains a
|
|
valid thing to do.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the newly-created child watch source</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="pid" transfer-ownership="none">
|
|
<doc xml:space="preserve">process to watch. On POSIX the positive pid of a child process. On
|
|
Windows a handle for a process (which doesn't have to be a child).</doc>
|
|
<type name="Pid" c:type="GPid"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="clear_error" c:identifier="g_clear_error" throws="1">
|
|
<doc xml:space="preserve">If @err or *@err is %NULL, does nothing. Otherwise,
|
|
calls g_error_free() on *@err and sets *@err to %NULL.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="clear_handle_id" c:identifier="g_clear_handle_id" version="2.56" introspectable="0">
|
|
<doc xml:space="preserve">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.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="tag_ptr" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to the handler ID</doc>
|
|
<type name="guint" c:type="guint*"/>
|
|
</parameter>
|
|
<parameter name="clear_func" transfer-ownership="none">
|
|
<doc xml:space="preserve">the function to call to clear the handler</doc>
|
|
<type name="ClearHandleFunc" c:type="GClearHandleFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="clear_list" c:identifier="g_clear_list" version="2.64" introspectable="0">
|
|
<doc xml:space="preserve">Clears a pointer to a #GList, freeing it and, optionally, freeing its elements using @destroy.
|
|
|
|
@list_ptr must be a valid pointer. If @list_ptr points to a null #GList, this does nothing.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="list_ptr" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GList return location</doc>
|
|
<type name="GLib.List" c:type="GList**">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">the function to pass to g_list_free_full() or %NULL to not free elements</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="clear_pointer" c:identifier="g_clear_pointer" version="2.34" introspectable="0">
|
|
<doc xml:space="preserve">Clears a reference to a variable.
|
|
|
|
@pp must not be %NULL.
|
|
|
|
If the reference is %NULL then this function does nothing.
|
|
Otherwise, the variable is destroyed using @destroy and the
|
|
pointer is set to %NULL.
|
|
|
|
A macro is also included that allows this function to be used without
|
|
pointer casts. This will mask any warnings about incompatible function types
|
|
or calling conventions, so you must ensure that your @destroy function is
|
|
compatible with being called as `GDestroyNotify` using the standard calling
|
|
convention for the platform that GLib was compiled for; otherwise the program
|
|
will experience undefined behaviour.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="pp" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a variable, struct member etc. holding a
|
|
pointer</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</parameter>
|
|
<parameter name="destroy" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">a function to which a gpointer can be passed, to destroy *@pp</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="clear_slist" c:identifier="g_clear_slist" version="2.64" introspectable="0">
|
|
<doc xml:space="preserve">Clears a pointer to a #GSList, freeing it and, optionally, freeing its elements using @destroy.
|
|
|
|
@slist_ptr must be a valid pointer. If @slist_ptr points to a null #GSList, this does nothing.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="slist_ptr" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSList return location</doc>
|
|
<type name="GLib.SList" c:type="GSList**">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">the function to pass to g_slist_free_full() or %NULL to not free elements</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="close" c:identifier="g_close" version="2.36" throws="1">
|
|
<doc xml:space="preserve">This wraps the close() call; in case of error, %errno will be
|
|
preserved, but the error will also be stored as a #GError in @error.
|
|
|
|
Besides using #GError, there is another major reason to prefer this
|
|
function over the call provided by the system; on Unix, it will
|
|
attempt to correctly handle %EINTR, which has platform-specific
|
|
semantics.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on success, %FALSE if there was an error.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">A file descriptor</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="compute_checksum_for_bytes" c:identifier="g_compute_checksum_for_bytes" version="2.34">
|
|
<doc xml:space="preserve">Computes the checksum for a binary @data. This is a
|
|
convenience wrapper for g_checksum_new(), g_checksum_get_string()
|
|
and g_checksum_free().
|
|
|
|
The hexadecimal string returned will be in lower case.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the digest of the binary data as a string in hexadecimal.
|
|
The returned string should be freed with g_free() when done using it.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="checksum_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GChecksumType</doc>
|
|
<type name="ChecksumType" c:type="GChecksumType"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none">
|
|
<doc xml:space="preserve">binary blob to compute the digest of</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="compute_checksum_for_data" c:identifier="g_compute_checksum_for_data" version="2.16">
|
|
<doc xml:space="preserve">Computes the checksum for a binary @data of @length. This is a
|
|
convenience wrapper for g_checksum_new(), g_checksum_get_string()
|
|
and g_checksum_free().
|
|
|
|
The hexadecimal string returned will be in lower case.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the digest of the binary data as a string in hexadecimal.
|
|
The returned string should be freed with g_free() when done using it.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="checksum_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GChecksumType</doc>
|
|
<type name="ChecksumType" c:type="GChecksumType"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none">
|
|
<doc xml:space="preserve">binary blob to compute the digest of</doc>
|
|
<array length="2" zero-terminated="0" c:type="const guchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @data</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="compute_checksum_for_string" c:identifier="g_compute_checksum_for_string" version="2.16">
|
|
<doc xml:space="preserve">Computes the checksum of a string.
|
|
|
|
The hexadecimal string returned will be in lower case.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the checksum as a hexadecimal string. The returned string
|
|
should be freed with g_free() when done using it.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="checksum_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GChecksumType</doc>
|
|
<type name="ChecksumType" c:type="GChecksumType"/>
|
|
</parameter>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to compute the checksum of</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the string, or -1 if the string is null-terminated.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="compute_hmac_for_bytes" c:identifier="g_compute_hmac_for_bytes" version="2.50">
|
|
<doc xml:space="preserve">Computes the HMAC for a binary @data. This is a
|
|
convenience wrapper for g_hmac_new(), g_hmac_get_string()
|
|
and g_hmac_unref().
|
|
|
|
The hexadecimal string returned will be in lower case.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the HMAC of the binary data as a string in hexadecimal.
|
|
The returned string should be freed with g_free() when done using it.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="digest_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GChecksumType to use for the HMAC</doc>
|
|
<type name="ChecksumType" c:type="GChecksumType"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">the key to use in the HMAC</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none">
|
|
<doc xml:space="preserve">binary blob to compute the HMAC of</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="compute_hmac_for_data" c:identifier="g_compute_hmac_for_data" version="2.30">
|
|
<doc xml:space="preserve">Computes the HMAC for a binary @data of @length. This is a
|
|
convenience wrapper for g_hmac_new(), g_hmac_get_string()
|
|
and g_hmac_unref().
|
|
|
|
The hexadecimal string returned will be in lower case.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the HMAC of the binary data as a string in hexadecimal.
|
|
The returned string should be freed with g_free() when done using it.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="digest_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GChecksumType to use for the HMAC</doc>
|
|
<type name="ChecksumType" c:type="GChecksumType"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">the key to use in the HMAC</doc>
|
|
<array length="2" zero-terminated="0" c:type="const guchar*">
|
|
<type name="guint8" c:type="guchar"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="key_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the key</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none">
|
|
<doc xml:space="preserve">binary blob to compute the HMAC of</doc>
|
|
<array length="4" zero-terminated="0" c:type="const guchar*">
|
|
<type name="guint8" c:type="guchar"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @data</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="compute_hmac_for_string" c:identifier="g_compute_hmac_for_string" version="2.30">
|
|
<doc xml:space="preserve">Computes the HMAC for a string.
|
|
|
|
The hexadecimal string returned will be in lower case.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the HMAC as a hexadecimal string.
|
|
The returned string should be freed with g_free()
|
|
when done using it.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="digest_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GChecksumType to use for the HMAC</doc>
|
|
<type name="ChecksumType" c:type="GChecksumType"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">the key to use in the HMAC</doc>
|
|
<array length="2" zero-terminated="0" c:type="const guchar*">
|
|
<type name="guint8" c:type="guchar"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="key_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the key</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to compute the HMAC for</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the string, or -1 if the string is nul-terminated</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="conversions">
|
|
<doc xml:space="preserve">The g_convert() family of function wraps the functionality of iconv().
|
|
In addition to pure character set conversions, GLib has functions to
|
|
deal with the extra complications of encodings for file names.
|
|
|
|
## File Name Encodings
|
|
|
|
Historically, UNIX has not had a defined encoding for file names:
|
|
a file name is valid as long as it does not have path separators
|
|
in it ("/"). However, displaying file names may require conversion:
|
|
from the character set in which they were created, to the character
|
|
set in which the application operates. Consider the Spanish file name
|
|
"Presentación.sxi". If the application which created it uses
|
|
ISO-8859-1 for its encoding,
|
|
|[
|
|
Character: P r e s e n t a c i ó n . s x i
|
|
Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
|
|
]|
|
|
However, if the application use UTF-8, the actual file name on
|
|
disk would look like this:
|
|
|[
|
|
Character: P r e s e n t a c i ó n . s x i
|
|
Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
|
|
]|
|
|
Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ that use
|
|
GLib do the same thing. If you get a file name from the file system,
|
|
for example, from readdir() or from g_dir_read_name(), and you wish
|
|
to display the file name to the user, you will need to convert it
|
|
into UTF-8. The opposite case is when the user types the name of a
|
|
file they wish to save: the toolkit will give you that string in
|
|
UTF-8 encoding, and you will need to convert it to the character
|
|
set used for file names before you can create the file with open()
|
|
or fopen().
|
|
|
|
By default, GLib assumes that file names on disk are in UTF-8
|
|
encoding. This is a valid assumption for file systems which
|
|
were created relatively recently: most applications use UTF-8
|
|
encoding for their strings, and that is also what they use for
|
|
the file names they create. However, older file systems may
|
|
still contain file names created in "older" encodings, such as
|
|
ISO-8859-1. In this case, for compatibility reasons, you may want
|
|
to instruct GLib to use that particular encoding for file names
|
|
rather than UTF-8. You can do this by specifying the encoding for
|
|
file names in the [`G_FILENAME_ENCODING`][G_FILENAME_ENCODING]
|
|
environment variable. For example, if your installation uses
|
|
ISO-8859-1 for file names, you can put this in your `~/.profile`:
|
|
|[
|
|
export G_FILENAME_ENCODING=ISO-8859-1
|
|
]|
|
|
GLib provides the functions g_filename_to_utf8() and
|
|
g_filename_from_utf8() to perform the necessary conversions.
|
|
These functions convert file names from the encoding specified
|
|
in `G_FILENAME_ENCODING` to UTF-8 and vice-versa. This
|
|
[diagram][file-name-encodings-diagram] illustrates how
|
|
these functions are used to convert between UTF-8 and the
|
|
encoding for file names in the file system.
|
|
|
|
## Conversion between file name encodings # {#file-name-encodings-diagram)
|
|
|
|
|
|
|
|
## Checklist for Application Writers
|
|
|
|
This section is a practical summary of the detailed
|
|
things to do to make sure your applications process file
|
|
name encodings correctly.
|
|
|
|
1. If you get a file name from the file system from a function
|
|
such as readdir() or gtk_file_chooser_get_filename(), you do
|
|
not need to do any conversion to pass that file name to
|
|
functions like open(), rename(), or fopen() -- those are "raw"
|
|
file names which the file system understands.
|
|
|
|
2. If you need to display a file name, convert it to UTF-8 first
|
|
by using g_filename_to_utf8(). If conversion fails, display a
|
|
string like "Unknown file name". Do not convert this string back
|
|
into the encoding used for file names if you wish to pass it to
|
|
the file system; use the original file name instead.
|
|
|
|
For example, the document window of a word processor could display
|
|
"Unknown file name" in its title bar but still let the user save
|
|
the file, as it would keep the raw file name internally. This
|
|
can happen if the user has not set the `G_FILENAME_ENCODING`
|
|
environment variable even though he has files whose names are
|
|
not encoded in UTF-8.
|
|
|
|
3. If your user interface lets the user type a file name for saving
|
|
or renaming, convert it to the encoding used for file names in
|
|
the file system by using g_filename_from_utf8(). Pass the converted
|
|
file name to functions like fopen(). If conversion fails, ask the
|
|
user to enter a different file name. This can happen if the user
|
|
types Japanese characters when `G_FILENAME_ENCODING` is set to
|
|
`ISO-8859-1`, for example.</doc>
|
|
</docsection>
|
|
<function name="convert" c:identifier="g_convert" throws="1">
|
|
<doc xml:space="preserve">Converts a string from one character set to another.
|
|
|
|
Note that you should use g_iconv() for streaming conversions.
|
|
Despite the fact that @bytes_read can return information about partial
|
|
characters, the g_convert_... functions are not generally suitable
|
|
for streaming. If the underlying converter maintains internal state,
|
|
then this won't be preserved across successive calls to g_convert(),
|
|
g_convert_with_iconv() or g_convert_with_fallback(). (An example of
|
|
this is the GNU C converter for CP1255 which does not emit a base
|
|
character until it knows that the next character is not a mark that
|
|
could combine with the base character.)
|
|
|
|
Using extensions such as "//TRANSLIT" may not work (or may not work
|
|
well) on many platforms. Consider using g_str_to_ascii() instead.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">
|
|
If the conversion was successful, a newly allocated buffer
|
|
containing the converted string, which must be freed with g_free().
|
|
Otherwise %NULL and @error will be set.</doc>
|
|
<array length="5" zero-terminated="0" c:type="gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">
|
|
the string to convert.</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the string in bytes, or -1 if the string is
|
|
nul-terminated (Note that some encodings may allow nul
|
|
bytes to occur inside strings. In that case, using -1
|
|
for the @len parameter is unsafe)</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="to_codeset" transfer-ownership="none">
|
|
<doc xml:space="preserve">name of character set into which to convert @str</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="from_codeset" transfer-ownership="none">
|
|
<doc xml:space="preserve">character set of @str.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store the number of bytes in
|
|
the input string that were successfully converted, or %NULL.
|
|
Even if the conversion was successful, this may be
|
|
less than @len if there were partial characters
|
|
at the end of the input. If the error
|
|
#G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
|
|
stored will be the byte offset after the last valid
|
|
input sequence.</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
<parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">the number of bytes stored in
|
|
the output buffer (not including the terminating nul).</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="convert_error_quark" c:identifier="g_convert_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="convert_with_fallback" c:identifier="g_convert_with_fallback" throws="1">
|
|
<doc xml:space="preserve">Converts a string from one character set to another, possibly
|
|
including fallback sequences for characters not representable
|
|
in the output. Note that it is not guaranteed that the specification
|
|
for the fallback sequences in @fallback will be honored. Some
|
|
systems may do an approximate conversion from @from_codeset
|
|
to @to_codeset in their iconv() functions,
|
|
in which case GLib will simply return that approximate conversion.
|
|
|
|
Note that you should use g_iconv() for streaming conversions.
|
|
Despite the fact that @bytes_read can return information about partial
|
|
characters, the g_convert_... functions are not generally suitable
|
|
for streaming. If the underlying converter maintains internal state,
|
|
then this won't be preserved across successive calls to g_convert(),
|
|
g_convert_with_iconv() or g_convert_with_fallback(). (An example of
|
|
this is the GNU C converter for CP1255 which does not emit a base
|
|
character until it knows that the next character is not a mark that
|
|
could combine with the base character.)</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">
|
|
If the conversion was successful, a newly allocated buffer
|
|
containing the converted string, which must be freed with g_free().
|
|
Otherwise %NULL and @error will be set.</doc>
|
|
<array length="6" zero-terminated="0" c:type="gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">
|
|
the string to convert.</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the string in bytes, or -1 if the string is
|
|
nul-terminated (Note that some encodings may allow nul
|
|
bytes to occur inside strings. In that case, using -1
|
|
for the @len parameter is unsafe)</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="to_codeset" transfer-ownership="none">
|
|
<doc xml:space="preserve">name of character set into which to convert @str</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="from_codeset" transfer-ownership="none">
|
|
<doc xml:space="preserve">character set of @str.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="fallback" transfer-ownership="none">
|
|
<doc xml:space="preserve">UTF-8 string to use in place of characters not
|
|
present in the target encoding. (The string must be
|
|
representable in the target encoding).
|
|
If %NULL, characters not in the target encoding will
|
|
be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store the number of bytes in
|
|
the input string that were successfully converted, or %NULL.
|
|
Even if the conversion was successful, this may be
|
|
less than @len if there were partial characters
|
|
at the end of the input.</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
<parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">the number of bytes stored in
|
|
the output buffer (not including the terminating nul).</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="convert_with_iconv" c:identifier="g_convert_with_iconv" introspectable="0" throws="1">
|
|
<doc xml:space="preserve">Converts a string from one character set to another.
|
|
|
|
Note that you should use g_iconv() for streaming conversions.
|
|
Despite the fact that @bytes_read can return information about partial
|
|
characters, the g_convert_... functions are not generally suitable
|
|
for streaming. If the underlying converter maintains internal state,
|
|
then this won't be preserved across successive calls to g_convert(),
|
|
g_convert_with_iconv() or g_convert_with_fallback(). (An example of
|
|
this is the GNU C converter for CP1255 which does not emit a base
|
|
character until it knows that the next character is not a mark that
|
|
could combine with the base character.)
|
|
|
|
Characters which are valid in the input character set, but which have no
|
|
representation in the output character set will result in a
|
|
%G_CONVERT_ERROR_ILLEGAL_SEQUENCE error. This is in contrast to the iconv()
|
|
specification, which leaves this behaviour implementation defined. Note that
|
|
this is the same error code as is returned for an invalid byte sequence in
|
|
the input character set. To get defined behaviour for conversion of
|
|
unrepresentable characters, use g_convert_with_fallback().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">
|
|
If the conversion was successful, a newly allocated buffer
|
|
containing the converted string, which must be freed with
|
|
g_free(). Otherwise %NULL and @error will be set.</doc>
|
|
<array length="4" zero-terminated="0" c:type="gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">
|
|
the string to convert.</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the string in bytes, or -1 if the string is
|
|
nul-terminated (Note that some encodings may allow nul
|
|
bytes to occur inside strings. In that case, using -1
|
|
for the @len parameter is unsafe)</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="converter" transfer-ownership="none">
|
|
<doc xml:space="preserve">conversion descriptor from g_iconv_open()</doc>
|
|
<type name="IConv" c:type="GIConv"/>
|
|
</parameter>
|
|
<parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store the number of bytes in
|
|
the input string that were successfully converted, or %NULL.
|
|
Even if the conversion was successful, this may be
|
|
less than @len if there were partial characters
|
|
at the end of the input. If the error
|
|
#G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
|
|
stored will be the byte offset after the last valid
|
|
input sequence.</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
<parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">the number of bytes stored in
|
|
the output buffer (not including the terminating nul).</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="datalist">
|
|
<doc xml:space="preserve">Keyed data lists provide lists of arbitrary data elements which can
|
|
be accessed either with a string or with a #GQuark corresponding to
|
|
the string.
|
|
|
|
The #GQuark methods are quicker, since the strings have to be
|
|
converted to #GQuarks anyway.
|
|
|
|
Data lists are used for associating arbitrary data with #GObjects,
|
|
using g_object_set_data() and related functions.
|
|
|
|
To create a datalist, use g_datalist_init().
|
|
|
|
To add data elements to a datalist use g_datalist_id_set_data(),
|
|
g_datalist_id_set_data_full(), g_datalist_set_data() and
|
|
g_datalist_set_data_full().
|
|
|
|
To get data elements from a datalist use g_datalist_id_get_data()
|
|
and g_datalist_get_data().
|
|
|
|
To iterate over all data elements in a datalist use
|
|
g_datalist_foreach() (not thread-safe).
|
|
|
|
To remove data elements from a datalist use
|
|
g_datalist_id_remove_data() and g_datalist_remove_data().
|
|
|
|
To remove all data elements from a datalist, use g_datalist_clear().</doc>
|
|
</docsection>
|
|
<function name="datalist_clear" c:identifier="g_datalist_clear" introspectable="0">
|
|
<doc xml:space="preserve">Frees all the data elements of the datalist.
|
|
The data elements' destroy functions are called
|
|
if they have been set.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="datalist" transfer-ownership="none">
|
|
<doc xml:space="preserve">a datalist.</doc>
|
|
<type name="Data" c:type="GData**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="datalist_foreach" c:identifier="g_datalist_foreach">
|
|
<doc xml:space="preserve">Calls the given function for each data element of the datalist. The
|
|
function is called with each data element's #GQuark id and data,
|
|
together with the given @user_data parameter. 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.
|
|
|
|
@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.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="datalist" transfer-ownership="none">
|
|
<doc xml:space="preserve">a datalist.</doc>
|
|
<type name="Data" c:type="GData**"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" scope="call" closure="2">
|
|
<doc xml:space="preserve">the function to call for each data element.</doc>
|
|
<type name="DataForeachFunc" c:type="GDataForeachFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to the function.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="datalist_get_data" c:identifier="g_datalist_get_data">
|
|
<doc xml:space="preserve">Gets a data element, using its string identifier. This is slower than
|
|
g_datalist_id_get_data() because it compares strings.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the data element, or %NULL if it
|
|
is not found.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="datalist" transfer-ownership="none">
|
|
<doc xml:space="preserve">a datalist.</doc>
|
|
<type name="Data" c:type="GData**"/>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string identifying a data element.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="datalist_get_flags" c:identifier="g_datalist_get_flags" version="2.8">
|
|
<doc xml:space="preserve">Gets flags values packed in together with the datalist.
|
|
See g_datalist_set_flags().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the flags of the datalist</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="datalist" transfer-ownership="none">
|
|
<doc xml:space="preserve">pointer to the location that holds a list</doc>
|
|
<type name="Data" c:type="GData**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="datalist_id_dup_data" c:identifier="g_datalist_id_dup_data" version="2.34" introspectable="0">
|
|
<doc xml:space="preserve">This is a variant of g_datalist_id_get_data() which
|
|
returns a 'duplicate' of the value. @dup_func defines the
|
|
meaning of 'duplicate' in this context, it could e.g.
|
|
take a reference on a ref-counted object.
|
|
|
|
If the @key_id is not set in the datalist then @dup_func
|
|
will be called with a %NULL argument.
|
|
|
|
Note that @dup_func is called while the datalist is locked, so it
|
|
is not allowed to read or modify the datalist.
|
|
|
|
This function can be useful to avoid races when multiple
|
|
threads are using the same datalist and the same key.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">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.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="datalist" transfer-ownership="none">
|
|
<doc xml:space="preserve">location of a datalist</doc>
|
|
<type name="Data" c:type="GData**"/>
|
|
</parameter>
|
|
<parameter name="key_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GQuark identifying a data element</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</parameter>
|
|
<parameter name="dup_func" transfer-ownership="none" nullable="1" allow-none="1" scope="call" closure="3">
|
|
<doc xml:space="preserve">function to duplicate the old value</doc>
|
|
<type name="DuplicateFunc" c:type="GDuplicateFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">passed as user_data to @dup_func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="datalist_id_get_data" c:identifier="g_datalist_id_get_data">
|
|
<doc xml:space="preserve">Retrieves the data element corresponding to @key_id.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the data element, or %NULL if
|
|
it is not found.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="datalist" transfer-ownership="none">
|
|
<doc xml:space="preserve">a datalist.</doc>
|
|
<type name="Data" c:type="GData**"/>
|
|
</parameter>
|
|
<parameter name="key_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GQuark identifying a data element.</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="datalist_id_remove_data" c:identifier="g_datalist_id_remove_data" introspectable="0">
|
|
<doc xml:space="preserve">Removes an element, using its #GQuark identifier.</doc>
|
|
<parameters>
|
|
<parameter name="dl">
|
|
<doc xml:space="preserve">a datalist.</doc>
|
|
</parameter>
|
|
<parameter name="q">
|
|
<doc xml:space="preserve">the #GQuark identifying the data element.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="datalist_id_remove_no_notify" c:identifier="g_datalist_id_remove_no_notify" introspectable="0">
|
|
<doc xml:space="preserve">Removes an element, without calling its destroy notification
|
|
function.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the data previously stored at @key_id,
|
|
or %NULL if none.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="datalist" transfer-ownership="none">
|
|
<doc xml:space="preserve">a datalist.</doc>
|
|
<type name="Data" c:type="GData**"/>
|
|
</parameter>
|
|
<parameter name="key_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GQuark identifying a data element.</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="datalist_id_replace_data" c:identifier="g_datalist_id_replace_data" version="2.34" introspectable="0">
|
|
<doc xml:space="preserve">Compares the member that is associated with @key_id in
|
|
@datalist to @oldval, and if they are the same, replace
|
|
@oldval with @newval.
|
|
|
|
This is like a typical atomic compare-and-exchange
|
|
operation, for a member of @datalist.
|
|
|
|
If the previous value was replaced then ownership of the
|
|
old value (@oldval) is passed to the caller, including
|
|
the registered destroy notify for it (passed out in @old_destroy).
|
|
Its up to the caller to free this as he wishes, which may
|
|
or may not include using @old_destroy as sometimes replacement
|
|
should not destroy the object in the normal way.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the existing value for @key_id was replaced
|
|
by @newval, %FALSE otherwise.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="datalist" transfer-ownership="none">
|
|
<doc xml:space="preserve">location of a datalist</doc>
|
|
<type name="Data" c:type="GData**"/>
|
|
</parameter>
|
|
<parameter name="key_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GQuark identifying a data element</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</parameter>
|
|
<parameter name="oldval" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the old value to compare against</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="newval" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the new value to replace it with</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="destroy" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">destroy notify for the new value</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
<parameter name="old_destroy" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">destroy notify for the existing value</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="datalist_id_set_data" c:identifier="g_datalist_id_set_data" introspectable="0">
|
|
<doc xml:space="preserve">Sets the data corresponding to the given #GQuark id. Any previous
|
|
data with the same key is removed, and its destroy function is
|
|
called.</doc>
|
|
<parameters>
|
|
<parameter name="dl">
|
|
<doc xml:space="preserve">a datalist.</doc>
|
|
</parameter>
|
|
<parameter name="q">
|
|
<doc xml:space="preserve">the #GQuark to identify the data element.</doc>
|
|
</parameter>
|
|
<parameter name="d">
|
|
<doc xml:space="preserve">the data element, or %NULL to remove any previous element
|
|
corresponding to @q.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="datalist_id_set_data_full" c:identifier="g_datalist_id_set_data_full" introspectable="0">
|
|
<doc xml:space="preserve">Sets the data corresponding to the given #GQuark id, and the
|
|
function to be called when the element is removed from the datalist.
|
|
Any previous data with the same key is removed, and its destroy
|
|
function is called.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="datalist" transfer-ownership="none">
|
|
<doc xml:space="preserve">a datalist.</doc>
|
|
<type name="Data" c:type="GData**"/>
|
|
</parameter>
|
|
<parameter name="key_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GQuark to identify the data element.</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data element or %NULL to remove any previous element
|
|
corresponding to @key_id.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="destroy_func" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">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
|
|
also be %NULL.</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="datalist_init" c:identifier="g_datalist_init" introspectable="0">
|
|
<doc xml:space="preserve">Resets the datalist to %NULL. It does not free any memory or call
|
|
any destroy functions.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="datalist" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a pointer to a datalist.</doc>
|
|
<type name="Data" c:type="GData**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="datalist_remove_data" c:identifier="g_datalist_remove_data" introspectable="0">
|
|
<doc xml:space="preserve">Removes an element using its string identifier. The data element's
|
|
destroy function is called if it has been set.</doc>
|
|
<parameters>
|
|
<parameter name="dl">
|
|
<doc xml:space="preserve">a datalist.</doc>
|
|
</parameter>
|
|
<parameter name="k">
|
|
<doc xml:space="preserve">the string identifying the data element.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="datalist_remove_no_notify" c:identifier="g_datalist_remove_no_notify" introspectable="0">
|
|
<doc xml:space="preserve">Removes an element, without calling its destroy notifier.</doc>
|
|
<parameters>
|
|
<parameter name="dl">
|
|
<doc xml:space="preserve">a datalist.</doc>
|
|
</parameter>
|
|
<parameter name="k">
|
|
<doc xml:space="preserve">the string identifying the data element.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="datalist_set_data" c:identifier="g_datalist_set_data" introspectable="0">
|
|
<doc xml:space="preserve">Sets the data element corresponding to the given string identifier.</doc>
|
|
<parameters>
|
|
<parameter name="dl">
|
|
<doc xml:space="preserve">a datalist.</doc>
|
|
</parameter>
|
|
<parameter name="k">
|
|
<doc xml:space="preserve">the string to identify the data element.</doc>
|
|
</parameter>
|
|
<parameter name="d">
|
|
<doc xml:space="preserve">the data element, or %NULL to remove any previous element
|
|
corresponding to @k.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="datalist_set_data_full" c:identifier="g_datalist_set_data_full" introspectable="0">
|
|
<doc xml:space="preserve">Sets the data element corresponding to the given string identifier,
|
|
and the function to be called when the data element is removed.</doc>
|
|
<parameters>
|
|
<parameter name="dl">
|
|
<doc xml:space="preserve">a datalist.</doc>
|
|
</parameter>
|
|
<parameter name="k">
|
|
<doc xml:space="preserve">the string to identify the data element.</doc>
|
|
</parameter>
|
|
<parameter name="d">
|
|
<doc xml:space="preserve">the data element, or %NULL to remove any previous element
|
|
corresponding to @k.</doc>
|
|
</parameter>
|
|
<parameter name="f">
|
|
<doc xml:space="preserve">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.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="datalist_set_flags" c:identifier="g_datalist_set_flags" version="2.8">
|
|
<doc xml:space="preserve">Turns on flag values for a data list. This function is used
|
|
to keep a small number of boolean flags in an object with
|
|
a data list without using any additional space. It is
|
|
not generally useful except in circumstances where space
|
|
is very tight. (It is used in the base #GObject type, for
|
|
example.)</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="datalist" transfer-ownership="none">
|
|
<doc xml:space="preserve">pointer to the location that holds a list</doc>
|
|
<type name="Data" c:type="GData**"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">the flags to turn on. The values of the flags are
|
|
restricted by %G_DATALIST_FLAGS_MASK (currently
|
|
3; giving two possible boolean flags).
|
|
A value for @flags that doesn't fit within the mask is
|
|
an error.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="datalist_unset_flags" c:identifier="g_datalist_unset_flags" version="2.8">
|
|
<doc xml:space="preserve">Turns off flag values for a data list. See g_datalist_unset_flags()</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="datalist" transfer-ownership="none">
|
|
<doc xml:space="preserve">pointer to the location that holds a list</doc>
|
|
<type name="Data" c:type="GData**"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">the flags to turn off. The values of the flags are
|
|
restricted by %G_DATALIST_FLAGS_MASK (currently
|
|
3: giving two possible boolean flags).
|
|
A value for @flags that doesn't fit within the mask is
|
|
an error.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="dataset_destroy" c:identifier="g_dataset_destroy">
|
|
<doc xml:space="preserve">Destroys the dataset, freeing all memory allocated, and calling any
|
|
destroy functions set for data elements.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dataset_location" transfer-ownership="none">
|
|
<doc xml:space="preserve">the location identifying the dataset.</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="dataset_foreach" c:identifier="g_dataset_foreach">
|
|
<doc xml:space="preserve">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 @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.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dataset_location" transfer-ownership="none">
|
|
<doc xml:space="preserve">the location identifying the dataset.</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" scope="call" closure="2">
|
|
<doc xml:space="preserve">the function to call for each data element.</doc>
|
|
<type name="DataForeachFunc" c:type="GDataForeachFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to the function.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="dataset_get_data" c:identifier="g_dataset_get_data" introspectable="0">
|
|
<doc xml:space="preserve">Gets the data element corresponding to a string.</doc>
|
|
<parameters>
|
|
<parameter name="l">
|
|
<doc xml:space="preserve">the location identifying the dataset.</doc>
|
|
</parameter>
|
|
<parameter name="k">
|
|
<doc xml:space="preserve">the string identifying the data element.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="dataset_id_get_data" c:identifier="g_dataset_id_get_data">
|
|
<doc xml:space="preserve">Gets the data element corresponding to a #GQuark.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the data element corresponding to
|
|
the #GQuark, or %NULL if it is not found.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dataset_location" transfer-ownership="none">
|
|
<doc xml:space="preserve">the location identifying the dataset.</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="key_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GQuark id to identify the data element.</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="dataset_id_remove_data" c:identifier="g_dataset_id_remove_data" introspectable="0">
|
|
<doc xml:space="preserve">Removes a data element from a dataset. The data element's destroy
|
|
function is called if it has been set.</doc>
|
|
<parameters>
|
|
<parameter name="l">
|
|
<doc xml:space="preserve">the location identifying the dataset.</doc>
|
|
</parameter>
|
|
<parameter name="k">
|
|
<doc xml:space="preserve">the #GQuark id identifying the data element.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="dataset_id_remove_no_notify" c:identifier="g_dataset_id_remove_no_notify" introspectable="0">
|
|
<doc xml:space="preserve">Removes an element, without calling its destroy notification
|
|
function.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the data previously stored at @key_id,
|
|
or %NULL if none.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dataset_location" transfer-ownership="none">
|
|
<doc xml:space="preserve">the location identifying the dataset.</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="key_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GQuark ID identifying the data element.</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="dataset_id_set_data" c:identifier="g_dataset_id_set_data" introspectable="0">
|
|
<doc xml:space="preserve">Sets the data element associated with the given #GQuark id. Any
|
|
previous data with the same key is removed, and its destroy function
|
|
is called.</doc>
|
|
<parameters>
|
|
<parameter name="l">
|
|
<doc xml:space="preserve">the location identifying the dataset.</doc>
|
|
</parameter>
|
|
<parameter name="k">
|
|
<doc xml:space="preserve">the #GQuark id to identify the data element.</doc>
|
|
</parameter>
|
|
<parameter name="d">
|
|
<doc xml:space="preserve">the data element.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="dataset_id_set_data_full" c:identifier="g_dataset_id_set_data_full" introspectable="0">
|
|
<doc xml:space="preserve">Sets the data element associated with the given #GQuark id, and also
|
|
the function to call when the data element is destroyed. Any
|
|
previous data with the same key is removed, and its destroy function
|
|
is called.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dataset_location" transfer-ownership="none">
|
|
<doc xml:space="preserve">the location identifying the dataset.</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="key_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GQuark id to identify the data element.</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data element.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="destroy_func" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">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.</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="dataset_remove_data" c:identifier="g_dataset_remove_data" introspectable="0">
|
|
<doc xml:space="preserve">Removes a data element corresponding to a string. Its destroy
|
|
function is called if it has been set.</doc>
|
|
<parameters>
|
|
<parameter name="l">
|
|
<doc xml:space="preserve">the location identifying the dataset.</doc>
|
|
</parameter>
|
|
<parameter name="k">
|
|
<doc xml:space="preserve">the string identifying the data element.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="dataset_remove_no_notify" c:identifier="g_dataset_remove_no_notify" introspectable="0">
|
|
<doc xml:space="preserve">Removes an element, without calling its destroy notifier.</doc>
|
|
<parameters>
|
|
<parameter name="l">
|
|
<doc xml:space="preserve">the location identifying the dataset.</doc>
|
|
</parameter>
|
|
<parameter name="k">
|
|
<doc xml:space="preserve">the string identifying the data element.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="dataset_set_data" c:identifier="g_dataset_set_data" introspectable="0">
|
|
<doc xml:space="preserve">Sets the data corresponding to the given string identifier.</doc>
|
|
<parameters>
|
|
<parameter name="l">
|
|
<doc xml:space="preserve">the location identifying the dataset.</doc>
|
|
</parameter>
|
|
<parameter name="k">
|
|
<doc xml:space="preserve">the string to identify the data element.</doc>
|
|
</parameter>
|
|
<parameter name="d">
|
|
<doc xml:space="preserve">the data element.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="dataset_set_data_full" c:identifier="g_dataset_set_data_full" introspectable="0">
|
|
<doc xml:space="preserve">Sets the data corresponding to the given string identifier, and the
|
|
function to call when the data element is destroyed.</doc>
|
|
<parameters>
|
|
<parameter name="l">
|
|
<doc xml:space="preserve">the location identifying the dataset.</doc>
|
|
</parameter>
|
|
<parameter name="k">
|
|
<doc xml:space="preserve">the string to identify the data element.</doc>
|
|
</parameter>
|
|
<parameter name="d">
|
|
<doc xml:space="preserve">the data element.</doc>
|
|
</parameter>
|
|
<parameter name="f">
|
|
<doc xml:space="preserve">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.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<docsection name="datasets">
|
|
<doc xml:space="preserve">Datasets associate groups of data elements with particular memory
|
|
locations. These are useful if you need to associate data with a
|
|
structure returned from an external library. Since you cannot modify
|
|
the structure, you use its location in memory as the key into a
|
|
dataset, where you can associate any number of data elements with it.
|
|
|
|
There are two forms of most of the dataset functions. The first form
|
|
uses strings to identify the data elements associated with a
|
|
location. The second form uses #GQuark identifiers, which are
|
|
created with a call to g_quark_from_string() or
|
|
g_quark_from_static_string(). The second form is quicker, since it
|
|
does not require looking up the string in the hash table of #GQuark
|
|
identifiers.
|
|
|
|
There is no function to create a dataset. It is automatically
|
|
created as soon as you add elements to it.
|
|
|
|
To add data elements to a dataset use g_dataset_id_set_data(),
|
|
g_dataset_id_set_data_full(), g_dataset_set_data() and
|
|
g_dataset_set_data_full().
|
|
|
|
To get data elements from a dataset use g_dataset_id_get_data() and
|
|
g_dataset_get_data().
|
|
|
|
To iterate over all data elements in a dataset use
|
|
g_dataset_foreach() (not thread-safe).
|
|
|
|
To remove data elements from a dataset use
|
|
g_dataset_id_remove_data() and g_dataset_remove_data().
|
|
|
|
To destroy a dataset, use g_dataset_destroy().</doc>
|
|
</docsection>
|
|
<docsection name="date">
|
|
<doc xml:space="preserve">The #GDate data structure represents a day between January 1, Year 1,
|
|
and sometime a few thousand years in the future (right now it will go
|
|
to the year 65535 or so, but g_date_set_parse() only parses up to the
|
|
year 8000 or so - just count on "a few thousand"). #GDate is meant to
|
|
represent everyday dates, not astronomical dates or historical dates
|
|
or ISO timestamps or the like. It extrapolates the current Gregorian
|
|
calendar forward and backward in time; there is no attempt to change
|
|
the calendar to match time periods or locations. #GDate does not store
|
|
time information; it represents a day.
|
|
|
|
The #GDate implementation has several nice features; it is only a
|
|
64-bit struct, so storing large numbers of dates is very efficient. It
|
|
can keep both a Julian and day-month-year representation of the date,
|
|
since some calculations are much easier with one representation or the
|
|
other. A Julian representation is simply a count of days since some
|
|
fixed day in the past; for #GDate the fixed day is January 1, 1 AD.
|
|
("Julian" dates in the #GDate API aren't really Julian dates in the
|
|
technical sense; technically, Julian dates count from the start of the
|
|
Julian period, Jan 1, 4713 BC).
|
|
|
|
#GDate is simple to use. First you need a "blank" date; you can get a
|
|
dynamically allocated date from g_date_new(), or you can declare an
|
|
automatic variable or array and initialize it by
|
|
calling g_date_clear(). A cleared date is safe; it's safe to call
|
|
g_date_set_dmy() and the other mutator functions to initialize the
|
|
value of a cleared date. However, a cleared date is initially
|
|
invalid, meaning that it doesn't represent a day that exists.
|
|
It is undefined to call any of the date calculation routines on an
|
|
invalid date. If you obtain a date from a user or other
|
|
unpredictable source, you should check its validity with the
|
|
g_date_valid() predicate. g_date_valid() is also used to check for
|
|
errors with g_date_set_parse() and other functions that can
|
|
fail. Dates can be invalidated by calling g_date_clear() again.
|
|
|
|
It is very important to use the API to access the #GDate
|
|
struct. Often only the day-month-year or only the Julian
|
|
representation is valid. Sometimes neither is valid. Use the API.
|
|
|
|
GLib also features #GDateTime which represents a precise time.</doc>
|
|
</docsection>
|
|
<function name="date_get_days_in_month" c:identifier="g_date_get_days_in_month" moved-to="Date.get_days_in_month">
|
|
<doc xml:space="preserve">Returns the number of days in a month, taking leap
|
|
years into account.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">number of days in @month during the @year</doc>
|
|
<type name="guint8" c:type="guint8"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="month" transfer-ownership="none">
|
|
<doc xml:space="preserve">month</doc>
|
|
<type name="DateMonth" c:type="GDateMonth"/>
|
|
</parameter>
|
|
<parameter name="year" transfer-ownership="none">
|
|
<doc xml:space="preserve">year</doc>
|
|
<type name="DateYear" c:type="GDateYear"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="date_get_monday_weeks_in_year" c:identifier="g_date_get_monday_weeks_in_year" moved-to="Date.get_monday_weeks_in_year">
|
|
<doc xml:space="preserve">Returns the number of weeks in the year, where weeks
|
|
are taken to start on Monday. Will be 52 or 53. The
|
|
date must be valid. (Years always have 52 7-day periods,
|
|
plus 1 or 2 extra days depending on whether it's a leap
|
|
year. This function is basically telling you how many
|
|
Mondays are in the year, i.e. there are 53 Mondays if
|
|
one of the extra days happens to be a Monday.)</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">number of Mondays in the year</doc>
|
|
<type name="guint8" c:type="guint8"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="year" transfer-ownership="none">
|
|
<doc xml:space="preserve">a year</doc>
|
|
<type name="DateYear" c:type="GDateYear"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="date_get_sunday_weeks_in_year" c:identifier="g_date_get_sunday_weeks_in_year" moved-to="Date.get_sunday_weeks_in_year">
|
|
<doc xml:space="preserve">Returns the number of weeks in the year, where weeks
|
|
are taken to start on Sunday. Will be 52 or 53. The
|
|
date must be valid. (Years always have 52 7-day periods,
|
|
plus 1 or 2 extra days depending on whether it's a leap
|
|
year. This function is basically telling you how many
|
|
Sundays are in the year, i.e. there are 53 Sundays if
|
|
one of the extra days happens to be a Sunday.)</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of weeks in @year</doc>
|
|
<type name="guint8" c:type="guint8"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="year" transfer-ownership="none">
|
|
<doc xml:space="preserve">year to count weeks in</doc>
|
|
<type name="DateYear" c:type="GDateYear"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="date_is_leap_year" c:identifier="g_date_is_leap_year" moved-to="Date.is_leap_year">
|
|
<doc xml:space="preserve">Returns %TRUE if the year is a leap year.
|
|
|
|
For the purposes of this function, leap year is every year
|
|
divisible by 4 unless that year is divisible by 100. If it
|
|
is divisible by 100 it would be a leap year only if that year
|
|
is also divisible by 400.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the year is a leap year</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="year" transfer-ownership="none">
|
|
<doc xml:space="preserve">year to check</doc>
|
|
<type name="DateYear" c:type="GDateYear"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="date_strftime" c:identifier="g_date_strftime" moved-to="Date.strftime">
|
|
<doc xml:space="preserve">Generates a printed representation of the date, in a
|
|
[locale][setlocale]-specific way.
|
|
Works just like the platform's C library strftime() function,
|
|
but only accepts date-related formats; time-related formats
|
|
give undefined results. Date must be valid. Unlike strftime()
|
|
(which uses the locale encoding), works on a UTF-8 format
|
|
string and stores a UTF-8 result.
|
|
|
|
This function does not provide any conversion specifiers in
|
|
addition to those implemented by the platform's C library.
|
|
For example, don't expect that using g_date_strftime() would
|
|
make the \%F provided by the C99 strftime() work on Windows
|
|
where the C library only complies to C89.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">number of characters written to the buffer, or 0 the buffer was too small</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="s" transfer-ownership="none">
|
|
<doc xml:space="preserve">destination buffer</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="slen" transfer-ownership="none">
|
|
<doc xml:space="preserve">buffer size</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">format string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="date" transfer-ownership="none">
|
|
<doc xml:space="preserve">valid #GDate</doc>
|
|
<type name="Date" c:type="const GDate*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="date_time_compare" c:identifier="g_date_time_compare" moved-to="DateTime.compare" version="2.26">
|
|
<doc xml:space="preserve">A comparison function for #GDateTimes that is suitable
|
|
as a #GCompareFunc. Both #GDateTimes must be non-%NULL.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">-1, 0 or 1 if @dt1 is less than, equal to or greater
|
|
than @dt2.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dt1" transfer-ownership="none">
|
|
<doc xml:space="preserve">first #GDateTime to compare</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="dt2" transfer-ownership="none">
|
|
<doc xml:space="preserve">second #GDateTime to compare</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="date_time_equal" c:identifier="g_date_time_equal" moved-to="DateTime.equal" version="2.26">
|
|
<doc xml:space="preserve">Checks to see if @dt1 and @dt2 are equal.
|
|
|
|
Equal here means that they represent the same moment after converting
|
|
them to the same time zone.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @dt1 and @dt2 are equal</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dt1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="dt2" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="date_time_hash" c:identifier="g_date_time_hash" moved-to="DateTime.hash" version="2.26">
|
|
<doc xml:space="preserve">Hashes @datetime into a #guint, suitable for use within #GHashTable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #guint containing the hash</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="datetime" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GDateTime</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="date_valid_day" c:identifier="g_date_valid_day" moved-to="Date.valid_day">
|
|
<doc xml:space="preserve">Returns %TRUE if the day of the month is valid (a day is valid if it's
|
|
between 1 and 31 inclusive).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the day is valid</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="day" transfer-ownership="none">
|
|
<doc xml:space="preserve">day to check</doc>
|
|
<type name="DateDay" c:type="GDateDay"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="date_valid_dmy" c:identifier="g_date_valid_dmy" moved-to="Date.valid_dmy">
|
|
<doc xml:space="preserve">Returns %TRUE if the day-month-year triplet forms a valid, existing day
|
|
in the range of days #GDate understands (Year 1 or later, no more than
|
|
a few thousand years in the future).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the date is a valid one</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="day" transfer-ownership="none">
|
|
<doc xml:space="preserve">day</doc>
|
|
<type name="DateDay" c:type="GDateDay"/>
|
|
</parameter>
|
|
<parameter name="month" transfer-ownership="none">
|
|
<doc xml:space="preserve">month</doc>
|
|
<type name="DateMonth" c:type="GDateMonth"/>
|
|
</parameter>
|
|
<parameter name="year" transfer-ownership="none">
|
|
<doc xml:space="preserve">year</doc>
|
|
<type name="DateYear" c:type="GDateYear"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="date_valid_julian" c:identifier="g_date_valid_julian" moved-to="Date.valid_julian">
|
|
<doc xml:space="preserve">Returns %TRUE if the Julian day is valid. Anything greater than zero
|
|
is basically a valid Julian, though there is a 32-bit limit.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the Julian day is valid</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="julian_date" transfer-ownership="none">
|
|
<doc xml:space="preserve">Julian day to check</doc>
|
|
<type name="guint32" c:type="guint32"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="date_valid_month" c:identifier="g_date_valid_month" moved-to="Date.valid_month">
|
|
<doc xml:space="preserve">Returns %TRUE if the month value is valid. The 12 #GDateMonth
|
|
enumeration values are the only valid months.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the month is valid</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="month" transfer-ownership="none">
|
|
<doc xml:space="preserve">month</doc>
|
|
<type name="DateMonth" c:type="GDateMonth"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="date_valid_weekday" c:identifier="g_date_valid_weekday" moved-to="Date.valid_weekday">
|
|
<doc xml:space="preserve">Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration
|
|
values are the only valid weekdays.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the weekday is valid</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="weekday" transfer-ownership="none">
|
|
<doc xml:space="preserve">weekday</doc>
|
|
<type name="DateWeekday" c:type="GDateWeekday"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="date_valid_year" c:identifier="g_date_valid_year" moved-to="Date.valid_year">
|
|
<doc xml:space="preserve">Returns %TRUE if the year is valid. Any year greater than 0 is valid,
|
|
though there is a 16-bit limit to what #GDate will understand.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the year is valid</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="year" transfer-ownership="none">
|
|
<doc xml:space="preserve">year</doc>
|
|
<type name="DateYear" c:type="GDateYear"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="datetime">
|
|
<doc xml:space="preserve">#GDateTime is a structure that combines a Gregorian date and time
|
|
into a single structure. It provides many conversion and methods to
|
|
manipulate dates and times. Time precision is provided down to
|
|
microseconds and the time can range (proleptically) from 0001-01-01
|
|
00:00:00 to 9999-12-31 23:59:59.999999. #GDateTime follows POSIX
|
|
time in the sense that it is oblivious to leap seconds.
|
|
|
|
#GDateTime is an immutable object; once it has been created it cannot
|
|
be modified further. All modifiers will create a new #GDateTime.
|
|
Nearly all such functions can fail due to the date or time going out
|
|
of range, in which case %NULL will be returned.
|
|
|
|
#GDateTime is reference counted: the reference count is increased by calling
|
|
g_date_time_ref() and decreased by calling g_date_time_unref(). When the
|
|
reference count drops to 0, the resources allocated by the #GDateTime
|
|
structure are released.
|
|
|
|
Many parts of the API may produce non-obvious results. As an
|
|
example, adding two months to January 31st will yield March 31st
|
|
whereas adding one month and then one month again will yield either
|
|
March 28th or March 29th. Also note that adding 24 hours is not
|
|
always the same as adding one day (since days containing daylight
|
|
savings time transitions are either 23 or 25 hours in length).
|
|
|
|
#GDateTime is available since GLib 2.26.</doc>
|
|
</docsection>
|
|
<function name="dcgettext" c:identifier="g_dcgettext" version="2.26">
|
|
<doc xml:space="preserve">This is a variant of g_dgettext() that allows specifying a locale
|
|
category instead of always using `LC_MESSAGES`. See g_dgettext() for
|
|
more information about how this functions differs from calling
|
|
dcgettext() directly.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the translated string for the given locale category</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="domain" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the translation domain to use, or %NULL to use
|
|
the domain set with textdomain()</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="msgid" transfer-ownership="none">
|
|
<doc xml:space="preserve">message to translate</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="category" transfer-ownership="none">
|
|
<doc xml:space="preserve">a locale category</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="dgettext" c:identifier="g_dgettext" version="2.18">
|
|
<doc xml:space="preserve">This function is a wrapper of dgettext() which does not translate
|
|
the message if the default domain as set with textdomain() has no
|
|
translations for the current locale.
|
|
|
|
The advantage of using this function over dgettext() proper is that
|
|
libraries using this function (like GTK+) will not use translations
|
|
if the application using the library does not have translations for
|
|
the current locale. This results in a consistent English-only
|
|
interface instead of one having partial translations. For this
|
|
feature to work, the call to textdomain() and setlocale() should
|
|
precede any g_dgettext() invocations. For GTK+, it means calling
|
|
textdomain() before gtk_init or its variants.
|
|
|
|
This function disables translations if and only if upon its first
|
|
call all the following conditions hold:
|
|
|
|
- @domain is not %NULL
|
|
|
|
- textdomain() has been called to set a default text domain
|
|
|
|
- there is no translations available for the default text domain
|
|
and the current locale
|
|
|
|
- current locale is not "C" or any English locales (those
|
|
starting with "en_")
|
|
|
|
Note that this behavior may not be desired for example if an application
|
|
has its untranslated messages in a language other than English. In those
|
|
cases the application should call textdomain() after initializing GTK+.
|
|
|
|
Applications should normally not use this function directly,
|
|
but use the _() macro for translations.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">The translated string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="domain" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the translation domain to use, or %NULL to use
|
|
the domain set with textdomain()</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="msgid" transfer-ownership="none">
|
|
<doc xml:space="preserve">message to translate</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="dir_make_tmp" c:identifier="g_dir_make_tmp" moved-to="Dir.make_tmp" version="2.30" throws="1">
|
|
<doc xml:space="preserve">Creates a subdirectory in the preferred directory for temporary
|
|
files (as returned by g_get_tmp_dir()).
|
|
|
|
@tmpl should be a string in the GLib file name encoding containing
|
|
a sequence of six 'X' characters, as the parameter to g_mkstemp().
|
|
However, unlike these functions, the template should only be a
|
|
basename, no directory components are allowed. If template is
|
|
%NULL, a default template is used.
|
|
|
|
Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not
|
|
modified, and might thus be a read-only literal string.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">The actual name used. This string
|
|
should be freed with g_free() when not needed any longer and is
|
|
is in the GLib file name encoding. In case of errors, %NULL is
|
|
returned and @error will be set.</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="tmpl" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">Template for directory name,
|
|
as in g_mkdtemp(), basename only, or %NULL for a default template</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="direct_equal" c:identifier="g_direct_equal">
|
|
<doc xml:space="preserve">Compares two #gpointer arguments and returns %TRUE if they are equal.
|
|
It can be passed to g_hash_table_new() as the @key_equal_func
|
|
parameter, when using opaque pointers compared by pointer value as
|
|
keys in a #GHashTable.
|
|
|
|
This equality function is also appropriate for keys that are integers
|
|
stored in pointers, such as `GINT_TO_POINTER (n)`.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the two keys match.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="v1" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="v2" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a key to compare with @v1</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="direct_hash" c:identifier="g_direct_hash">
|
|
<doc xml:space="preserve">Converts a gpointer to a hash value.
|
|
It can be passed to g_hash_table_new() as the @hash_func parameter,
|
|
when using opaque pointers compared by pointer value as keys in a
|
|
#GHashTable.
|
|
|
|
This hash function is also appropriate for keys that are integers
|
|
stored in pointers, such as `GINT_TO_POINTER (n)`.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a hash value corresponding to the key.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="v" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #gpointer key</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="dngettext" c:identifier="g_dngettext" version="2.18">
|
|
<doc xml:space="preserve">This function is a wrapper of dngettext() which does not translate
|
|
the message if the default domain as set with textdomain() has no
|
|
translations for the current locale.
|
|
|
|
See g_dgettext() for details of how this differs from dngettext()
|
|
proper.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">The translated string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="domain" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the translation domain to use, or %NULL to use
|
|
the domain set with textdomain()</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="msgid" transfer-ownership="none">
|
|
<doc xml:space="preserve">message to translate</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="msgid_plural" transfer-ownership="none">
|
|
<doc xml:space="preserve">plural form of the message</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">the quantity for which translation is needed</doc>
|
|
<type name="gulong" c:type="gulong"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="double_equal" c:identifier="g_double_equal" version="2.22">
|
|
<doc xml:space="preserve">Compares the two #gdouble values being pointed to and returns
|
|
%TRUE if they are equal.
|
|
It can be passed to g_hash_table_new() as the @key_equal_func
|
|
parameter, when using non-%NULL pointers to doubles as keys in a
|
|
#GHashTable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the two keys match.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="v1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gdouble key</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="v2" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gdouble key to compare with @v1</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="double_hash" c:identifier="g_double_hash" version="2.22">
|
|
<doc xml:space="preserve">Converts a pointer to a #gdouble to a hash value.
|
|
It can be passed to g_hash_table_new() as the @hash_func parameter,
|
|
It can be passed to g_hash_table_new() as the @hash_func parameter,
|
|
when using non-%NULL pointers to doubles as keys in a #GHashTable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a hash value corresponding to the key.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="v" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gdouble key</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="dpgettext" c:identifier="g_dpgettext" version="2.16">
|
|
<doc xml:space="preserve">This function is a variant of g_dgettext() which supports
|
|
a disambiguating message context. GNU gettext uses the
|
|
'\004' character to separate the message context and
|
|
message id in @msgctxtid.
|
|
If 0 is passed as @msgidoffset, this function will fall back to
|
|
trying to use the deprecated convention of using "|" as a separation
|
|
character.
|
|
|
|
This uses g_dgettext() internally. See that functions for differences
|
|
with dgettext() proper.
|
|
|
|
Applications should normally not use this function directly,
|
|
but use the C_() macro for translations with context.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">The translated string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="domain" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the translation domain to use, or %NULL to use
|
|
the domain set with textdomain()</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="msgctxtid" transfer-ownership="none">
|
|
<doc xml:space="preserve">a combined message context and message id, separated
|
|
by a \004 character</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="msgidoffset" transfer-ownership="none">
|
|
<doc xml:space="preserve">the offset of the message id in @msgctxid</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="dpgettext2" c:identifier="g_dpgettext2" version="2.18">
|
|
<doc xml:space="preserve">This function is a variant of g_dgettext() which supports
|
|
a disambiguating message context. GNU gettext uses the
|
|
'\004' character to separate the message context and
|
|
message id in @msgctxtid.
|
|
|
|
This uses g_dgettext() internally. See that functions for differences
|
|
with dgettext() proper.
|
|
|
|
This function differs from C_() in that it is not a macro and
|
|
thus you may use non-string-literals as context and msgid arguments.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">The translated string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="domain" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the translation domain to use, or %NULL to use
|
|
the domain set with textdomain()</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="context" transfer-ownership="none">
|
|
<doc xml:space="preserve">the message context</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="msgid" transfer-ownership="none">
|
|
<doc xml:space="preserve">the message</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="environ_getenv" c:identifier="g_environ_getenv" version="2.32">
|
|
<doc xml:space="preserve">Returns the value of the environment variable @variable in the
|
|
provided list @envp.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">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.</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="envp" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">
|
|
an environment list (eg, as returned from g_get_environ()), or %NULL
|
|
for an empty environment list</doc>
|
|
<array c:type="gchar**">
|
|
<type name="filename"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="variable" transfer-ownership="none">
|
|
<doc xml:space="preserve">the environment variable to get</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="environ_setenv" c:identifier="g_environ_setenv" version="2.32">
|
|
<doc xml:space="preserve">Sets the environment variable @variable in the provided list
|
|
@envp to @value.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">
|
|
the updated environment list. Free it using g_strfreev().</doc>
|
|
<array c:type="gchar**">
|
|
<type name="filename"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="envp" transfer-ownership="full" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">
|
|
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</doc>
|
|
<array c:type="gchar**">
|
|
<type name="filename"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="variable" transfer-ownership="none">
|
|
<doc xml:space="preserve">the environment variable to set, must not
|
|
contain '='</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">the value for to set the variable to</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="overwrite" transfer-ownership="none">
|
|
<doc xml:space="preserve">whether to change the variable if it already exists</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="environ_unsetenv" c:identifier="g_environ_unsetenv" version="2.32">
|
|
<doc xml:space="preserve">Removes the environment variable @variable from the provided
|
|
environment @envp.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">
|
|
the updated environment list. Free it using g_strfreev().</doc>
|
|
<array c:type="gchar**">
|
|
<type name="filename"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="envp" transfer-ownership="full" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">
|
|
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</doc>
|
|
<array c:type="gchar**">
|
|
<type name="filename"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="variable" transfer-ownership="none">
|
|
<doc xml:space="preserve">the environment variable to remove, must not
|
|
contain '='</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="error_reporting">
|
|
<doc xml:space="preserve">GLib provides a standard method of reporting errors from a called
|
|
function to the calling code. (This is the same problem solved by
|
|
exceptions in other languages.) It's important to understand that
|
|
this method is both a data type (the #GError struct) and a [set of
|
|
rules][gerror-rules]. If you use #GError incorrectly, then your code will not
|
|
properly interoperate with other code that uses #GError, and users
|
|
of your API will probably get confused. In most cases, [using #GError is
|
|
preferred over numeric error codes][gerror-comparison], but there are
|
|
situations where numeric error codes are useful for performance.
|
|
|
|
First and foremost: #GError should only be used to report recoverable
|
|
runtime errors, never to report programming errors. If the programmer
|
|
has screwed up, then you should use g_warning(), g_return_if_fail(),
|
|
g_assert(), g_error(), or some similar facility. (Incidentally,
|
|
remember that the g_error() function should only be used for
|
|
programming errors, it should not be used to print any error
|
|
reportable via #GError.)
|
|
|
|
Examples of recoverable runtime errors are "file not found" or
|
|
"failed to parse input." Examples of programming errors are "NULL
|
|
passed to strcmp()" or "attempted to free the same pointer twice."
|
|
These two kinds of errors are fundamentally different: runtime errors
|
|
should be handled or reported to the user, programming errors should
|
|
be eliminated by fixing the bug in the program. This is why most
|
|
functions in GLib and GTK+ do not use the #GError facility.
|
|
|
|
Functions that can fail take a return location for a #GError as their
|
|
last argument. On error, a new #GError instance will be allocated and
|
|
returned to the caller via this argument. For example:
|
|
|[<!-- language="C" -->
|
|
gboolean g_file_get_contents (const gchar *filename,
|
|
gchar **contents,
|
|
gsize *length,
|
|
GError **error);
|
|
]|
|
|
If you pass a non-%NULL value for the `error` argument, it should
|
|
point to a location where an error can be placed. For example:
|
|
|[<!-- language="C" -->
|
|
gchar *contents;
|
|
GError *err = NULL;
|
|
|
|
g_file_get_contents ("foo.txt", &contents, NULL, &err);
|
|
g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));
|
|
if (err != NULL)
|
|
{
|
|
// Report error to user, and free error
|
|
g_assert (contents == NULL);
|
|
fprintf (stderr, "Unable to read file: %s\n", err->message);
|
|
g_error_free (err);
|
|
}
|
|
else
|
|
{
|
|
// Use file contents
|
|
g_assert (contents != NULL);
|
|
}
|
|
]|
|
|
Note that `err != NULL` in this example is a reliable indicator
|
|
of whether g_file_get_contents() failed. Additionally,
|
|
g_file_get_contents() returns a boolean which
|
|
indicates whether it was successful.
|
|
|
|
Because g_file_get_contents() returns %FALSE on failure, if you
|
|
are only interested in whether it failed and don't need to display
|
|
an error message, you can pass %NULL for the @error argument:
|
|
|[<!-- language="C" -->
|
|
if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) // ignore errors
|
|
// no error occurred
|
|
;
|
|
else
|
|
// error
|
|
;
|
|
]|
|
|
|
|
The #GError object contains three fields: @domain indicates the module
|
|
the error-reporting function is located in, @code indicates the specific
|
|
error that occurred, and @message is a user-readable error message with
|
|
as many details as possible. Several functions are provided to deal
|
|
with an error received from a called function: g_error_matches()
|
|
returns %TRUE if the error matches a given domain and code,
|
|
g_propagate_error() copies an error into an error location (so the
|
|
calling function will receive it), and g_clear_error() clears an
|
|
error location by freeing the error and resetting the location to
|
|
%NULL. To display an error to the user, simply display the @message,
|
|
perhaps along with additional context known only to the calling
|
|
function (the file being opened, or whatever - though in the
|
|
g_file_get_contents() case, the @message already contains a filename).
|
|
|
|
Note, however, that many error messages are too technical to display to the
|
|
user in an application, so prefer to use g_error_matches() to categorize errors
|
|
from called functions, and build an appropriate error message for the context
|
|
within your application. Error messages from a #GError are more appropriate
|
|
to be printed in system logs or on the command line. They are typically
|
|
translated.
|
|
|
|
When implementing a function that can report errors, the basic
|
|
tool is g_set_error(). Typically, if a fatal error occurs you
|
|
want to g_set_error(), then return immediately. g_set_error()
|
|
does nothing if the error location passed to it is %NULL.
|
|
Here's an example:
|
|
|[<!-- language="C" -->
|
|
gint
|
|
foo_open_file (GError **error)
|
|
{
|
|
gint fd;
|
|
int saved_errno;
|
|
|
|
g_return_val_if_fail (error == NULL || *error == NULL, -1);
|
|
|
|
fd = open ("file.txt", O_RDONLY);
|
|
saved_errno = errno;
|
|
|
|
if (fd < 0)
|
|
{
|
|
g_set_error (error,
|
|
FOO_ERROR, // error domain
|
|
FOO_ERROR_BLAH, // error code
|
|
"Failed to open file: %s", // error message format string
|
|
g_strerror (saved_errno));
|
|
return -1;
|
|
}
|
|
else
|
|
return fd;
|
|
}
|
|
]|
|
|
|
|
Things are somewhat more complicated if you yourself call another
|
|
function that can report a #GError. If the sub-function indicates
|
|
fatal errors in some way other than reporting a #GError, such as
|
|
by returning %TRUE on success, you can simply do the following:
|
|
|[<!-- language="C" -->
|
|
gboolean
|
|
my_function_that_can_fail (GError **err)
|
|
{
|
|
g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
|
|
|
|
if (!sub_function_that_can_fail (err))
|
|
{
|
|
// assert that error was set by the sub-function
|
|
g_assert (err == NULL || *err != NULL);
|
|
return FALSE;
|
|
}
|
|
|
|
// otherwise continue, no error occurred
|
|
g_assert (err == NULL || *err == NULL);
|
|
}
|
|
]|
|
|
|
|
If the sub-function does not indicate errors other than by
|
|
reporting a #GError (or if its return value does not reliably indicate
|
|
errors) you need to create a temporary #GError
|
|
since the passed-in one may be %NULL. g_propagate_error() is
|
|
intended for use in this case.
|
|
|[<!-- language="C" -->
|
|
gboolean
|
|
my_function_that_can_fail (GError **err)
|
|
{
|
|
GError *tmp_error;
|
|
|
|
g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
|
|
|
|
tmp_error = NULL;
|
|
sub_function_that_can_fail (&tmp_error);
|
|
|
|
if (tmp_error != NULL)
|
|
{
|
|
// store tmp_error in err, if err != NULL,
|
|
// otherwise call g_error_free() on tmp_error
|
|
g_propagate_error (err, tmp_error);
|
|
return FALSE;
|
|
}
|
|
|
|
// otherwise continue, no error occurred
|
|
}
|
|
]|
|
|
|
|
Error pileups are always a bug. For example, this code is incorrect:
|
|
|[<!-- language="C" -->
|
|
gboolean
|
|
my_function_that_can_fail (GError **err)
|
|
{
|
|
GError *tmp_error;
|
|
|
|
g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
|
|
|
|
tmp_error = NULL;
|
|
sub_function_that_can_fail (&tmp_error);
|
|
other_function_that_can_fail (&tmp_error);
|
|
|
|
if (tmp_error != NULL)
|
|
{
|
|
g_propagate_error (err, tmp_error);
|
|
return FALSE;
|
|
}
|
|
}
|
|
]|
|
|
@tmp_error should be checked immediately after sub_function_that_can_fail(),
|
|
and either cleared or propagated upward. The rule is: after each error,
|
|
you must either handle the error, or return it to the calling function.
|
|
|
|
Note that passing %NULL for the error location is the equivalent
|
|
of handling an error by always doing nothing about it. So the
|
|
following code is fine, assuming errors in sub_function_that_can_fail()
|
|
are not fatal to my_function_that_can_fail():
|
|
|[<!-- language="C" -->
|
|
gboolean
|
|
my_function_that_can_fail (GError **err)
|
|
{
|
|
GError *tmp_error;
|
|
|
|
g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
|
|
|
|
sub_function_that_can_fail (NULL); // ignore errors
|
|
|
|
tmp_error = NULL;
|
|
other_function_that_can_fail (&tmp_error);
|
|
|
|
if (tmp_error != NULL)
|
|
{
|
|
g_propagate_error (err, tmp_error);
|
|
return FALSE;
|
|
}
|
|
}
|
|
]|
|
|
|
|
Note that passing %NULL for the error location ignores errors;
|
|
it's equivalent to
|
|
`try { sub_function_that_can_fail (); } catch (...) {}`
|
|
in C++. It does not mean to leave errors unhandled; it means
|
|
to handle them by doing nothing.
|
|
|
|
Error domains and codes are conventionally named as follows:
|
|
|
|
- The error domain is called <NAMESPACE>_<MODULE>_ERROR,
|
|
for example %G_SPAWN_ERROR or %G_THREAD_ERROR:
|
|
|[<!-- language="C" -->
|
|
#define G_SPAWN_ERROR g_spawn_error_quark ()
|
|
|
|
G_DEFINE_QUARK (g-spawn-error-quark, g_spawn_error)
|
|
]|
|
|
|
|
- The quark function for the error domain is called
|
|
<namespace>_<module>_error_quark,
|
|
for example g_spawn_error_quark() or g_thread_error_quark().
|
|
|
|
- The error codes are in an enumeration called
|
|
<Namespace><Module>Error;
|
|
for example, #GThreadError or #GSpawnError.
|
|
|
|
- Members of the error code enumeration are called
|
|
<NAMESPACE>_<MODULE>_ERROR_<CODE>,
|
|
for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN.
|
|
|
|
- If there's a "generic" or "unknown" error code for unrecoverable
|
|
errors it doesn't make sense to distinguish with specific codes,
|
|
it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED,
|
|
for example %G_SPAWN_ERROR_FAILED. In the case of error code
|
|
enumerations that may be extended in future releases, you should
|
|
generally not handle this error code explicitly, but should
|
|
instead treat any unrecognized error code as equivalent to
|
|
FAILED.
|
|
|
|
## Comparison of #GError and traditional error handling # {#gerror-comparison}
|
|
|
|
#GError has several advantages over traditional numeric error codes:
|
|
importantly, tools like
|
|
[gobject-introspection](https://developer.gnome.org/gi/stable/) understand
|
|
#GErrors and convert them to exceptions in bindings; the message includes
|
|
more information than just a code; and use of a domain helps prevent
|
|
misinterpretation of error codes.
|
|
|
|
#GError has disadvantages though: it requires a memory allocation, and
|
|
formatting the error message string has a performance overhead. This makes it
|
|
unsuitable for use in retry loops where errors are a common case, rather than
|
|
being unusual. For example, using %G_IO_ERROR_WOULD_BLOCK means hitting these
|
|
overheads in the normal control flow. String formatting overhead can be
|
|
eliminated by using g_set_error_literal() in some cases.
|
|
|
|
These performance issues can be compounded if a function wraps the #GErrors
|
|
returned by the functions it calls: this multiplies the number of allocations
|
|
and string formatting operations. This can be partially mitigated by using
|
|
g_prefix_error().
|
|
|
|
## Rules for use of #GError # {#gerror-rules}
|
|
|
|
Summary of rules for use of #GError:
|
|
|
|
- Do not report programming errors via #GError.
|
|
|
|
- The last argument of a function that returns an error should
|
|
be a location where a #GError can be placed (i.e. "#GError** error").
|
|
If #GError is used with varargs, the #GError** should be the last
|
|
argument before the "...".
|
|
|
|
- The caller may pass %NULL for the #GError** if they are not interested
|
|
in details of the exact error that occurred.
|
|
|
|
- If %NULL is passed for the #GError** argument, then errors should
|
|
not be returned to the caller, but your function should still
|
|
abort and return if an error occurs. That is, control flow should
|
|
not be affected by whether the caller wants to get a #GError.
|
|
|
|
- If a #GError is reported, then your function by definition had a
|
|
fatal failure and did not complete whatever it was supposed to do.
|
|
If the failure was not fatal, then you handled it and you should not
|
|
report it. If it was fatal, then you must report it and discontinue
|
|
whatever you were doing immediately.
|
|
|
|
- If a #GError is reported, out parameters are not guaranteed to
|
|
be set to any defined value.
|
|
|
|
- A #GError* must be initialized to %NULL before passing its address
|
|
to a function that can report errors.
|
|
|
|
- "Piling up" errors is always a bug. That is, if you assign a
|
|
new #GError to a #GError* that is non-%NULL, thus overwriting
|
|
the previous error, it indicates that you should have aborted
|
|
the operation instead of continuing. If you were able to continue,
|
|
you should have cleared the previous error with g_clear_error().
|
|
g_set_error() will complain if you pile up errors.
|
|
|
|
- By convention, if you return a boolean value indicating success
|
|
then %TRUE means success and %FALSE means failure. Avoid creating
|
|
functions which have a boolean return value and a GError parameter,
|
|
but where the boolean does something other than signal whether the
|
|
GError is set. Among other problems, it requires C callers to allocate
|
|
a temporary error. Instead, provide a "gboolean *" out parameter.
|
|
There are functions in GLib itself such as g_key_file_has_key() that
|
|
are deprecated because of this. If %FALSE is returned, the error must
|
|
be set to a non-%NULL value. One exception to this is that in situations
|
|
that are already considered to be undefined behaviour (such as when a
|
|
g_return_val_if_fail() check fails), the error need not be set.
|
|
Instead of checking separately whether the error is set, callers
|
|
should ensure that they do not provoke undefined behaviour, then
|
|
assume that the error will be set on failure.
|
|
|
|
- A %NULL return value is also frequently used to mean that an error
|
|
occurred. You should make clear in your documentation whether %NULL
|
|
is a valid return value in non-error cases; if %NULL is a valid value,
|
|
then users must check whether an error was returned to see if the
|
|
function succeeded.
|
|
|
|
- When implementing a function that can report errors, you may want
|
|
to add a check at the top of your function that the error return
|
|
location is either %NULL or contains a %NULL error (e.g.
|
|
`g_return_if_fail (error == NULL || *error == NULL);`).</doc>
|
|
</docsection>
|
|
<function name="file_error_from_errno" c:identifier="g_file_error_from_errno">
|
|
<doc xml:space="preserve">Gets a #GFileError constant based on the passed-in @err_no.
|
|
For example, if you pass in `EEXIST` this function returns
|
|
#G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably
|
|
assume that all #GFileError values will exist.
|
|
|
|
Normally a #GFileError value goes into a #GError returned
|
|
from a function that manipulates files. So you would use
|
|
g_file_error_from_errno() when constructing a #GError.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">#GFileError corresponding to the given @errno</doc>
|
|
<type name="FileError" c:type="GFileError"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="err_no" transfer-ownership="none">
|
|
<doc xml:space="preserve">an "errno" value</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="file_error_quark" c:identifier="g_file_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="file_get_contents" c:identifier="g_file_get_contents" throws="1">
|
|
<doc xml:space="preserve">Reads an entire file into allocated memory, with good error
|
|
checking.
|
|
|
|
If the call was successful, it returns %TRUE and sets @contents to the file
|
|
contents and @length to the length of the file contents in bytes. The string
|
|
stored in @contents will be nul-terminated, so for text files you can pass
|
|
%NULL for the @length argument. If the call was not successful, it returns
|
|
%FALSE and sets @error. The error domain is #G_FILE_ERROR. Possible error
|
|
codes are those in the #GFileError enumeration. In the error case,
|
|
@contents is set to %NULL and @length is set to zero.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on success, %FALSE if an error occurred</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="filename" transfer-ownership="none">
|
|
<doc xml:space="preserve">name of a file to read contents from, in the GLib file name encoding</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="contents" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">location to store an allocated string, use g_free() to free
|
|
the returned string</doc>
|
|
<array length="2" zero-terminated="0" c:type="gchar**">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">location to store length in bytes of the contents, or %NULL</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="file_open_tmp" c:identifier="g_file_open_tmp" throws="1">
|
|
<doc xml:space="preserve">Opens a file for writing in the preferred directory for temporary
|
|
files (as returned by g_get_tmp_dir()).
|
|
|
|
@tmpl should be a string in the GLib file name encoding containing
|
|
a sequence of six 'X' characters, as the parameter to g_mkstemp().
|
|
However, unlike these functions, the template should only be a
|
|
basename, no directory components are allowed. If template is
|
|
%NULL, a default template is used.
|
|
|
|
Note that in contrast to g_mkstemp() (and mkstemp()) @tmpl is not
|
|
modified, and might thus be a read-only literal string.
|
|
|
|
Upon success, and if @name_used is non-%NULL, the actual name used
|
|
is returned in @name_used. This string should be freed with g_free()
|
|
when not needed any longer. The returned name is in the GLib file
|
|
name encoding.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">A file handle (as from open()) to the file opened for
|
|
reading and writing. The file is opened in binary mode on platforms
|
|
where there is a difference. The file handle should be closed with
|
|
close(). In case of errors, -1 is returned and @error will be set.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="tmpl" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">Template for file name, as in
|
|
g_mkstemp(), basename only, or %NULL for a default template</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="name_used" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">location to store actual name used,
|
|
or %NULL</doc>
|
|
<type name="filename" c:type="gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="file_read_link" c:identifier="g_file_read_link" version="2.4" throws="1">
|
|
<doc xml:space="preserve">Reads the contents of the symbolic link @filename like the POSIX
|
|
readlink() function. The returned string is in the encoding used
|
|
for filenames. Use g_filename_to_utf8() to convert it to UTF-8.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">A newly-allocated string with the contents of
|
|
the symbolic link, or %NULL if an error occurred.</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="filename" transfer-ownership="none">
|
|
<doc xml:space="preserve">the symbolic link</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="file_set_contents" c:identifier="g_file_set_contents" version="2.8" throws="1">
|
|
<doc xml:space="preserve">Writes all of @contents to a file named @filename. This is a convenience
|
|
wrapper around calling g_file_set_contents() with `flags` set to
|
|
`G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING` and
|
|
`mode` set to `0666`.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on success, %FALSE if an error occurred</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="filename" transfer-ownership="none">
|
|
<doc xml:space="preserve">name of a file to write @contents to, in the GLib file name
|
|
encoding</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="contents" transfer-ownership="none">
|
|
<doc xml:space="preserve">string to write to the file</doc>
|
|
<array length="2" zero-terminated="0" c:type="const gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @contents, or -1 if @contents is a nul-terminated string</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="file_set_contents_full" c:identifier="g_file_set_contents_full" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Writes all of @contents to a file named @filename, with good error checking.
|
|
If a file called @filename already exists it will be overwritten.
|
|
|
|
@flags control the properties of the write operation: whether it’s atomic,
|
|
and what the tradeoff is between returning quickly or being resilient to
|
|
system crashes.
|
|
|
|
As this function performs file I/O, it is recommended to not call it anywhere
|
|
where blocking would cause problems, such as in the main loop of a graphical
|
|
application. In particular, if @flags has any value other than
|
|
%G_FILE_SET_CONTENTS_NONE then this function may call `fsync()`.
|
|
|
|
If %G_FILE_SET_CONTENTS_CONSISTENT is set in @flags, the operation is atomic
|
|
in the sense that it is first written to a temporary file which is then
|
|
renamed to the final name.
|
|
|
|
Notes:
|
|
|
|
- On UNIX, if @filename already exists hard links to @filename will break.
|
|
Also since the file is recreated, existing permissions, access control
|
|
lists, metadata etc. may be lost. If @filename is a symbolic link,
|
|
the link itself will be replaced, not the linked file.
|
|
|
|
- On UNIX, if @filename already exists and is non-empty, and if the system
|
|
supports it (via a journalling filesystem or equivalent), and if
|
|
%G_FILE_SET_CONTENTS_CONSISTENT is set in @flags, the `fsync()` call (or
|
|
equivalent) will be used to ensure atomic replacement: @filename
|
|
will contain either its old contents or @contents, even in the face of
|
|
system power loss, the disk being unsafely removed, etc.
|
|
|
|
- On UNIX, if @filename does not already exist or is empty, there is a
|
|
possibility that system power loss etc. after calling this function will
|
|
leave @filename empty or full of NUL bytes, depending on the underlying
|
|
filesystem, unless %G_FILE_SET_CONTENTS_DURABLE and
|
|
%G_FILE_SET_CONTENTS_CONSISTENT are set in @flags.
|
|
|
|
- On Windows renaming a file will not remove an existing file with the
|
|
new name, so on Windows there is a race condition between the existing
|
|
file being removed and the temporary file being renamed.
|
|
|
|
- On Windows there is no way to remove a file that is open to some
|
|
process, or mapped into memory. Thus, this function will fail if
|
|
@filename already exists and is open.
|
|
|
|
If the call was successful, it returns %TRUE. If the call was not successful,
|
|
it returns %FALSE and sets @error. The error domain is #G_FILE_ERROR.
|
|
Possible error codes are those in the #GFileError enumeration.
|
|
|
|
Note that the name for the temporary file is constructed by appending up
|
|
to 7 characters to @filename.
|
|
|
|
If the file didn’t exist before and is created, it will be given the
|
|
permissions from @mode. Otherwise, the permissions of the existing file may
|
|
be changed to @mode depending on @flags, or they may remain unchanged.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on success, %FALSE if an error occurred</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="filename" transfer-ownership="none">
|
|
<doc xml:space="preserve">name of a file to write @contents to, in the GLib file name
|
|
encoding</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="contents" transfer-ownership="none">
|
|
<doc xml:space="preserve">string to write to the file</doc>
|
|
<array length="2" zero-terminated="0" c:type="const gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @contents, or -1 if @contents is a nul-terminated string</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags controlling the safety vs speed of the operation</doc>
|
|
<type name="FileSetContentsFlags" c:type="GFileSetContentsFlags"/>
|
|
</parameter>
|
|
<parameter name="mode" transfer-ownership="none">
|
|
<doc xml:space="preserve">file mode, as passed to `open()`; typically this will be `0666`</doc>
|
|
<type name="gint" c:type="int"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="file_test" c:identifier="g_file_test">
|
|
<doc xml:space="preserve">Returns %TRUE if any of the tests in the bitfield @test are
|
|
%TRUE. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)`
|
|
will return %TRUE if the file exists; the check whether it's a
|
|
directory doesn't matter since the existence test is %TRUE. With
|
|
the current set of available tests, there's no point passing in
|
|
more than one test at a time.
|
|
|
|
Apart from %G_FILE_TEST_IS_SYMLINK all tests follow symbolic links,
|
|
so for a symbolic link to a regular file g_file_test() will return
|
|
%TRUE for both %G_FILE_TEST_IS_SYMLINK and %G_FILE_TEST_IS_REGULAR.
|
|
|
|
Note, that for a dangling symbolic link g_file_test() will return
|
|
%TRUE for %G_FILE_TEST_IS_SYMLINK and %FALSE for all other flags.
|
|
|
|
You should never use g_file_test() to test whether it is safe
|
|
to perform an operation, because there is always the possibility
|
|
of the condition changing before you actually perform the operation.
|
|
For example, you might think you could use %G_FILE_TEST_IS_SYMLINK
|
|
to know whether it is safe to write to a file without being
|
|
tricked into writing into a different location. It doesn't work!
|
|
|[<!-- language="C" -->
|
|
// DON'T DO THIS
|
|
if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK))
|
|
{
|
|
fd = g_open (filename, O_WRONLY);
|
|
// write to fd
|
|
}
|
|
]|
|
|
|
|
Another thing to note is that %G_FILE_TEST_EXISTS and
|
|
%G_FILE_TEST_IS_EXECUTABLE are implemented using the access()
|
|
system call. This usually doesn't matter, but if your program
|
|
is setuid or setgid it means that these tests will give you
|
|
the answer for the real user ID and group ID, rather than the
|
|
effective user ID and group ID.
|
|
|
|
On Windows, there are no symlinks, so testing for
|
|
%G_FILE_TEST_IS_SYMLINK will always return %FALSE. Testing for
|
|
%G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and
|
|
its name indicates that it is executable, checking for well-known
|
|
extensions and those listed in the `PATHEXT` environment variable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">whether a test was %TRUE</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="filename" transfer-ownership="none">
|
|
<doc xml:space="preserve">a filename to test in the
|
|
GLib file name encoding</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="test" transfer-ownership="none">
|
|
<doc xml:space="preserve">bitfield of #GFileTest flags</doc>
|
|
<type name="FileTest" c:type="GFileTest"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="filename_display_basename" c:identifier="g_filename_display_basename" version="2.6">
|
|
<doc xml:space="preserve">Returns the display basename for the particular filename, guaranteed
|
|
to be valid UTF-8. The display name might not be identical to the filename,
|
|
for instance there might be problems converting it to UTF-8, and some files
|
|
can be translated in the display.
|
|
|
|
If GLib cannot make sense of the encoding of @filename, as a last resort it
|
|
replaces unknown characters with U+FFFD, the Unicode replacement character.
|
|
You can search the result for the UTF-8 encoding of this character (which is
|
|
"\357\277\275" in octal notation) to find out if @filename was in an invalid
|
|
encoding.
|
|
|
|
You must pass the whole absolute pathname to this functions so that
|
|
translation of well known locations can be done.
|
|
|
|
This function is preferred over g_filename_display_name() if you know the
|
|
whole path, as it allows translation.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string containing
|
|
a rendition of the basename of the filename in valid UTF-8</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="filename" transfer-ownership="none">
|
|
<doc xml:space="preserve">an absolute pathname in the
|
|
GLib file name encoding</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="filename_display_name" c:identifier="g_filename_display_name" version="2.6">
|
|
<doc xml:space="preserve">Converts a filename into a valid UTF-8 string. The conversion is
|
|
not necessarily reversible, so you should keep the original around
|
|
and use the return value of this function only for display purposes.
|
|
Unlike g_filename_to_utf8(), the result is guaranteed to be non-%NULL
|
|
even if the filename actually isn't in the GLib file name encoding.
|
|
|
|
If GLib cannot make sense of the encoding of @filename, as a last resort it
|
|
replaces unknown characters with U+FFFD, the Unicode replacement character.
|
|
You can search the result for the UTF-8 encoding of this character (which is
|
|
"\357\277\275" in octal notation) to find out if @filename was in an invalid
|
|
encoding.
|
|
|
|
If you know the whole pathname of the file you should use
|
|
g_filename_display_basename(), since that allows location-based
|
|
translation of filenames.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string containing
|
|
a rendition of the filename in valid UTF-8</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="filename" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pathname hopefully in the
|
|
GLib file name encoding</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="filename_from_uri" c:identifier="g_filename_from_uri" throws="1">
|
|
<doc xml:space="preserve">Converts an escaped ASCII-encoded URI to a local filename in the
|
|
encoding used for filenames.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated string holding
|
|
the resulting filename, or %NULL on an error.</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a uri describing a filename (escaped, encoded in ASCII).</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="hostname" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">Location to store hostname for the URI.
|
|
If there is no hostname in the URI, %NULL will be
|
|
stored in this location.</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="filename_from_utf8" c:identifier="g_filename_from_utf8" throws="1">
|
|
<doc xml:space="preserve">Converts a string from UTF-8 to the encoding GLib uses for
|
|
filenames. Note that on Windows GLib uses UTF-8 for filenames;
|
|
on other platforms, this function indirectly depends on the
|
|
[current locale][setlocale].
|
|
|
|
The input string shall not contain nul characters even if the @len
|
|
argument is positive. A nul character found inside the string will result
|
|
in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. If the filename encoding is
|
|
not UTF-8 and the conversion output contains a nul character, the error
|
|
%G_CONVERT_ERROR_EMBEDDED_NUL is set and the function returns %NULL.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">
|
|
The converted string, or %NULL on an error.</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="utf8string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the string, or -1 if the string is
|
|
nul-terminated.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store the number of bytes in
|
|
the input string that were successfully converted, or %NULL.
|
|
Even if the conversion was successful, this may be
|
|
less than @len if there were partial characters
|
|
at the end of the input. If the error
|
|
%G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
|
|
stored will be the byte offset after the last valid
|
|
input sequence.</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
<parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">the number of bytes stored in
|
|
the output buffer (not including the terminating nul).</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="filename_to_uri" c:identifier="g_filename_to_uri" throws="1">
|
|
<doc xml:space="preserve">Converts an absolute filename to an escaped ASCII-encoded URI, with the path
|
|
component following Section 3.3. of RFC 2396.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated string holding the resulting
|
|
URI, or %NULL on an error.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="filename" transfer-ownership="none">
|
|
<doc xml:space="preserve">an absolute filename specified in the GLib file
|
|
name encoding, which is the on-disk file name bytes on Unix, and UTF-8
|
|
on Windows</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="hostname" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">A UTF-8 encoded hostname, or %NULL for none.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="filename_to_utf8" c:identifier="g_filename_to_utf8" throws="1">
|
|
<doc xml:space="preserve">Converts a string which is in the encoding used by GLib for
|
|
filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8
|
|
for filenames; on other platforms, this function indirectly depends on
|
|
the [current locale][setlocale].
|
|
|
|
The input string shall not contain nul characters even if the @len
|
|
argument is positive. A nul character found inside the string will result
|
|
in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
|
|
If the source encoding is not UTF-8 and the conversion output contains a
|
|
nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the
|
|
function returns %NULL. Use g_convert() to produce output that
|
|
may contain embedded nul characters.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">The converted string, or %NULL on an error.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="opsysstring" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string in the encoding for filenames</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the string, or -1 if the string is
|
|
nul-terminated (Note that some encodings may allow nul
|
|
bytes to occur inside strings. In that case, using -1
|
|
for the @len parameter is unsafe)</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store the number of bytes in the
|
|
input string that were successfully converted, or %NULL.
|
|
Even if the conversion was successful, this may be
|
|
less than @len if there were partial characters
|
|
at the end of the input. If the error
|
|
%G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
|
|
stored will be the byte offset after the last valid
|
|
input sequence.</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
<parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">the number of bytes stored in the output
|
|
buffer (not including the terminating nul).</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="fileutils">
|
|
<doc xml:space="preserve">Do not use these APIs unless you are porting a POSIX application to Windows.
|
|
A more high-level file access API is provided as GIO — see the documentation
|
|
for #GFile.
|
|
|
|
There is a group of functions which wrap the common POSIX functions
|
|
dealing with filenames (g_open(), g_rename(), g_mkdir(), g_stat(),
|
|
g_unlink(), g_remove(), g_fopen(), g_freopen()). The point of these
|
|
wrappers is to make it possible to handle file names with any Unicode
|
|
characters in them on Windows without having to use ifdefs and the
|
|
wide character API in the application code.
|
|
|
|
On some Unix systems, these APIs may be defined as identical to their POSIX
|
|
counterparts. For this reason, you must check for and include the necessary
|
|
header files (such as `fcntl.h`) before using functions like g_creat(). You
|
|
must also define the relevant feature test macros.
|
|
|
|
The pathname argument should be in the GLib file name encoding.
|
|
On POSIX this is the actual on-disk encoding which might correspond
|
|
to the locale settings of the process (or the `G_FILENAME_ENCODING`
|
|
environment variable), or not.
|
|
|
|
On Windows the GLib file name encoding is UTF-8. Note that the
|
|
Microsoft C library does not use UTF-8, but has separate APIs for
|
|
current system code page and wide characters (UTF-16). The GLib
|
|
wrappers call the wide character API if present (on modern Windows
|
|
systems), otherwise convert to/from the system code page.
|
|
|
|
Another group of functions allows to open and read directories
|
|
in the GLib file name encoding. These are g_dir_open(),
|
|
g_dir_read_name(), g_dir_rewind(), g_dir_close().</doc>
|
|
</docsection>
|
|
<function name="find_program_in_path" c:identifier="g_find_program_in_path">
|
|
<doc xml:space="preserve">Locates the first executable named @program in the user's path, in the
|
|
same way that execvp() would locate it. Returns an allocated string
|
|
with the absolute path name, or %NULL if the program is not found in
|
|
the path. If @program is already an absolute path, returns a copy of
|
|
@program if @program exists and is executable, and %NULL otherwise.
|
|
|
|
On Windows, if @program does not have a file type suffix, tries
|
|
with the suffixes .exe, .cmd, .bat and .com, and the suffixes in
|
|
the `PATHEXT` environment variable.
|
|
|
|
On Windows, it looks for the file in the same way as CreateProcess()
|
|
would. This means first in the directory where the executing
|
|
program was loaded from, then in the current directory, then in the
|
|
Windows 32-bit system directory, then in the Windows directory, and
|
|
finally in the directories in the `PATH` environment variable. If
|
|
the program is found, the return value contains the full name
|
|
including the type suffix.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a newly-allocated
|
|
string with the absolute path, or %NULL</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="program" transfer-ownership="none">
|
|
<doc xml:space="preserve">a program name in the GLib file name encoding</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="format_size" c:identifier="g_format_size" version="2.30">
|
|
<doc xml:space="preserve">Formats a size (for example the size of a file) into a human readable
|
|
string. Sizes are rounded to the nearest size prefix (kB, MB, GB)
|
|
and are displayed rounded to the nearest tenth. E.g. the file size
|
|
3292528 bytes will be converted into the string "3.2 MB". The returned string
|
|
is UTF-8, and may use a non-breaking space to separate the number and units,
|
|
to ensure they aren’t separated when line wrapped.
|
|
|
|
The prefix units base is 1000 (i.e. 1 kB is 1000 bytes).
|
|
|
|
This string should be freed with g_free() when not needed any longer.
|
|
|
|
See g_format_size_full() for more options about how the size might be
|
|
formatted.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated formatted string containing
|
|
a human readable file size</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="size" transfer-ownership="none">
|
|
<doc xml:space="preserve">a size in bytes</doc>
|
|
<type name="guint64" c:type="guint64"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="format_size_for_display" c:identifier="g_format_size_for_display" version="2.16" deprecated="1" deprecated-version="2.30">
|
|
<doc xml:space="preserve">Formats a size (for example the size of a file) into a human
|
|
readable string. Sizes are rounded to the nearest size prefix
|
|
(KB, MB, GB) and are displayed rounded to the nearest tenth.
|
|
E.g. the file size 3292528 bytes will be converted into the
|
|
string "3.1 MB".
|
|
|
|
The prefix units base is 1024 (i.e. 1 KB is 1024 bytes).
|
|
|
|
This string should be freed with g_free() when not needed any longer.</doc>
|
|
<doc-deprecated xml:space="preserve">This function is broken due to its use of SI
|
|
suffixes to denote IEC units. Use g_format_size() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated formatted string
|
|
containing a human readable file size</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="size" transfer-ownership="none">
|
|
<doc xml:space="preserve">a size in bytes</doc>
|
|
<type name="gint64" c:type="goffset"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="format_size_full" c:identifier="g_format_size_full" version="2.30">
|
|
<doc xml:space="preserve">Formats a size.
|
|
|
|
This function is similar to g_format_size() but allows for flags
|
|
that modify the output. See #GFormatSizeFlags.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated formatted string
|
|
containing a human readable file size</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="size" transfer-ownership="none">
|
|
<doc xml:space="preserve">a size in bytes</doc>
|
|
<type name="guint64" c:type="guint64"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">#GFormatSizeFlags to modify the output</doc>
|
|
<type name="FormatSizeFlags" c:type="GFormatSizeFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="fprintf" c:identifier="g_fprintf" version="2.2" introspectable="0">
|
|
<doc xml:space="preserve">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.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes printed.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="file" transfer-ownership="none">
|
|
<doc xml:space="preserve">the stream to write to.</doc>
|
|
<type name="gpointer" c:type="FILE*"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">a standard printf() format string, but notice
|
|
[string precision pitfalls][string-precision]</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">the arguments to insert in the output.</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="free" c:identifier="g_free">
|
|
<doc xml:space="preserve">Frees the memory pointed to by @mem.
|
|
|
|
If @mem is %NULL it simply returns, so there is no need to check @mem
|
|
against %NULL before calling this function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mem" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the memory to free</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="get_application_name" c:identifier="g_get_application_name" version="2.2">
|
|
<doc xml:space="preserve">Gets a human-readable name for the application, as set by
|
|
g_set_application_name(). This name should be localized if
|
|
possible, and is intended for display to the user. Contrast with
|
|
g_get_prgname(), which gets a non-localized name. If
|
|
g_set_application_name() has not been called, returns the result of
|
|
g_get_prgname() (which may be %NULL if g_set_prgname() has also not
|
|
been called).</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">human-readable application
|
|
name. May return %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_charset" c:identifier="g_get_charset">
|
|
<doc xml:space="preserve">Obtains the character set for the [current locale][setlocale]; you
|
|
might use this character set as an argument to g_convert(), to convert
|
|
from the current locale's encoding to some other encoding. (Frequently
|
|
g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts, though.)
|
|
|
|
On Windows the character set returned by this function is the
|
|
so-called system default ANSI code-page. That is the character set
|
|
used by the "narrow" versions of C library and Win32 functions that
|
|
handle file names. It might be different from the character set
|
|
used by the C library's current locale.
|
|
|
|
On Linux, the character set is found by consulting nl_langinfo() if
|
|
available. If not, the environment variables `LC_ALL`, `LC_CTYPE`, `LANG`
|
|
and `CHARSET` are queried in order.
|
|
|
|
The return value is %TRUE if the locale's encoding is UTF-8, in that
|
|
case you can perhaps avoid calling g_convert().
|
|
|
|
The string returned in @charset is not allocated, and should not be
|
|
freed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the returned charset is UTF-8</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="charset" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for character set
|
|
name, or %NULL.</doc>
|
|
<type name="utf8" c:type="const char**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="get_codeset" c:identifier="g_get_codeset">
|
|
<doc xml:space="preserve">Gets the character set for the current locale.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string containing the name
|
|
of the character set. This string must be freed with g_free().</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_console_charset" c:identifier="g_get_console_charset" version="2.62">
|
|
<doc xml:space="preserve">Obtains the character set used by the console attached to the process,
|
|
which is suitable for printing output to the terminal.
|
|
|
|
Usually this matches the result returned by g_get_charset(), but in
|
|
environments where the locale's character set does not match the encoding
|
|
of the console this function tries to guess a more suitable value instead.
|
|
|
|
On Windows the character set returned by this function is the
|
|
output code page used by the console associated with the calling process.
|
|
If the codepage can't be determined (for example because there is no
|
|
console attached) UTF-8 is assumed.
|
|
|
|
The return value is %TRUE if the locale's encoding is UTF-8, in that
|
|
case you can perhaps avoid calling g_convert().
|
|
|
|
The string returned in @charset is not allocated, and should not be
|
|
freed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the returned charset is UTF-8</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="charset" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for character set
|
|
name, or %NULL.</doc>
|
|
<type name="utf8" c:type="const char**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="get_current_dir" c:identifier="g_get_current_dir">
|
|
<doc xml:space="preserve">Gets the current directory.
|
|
|
|
The returned string should be freed when no longer needed.
|
|
The encoding of the returned string is system defined.
|
|
On Windows, it is always UTF-8.
|
|
|
|
Since GLib 2.40, this function will return the value of the "PWD"
|
|
environment variable if it is set and it happens to be the same as
|
|
the current directory. This can make a difference in the case that
|
|
the current directory is the target of a symbolic link.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the current directory</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_current_time" c:identifier="g_get_current_time" deprecated="1" deprecated-version="2.62">
|
|
<doc xml:space="preserve">Equivalent to the UNIX gettimeofday() function, but portable.
|
|
|
|
You may find g_get_real_time() to be more convenient.</doc>
|
|
<doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use g_get_real_time()
|
|
instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="result" transfer-ownership="none">
|
|
<doc xml:space="preserve">#GTimeVal structure in which to store current time.</doc>
|
|
<type name="TimeVal" c:type="GTimeVal*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="get_environ" c:identifier="g_get_environ" version="2.28">
|
|
<doc xml:space="preserve">Gets the list of environment variables for the current process.
|
|
|
|
The list is %NULL terminated and each item in the list is of the
|
|
form 'NAME=VALUE'.
|
|
|
|
This is equivalent to direct access to the 'environ' global variable,
|
|
except portable.
|
|
|
|
The return value is freshly allocated and it should be freed with
|
|
g_strfreev() when it is no longer needed.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">
|
|
the list of environment variables</doc>
|
|
<array c:type="gchar**">
|
|
<type name="filename"/>
|
|
</array>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_filename_charsets" c:identifier="g_get_filename_charsets" version="2.6">
|
|
<doc xml:space="preserve">Determines the preferred character sets used for filenames.
|
|
The first character set from the @charsets is the filename encoding, the
|
|
subsequent character sets are used when trying to generate a displayable
|
|
representation of a filename, see g_filename_display_name().
|
|
|
|
On Unix, the character sets are determined by consulting the
|
|
environment variables `G_FILENAME_ENCODING` and `G_BROKEN_FILENAMES`.
|
|
On Windows, the character set used in the GLib API is always UTF-8
|
|
and said environment variables have no effect.
|
|
|
|
`G_FILENAME_ENCODING` may be set to a comma-separated list of
|
|
character set names. The special token "\@locale" is taken
|
|
to mean the character set for the [current locale][setlocale].
|
|
If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is,
|
|
the character set of the current locale is taken as the filename
|
|
encoding. If neither environment variable is set, UTF-8 is taken
|
|
as the filename encoding, but the character set of the current locale
|
|
is also put in the list of encodings.
|
|
|
|
The returned @charsets belong to GLib and must not be freed.
|
|
|
|
Note that on Unix, regardless of the locale character set or
|
|
`G_FILENAME_ENCODING` value, the actual file names present
|
|
on a system might be in any random encoding or just gibberish.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the filename encoding is UTF-8.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="filename_charsets" direction="out" caller-allocates="0" transfer-ownership="none">
|
|
<doc xml:space="preserve">
|
|
return location for the %NULL-terminated list of encoding names</doc>
|
|
<array c:type="const gchar***">
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="get_home_dir" c:identifier="g_get_home_dir">
|
|
<doc xml:space="preserve">Gets the current user's home directory.
|
|
|
|
As with most UNIX tools, this function will return the value of the
|
|
`HOME` environment variable if it is set to an existing absolute path
|
|
name, falling back to the `passwd` file in the case that it is unset.
|
|
|
|
If the path given in `HOME` is non-absolute, does not exist, or is
|
|
not a directory, the result is undefined.
|
|
|
|
Before version 2.36 this function would ignore the `HOME` environment
|
|
variable, taking the value from the `passwd` database instead. This was
|
|
changed to increase the compatibility of GLib with other programs (and
|
|
the XDG basedir specification) and to increase testability of programs
|
|
based on GLib (by making it easier to run them from test frameworks).
|
|
|
|
If your program has a strong requirement for either the new or the
|
|
old behaviour (and if you don't wish to increase your GLib
|
|
dependency to ensure that the new behaviour is in effect) then you
|
|
should either directly check the `HOME` environment variable yourself
|
|
or unset it before calling any functions in GLib.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the current user's home directory</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_host_name" c:identifier="g_get_host_name" version="2.8">
|
|
<doc xml:space="preserve">Return a name for the machine.
|
|
|
|
The returned name is not necessarily a fully-qualified domain name,
|
|
or even present in DNS or some other name service at all. It need
|
|
not even be unique on your local network or site, but usually it
|
|
is. Callers should not rely on the return value having any specific
|
|
properties like uniqueness for security purposes. Even if the name
|
|
of the machine is changed while an application is running, the
|
|
return value from this function does not change. The returned
|
|
string is owned by GLib and should not be modified or freed. If no
|
|
name can be determined, a default fixed string "localhost" is
|
|
returned.
|
|
|
|
The encoding of the returned string is UTF-8.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the host name of the machine.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_language_names" c:identifier="g_get_language_names" version="2.6">
|
|
<doc xml:space="preserve">Computes a list of applicable locale names, which can be used to
|
|
e.g. construct locale-dependent filenames or search paths. The returned
|
|
list is sorted from most desirable to least desirable and always contains
|
|
the default locale "C".
|
|
|
|
For example, if LANGUAGE=de:en_US, then the returned list is
|
|
"de", "en_US", "en", "C".
|
|
|
|
This function consults the environment variables `LANGUAGE`, `LC_ALL`,
|
|
`LC_MESSAGES` and `LANG` to find the list of locales specified by the
|
|
user.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a %NULL-terminated array of strings owned by GLib
|
|
that must not be modified or freed.</doc>
|
|
<array c:type="const gchar* const*">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_language_names_with_category" c:identifier="g_get_language_names_with_category" version="2.58">
|
|
<doc xml:space="preserve">Computes a list of applicable locale names with a locale category name,
|
|
which can be used to construct the fallback locale-dependent filenames
|
|
or search paths. The returned list is sorted from most desirable to
|
|
least desirable and always contains the default locale "C".
|
|
|
|
This function consults the environment variables `LANGUAGE`, `LC_ALL`,
|
|
@category_name, and `LANG` to find the list of locales specified by the
|
|
user.
|
|
|
|
g_get_language_names() returns g_get_language_names_with_category("LC_MESSAGES").</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a %NULL-terminated array of strings owned by
|
|
the thread g_get_language_names_with_category was called from.
|
|
It must not be modified or freed. It must be copied if planned to be used in another thread.</doc>
|
|
<array c:type="const gchar* const*">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="category_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a locale category name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="get_locale_variants" c:identifier="g_get_locale_variants" version="2.28">
|
|
<doc xml:space="preserve">Returns a list of derived variants of @locale, which can be used to
|
|
e.g. construct locale-dependent filenames or search paths. The returned
|
|
list is sorted from most desirable to least desirable.
|
|
This function handles territory, charset and extra locale modifiers. See
|
|
[`setlocale(3)`](man:setlocale) for information about locales and their format.
|
|
|
|
@locale itself is guaranteed to be returned in the output.
|
|
|
|
For example, if @locale is `fr_BE`, then the returned list
|
|
is `fr_BE`, `fr`. If @locale is `en_GB.UTF-8@euro`, then the returned list
|
|
is `en_GB.UTF-8@euro`, `en_GB.UTF-8`, `en_GB@euro`, `en_GB`, `en.UTF-8@euro`,
|
|
`en.UTF-8`, `en@euro`, `en`.
|
|
|
|
If you need the list of variants for the current locale,
|
|
use g_get_language_names().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly
|
|
allocated array of newly allocated strings with the locale variants. Free with
|
|
g_strfreev().</doc>
|
|
<array c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="locale" transfer-ownership="none">
|
|
<doc xml:space="preserve">a locale identifier</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="get_monotonic_time" c:identifier="g_get_monotonic_time" version="2.28">
|
|
<doc xml:space="preserve">Queries the system monotonic time.
|
|
|
|
The monotonic clock will always increase and doesn't suffer
|
|
discontinuities when the user (or NTP) changes the system time. It
|
|
may or may not continue to tick during times where the machine is
|
|
suspended.
|
|
|
|
We try to use the clock that corresponds as closely as possible to
|
|
the passage of time as measured by system calls such as poll() but it
|
|
may not always be possible to do this.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the monotonic time, in microseconds</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_num_processors" c:identifier="g_get_num_processors" version="2.36">
|
|
<doc xml:space="preserve">Determine the approximate number of threads that the system will
|
|
schedule simultaneously for this process. This is intended to be
|
|
used as a parameter to g_thread_pool_new() for CPU bound tasks and
|
|
similar cases.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">Number of schedulable threads, always greater than 0</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_os_info" c:identifier="g_get_os_info" version="2.64">
|
|
<doc xml:space="preserve">Get information about the operating system.
|
|
|
|
On Linux this comes from the `/etc/os-release` file. On other systems, it may
|
|
come from a variety of sources. You can either use the standard key names
|
|
like %G_OS_INFO_KEY_NAME or pass any UTF-8 string key name. For example,
|
|
`/etc/os-release` provides a number of other less commonly used values that may
|
|
be useful. No key is guaranteed to be provided, so the caller should always
|
|
check if the result is %NULL.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">The associated value for the requested key or %NULL if
|
|
this information is not provided.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="key_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key for the OS info being requested, for example %G_OS_INFO_KEY_NAME.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="get_prgname" c:identifier="g_get_prgname">
|
|
<doc xml:space="preserve">Gets the name of the program. This name should not be localized,
|
|
in contrast to g_get_application_name().
|
|
|
|
If you are using #GApplication the program name is set in
|
|
g_application_run(). In case of GDK or GTK+ it is set in
|
|
gdk_init(), which is called by gtk_init() and the
|
|
#GtkApplication::startup handler. The program name is found by
|
|
taking the last component of @argv[0].</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the name of the program,
|
|
or %NULL if it has not been set yet. The returned string belongs
|
|
to GLib and must not be modified or freed.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_real_name" c:identifier="g_get_real_name">
|
|
<doc xml:space="preserve">Gets the real name of the user. This usually comes from the user's
|
|
entry in the `passwd` file. The encoding of the returned string is
|
|
system-defined. (On Windows, it is, however, always UTF-8.) If the
|
|
real user name cannot be determined, the string "Unknown" is
|
|
returned.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the user's real name.</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_real_time" c:identifier="g_get_real_time" version="2.28">
|
|
<doc xml:space="preserve">Queries the system wall-clock time.
|
|
|
|
This call is functionally equivalent to g_get_current_time() except
|
|
that the return value is often more convenient than dealing with a
|
|
#GTimeVal.
|
|
|
|
You should only use this call if you are actually interested in the real
|
|
wall-clock time. g_get_monotonic_time() is probably more useful for
|
|
measuring intervals.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of microseconds since January 1, 1970 UTC.</doc>
|
|
<type name="gint64" c:type="gint64"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_system_config_dirs" c:identifier="g_get_system_config_dirs" version="2.6">
|
|
<doc xml:space="preserve">Returns an ordered list of base directories in which to access
|
|
system-wide configuration information.
|
|
|
|
On UNIX platforms this is determined using the mechanisms described
|
|
in the
|
|
[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
|
|
In this case the list of directories retrieved will be `XDG_CONFIG_DIRS`.
|
|
|
|
On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_DIRS` is defined.
|
|
If `XDG_CONFIG_DIRS` is undefined, the directory that contains application
|
|
data for all users is used instead. A typical path is
|
|
`C:\Documents and Settings\All Users\Application Data`.
|
|
This folder is used for application data
|
|
that is not user specific. For example, an application can store
|
|
a spell-check dictionary, a database of clip art, or a log file in the
|
|
CSIDL_COMMON_APPDATA folder. This information will not roam and is available
|
|
to anyone using the computer.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">
|
|
a %NULL-terminated array of strings owned by GLib that must not be
|
|
modified or freed.</doc>
|
|
<array c:type="const gchar* const*">
|
|
<type name="filename"/>
|
|
</array>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_system_data_dirs" c:identifier="g_get_system_data_dirs" version="2.6">
|
|
<doc xml:space="preserve">Returns an ordered list of base directories in which to access
|
|
system-wide application data.
|
|
|
|
On UNIX platforms this is determined using the mechanisms described
|
|
in the
|
|
[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec)
|
|
In this case the list of directories retrieved will be `XDG_DATA_DIRS`.
|
|
|
|
On Windows it follows XDG Base Directory Specification if `XDG_DATA_DIRS` is defined.
|
|
If `XDG_DATA_DIRS` is undefined,
|
|
the first elements in the list are the Application Data
|
|
and Documents folders for All Users. (These can be determined only
|
|
on Windows 2000 or later and are not present in the list on other
|
|
Windows versions.) See documentation for CSIDL_COMMON_APPDATA and
|
|
CSIDL_COMMON_DOCUMENTS.
|
|
|
|
Then follows the "share" subfolder in the installation folder for
|
|
the package containing the DLL that calls this function, if it can
|
|
be determined.
|
|
|
|
Finally the list contains the "share" subfolder in the installation
|
|
folder for GLib, and in the installation folder for the package the
|
|
application's .exe file belongs to.
|
|
|
|
The installation folders above are determined by looking up the
|
|
folder where the module (DLL or EXE) in question is located. If the
|
|
folder's name is "bin", its parent is used, otherwise the folder
|
|
itself.
|
|
|
|
Note that on Windows the returned list can vary depending on where
|
|
this function is called.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">
|
|
a %NULL-terminated array of strings owned by GLib that must not be
|
|
modified or freed.</doc>
|
|
<array c:type="const gchar* const*">
|
|
<type name="filename"/>
|
|
</array>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_tmp_dir" c:identifier="g_get_tmp_dir">
|
|
<doc xml:space="preserve">Gets the directory to use for temporary files.
|
|
|
|
On UNIX, this is taken from the `TMPDIR` environment variable.
|
|
If the variable is not set, `P_tmpdir` is
|
|
used, as defined by the system C library. Failing that, a
|
|
hard-coded default of "/tmp" is returned.
|
|
|
|
On Windows, the `TEMP` environment variable is used, with the
|
|
root directory of the Windows installation (eg: "C:\") used
|
|
as a default.
|
|
|
|
The encoding of the returned string is system-defined. On Windows,
|
|
it is always UTF-8. The return value is never %NULL or the empty
|
|
string.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the directory to use for temporary files.</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_user_cache_dir" c:identifier="g_get_user_cache_dir" version="2.6">
|
|
<doc xml:space="preserve">Returns a base directory in which to store non-essential, cached
|
|
data specific to particular user.
|
|
|
|
On UNIX platforms this is determined using the mechanisms described
|
|
in the
|
|
[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
|
|
In this case the directory retrieved will be `XDG_CACHE_HOME`.
|
|
|
|
On Windows it follows XDG Base Directory Specification if `XDG_CACHE_HOME` is defined.
|
|
If `XDG_CACHE_HOME` is undefined, the directory that serves as a common
|
|
repository for temporary Internet files is used instead. A typical path is
|
|
`C:\Documents and Settings\username\Local Settings\Temporary Internet Files`.
|
|
See the [documentation for `CSIDL_INTERNET_CACHE`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_internet_cache).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a string owned by GLib that
|
|
must not be modified or freed.</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_user_config_dir" c:identifier="g_get_user_config_dir" version="2.6">
|
|
<doc xml:space="preserve">Returns a base directory in which to store user-specific application
|
|
configuration information such as user preferences and settings.
|
|
|
|
On UNIX platforms this is determined using the mechanisms described
|
|
in the
|
|
[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
|
|
In this case the directory retrieved will be `XDG_CONFIG_HOME`.
|
|
|
|
On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_HOME` is defined.
|
|
If `XDG_CONFIG_HOME` is undefined, the folder to use for local (as opposed
|
|
to roaming) application data is used instead. See the
|
|
[documentation for `CSIDL_LOCAL_APPDATA`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata).
|
|
Note that in this case on Windows it will be the same
|
|
as what g_get_user_data_dir() returns.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a string owned by GLib that
|
|
must not be modified or freed.</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_user_data_dir" c:identifier="g_get_user_data_dir" version="2.6">
|
|
<doc xml:space="preserve">Returns a base directory in which to access application data such
|
|
as icons that is customized for a particular user.
|
|
|
|
On UNIX platforms this is determined using the mechanisms described
|
|
in the
|
|
[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
|
|
In this case the directory retrieved will be `XDG_DATA_HOME`.
|
|
|
|
On Windows it follows XDG Base Directory Specification if `XDG_DATA_HOME`
|
|
is defined. If `XDG_DATA_HOME` is undefined, the folder to use for local (as
|
|
opposed to roaming) application data is used instead. See the
|
|
[documentation for `CSIDL_LOCAL_APPDATA`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata).
|
|
Note that in this case on Windows it will be the same
|
|
as what g_get_user_config_dir() returns.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a string owned by GLib that must
|
|
not be modified or freed.</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_user_name" c:identifier="g_get_user_name">
|
|
<doc xml:space="preserve">Gets the user name of the current user. The encoding of the returned
|
|
string is system-defined. On UNIX, it might be the preferred file name
|
|
encoding, or something else, and there is no guarantee that it is even
|
|
consistent on a machine. On Windows, it is always UTF-8.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the user name of the current user.</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_user_runtime_dir" c:identifier="g_get_user_runtime_dir" version="2.28">
|
|
<doc xml:space="preserve">Returns a directory that is unique to the current user on the local
|
|
system.
|
|
|
|
This is determined using the mechanisms described
|
|
in the
|
|
[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
|
|
This is the directory
|
|
specified in the `XDG_RUNTIME_DIR` environment variable.
|
|
In the case that this variable is not set, we return the value of
|
|
g_get_user_cache_dir(), after verifying that it exists.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a string owned by GLib that must not be
|
|
modified or freed.</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="get_user_special_dir" c:identifier="g_get_user_special_dir" version="2.14">
|
|
<doc xml:space="preserve">Returns the full path of a special directory using its logical id.
|
|
|
|
On UNIX this is done using the XDG special user directories.
|
|
For compatibility with existing practise, %G_USER_DIRECTORY_DESKTOP
|
|
falls back to `$HOME/Desktop` when XDG special user directories have
|
|
not been set up.
|
|
|
|
Depending on the platform, the user might be able to change the path
|
|
of the special directory without requiring the session to restart; GLib
|
|
will not reflect any change once the special directories are loaded.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the path to the specified special directory, or
|
|
%NULL if the logical id was not found. The returned string is owned by
|
|
GLib and should not be modified or freed.</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="directory" transfer-ownership="none">
|
|
<doc xml:space="preserve">the logical id of special directory</doc>
|
|
<type name="UserDirectory" c:type="GUserDirectory"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="getenv" c:identifier="g_getenv">
|
|
<doc xml:space="preserve">Returns the value of an environment variable.
|
|
|
|
On UNIX, the name and value are byte strings which might or might not
|
|
be in some consistent character set and encoding. On Windows, they are
|
|
in UTF-8.
|
|
On Windows, in case the environment variable's value contains
|
|
references to other environment variables, they are expanded.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">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().</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="variable" transfer-ownership="none">
|
|
<doc xml:space="preserve">the environment variable to get</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="ghostutils">
|
|
<doc xml:space="preserve">Functions for manipulating internet hostnames; in particular, for
|
|
converting between Unicode and ASCII-encoded forms of
|
|
Internationalized Domain Names (IDNs).
|
|
|
|
The
|
|
[Internationalized Domain Names for Applications (IDNA)](http://www.ietf.org/rfc/rfc3490.txt)
|
|
standards allow for the use
|
|
of Unicode domain names in applications, while providing
|
|
backward-compatibility with the old ASCII-only DNS, by defining an
|
|
ASCII-Compatible Encoding of any given Unicode name, which can be
|
|
used with non-IDN-aware applications and protocols. (For example,
|
|
"Παν語.org" maps to "xn--4wa8awb4637h.org".)</doc>
|
|
</docsection>
|
|
<docsection name="gunix">
|
|
<doc xml:space="preserve">Most of GLib is intended to be portable; in contrast, this set of
|
|
functions is designed for programs which explicitly target UNIX,
|
|
or are using it to build higher level abstractions which would be
|
|
conditionally compiled if the platform matches G_OS_UNIX.
|
|
|
|
To use these functions, you must explicitly include the
|
|
"glib-unix.h" header.</doc>
|
|
</docsection>
|
|
<function name="hash_table_add" c:identifier="g_hash_table_add" moved-to="HashTable.add" version="2.32">
|
|
<doc xml:space="preserve">This is a convenience function for using a #GHashTable as a set. It
|
|
is equivalent to calling g_hash_table_replace() with @key as both the
|
|
key and the value.
|
|
|
|
In particular, this means that if @key already exists in the hash table, then
|
|
the old copy of @key in the hash table is freed and @key replaces it in the
|
|
table.
|
|
|
|
When a hash table only ever contains keys that have themselves as the
|
|
corresponding value it is able to be stored more efficiently. See
|
|
the discussion in the section description.
|
|
|
|
Starting from GLib 2.40, this function returns a boolean value to
|
|
indicate whether the newly added value was already in the hash table
|
|
or not.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key did not exist yet</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="full" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a key to insert</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hash_table_contains" c:identifier="g_hash_table_contains" moved-to="HashTable.contains" version="2.32">
|
|
<doc xml:space="preserve">Checks if @key is in @hash_table.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @key is in @hash_table, %FALSE otherwise.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a key to check</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hash_table_destroy" c:identifier="g_hash_table_destroy" moved-to="HashTable.destroy">
|
|
<doc xml:space="preserve">Destroys all keys and values in the #GHashTable and decrements its
|
|
reference count by 1. If keys and/or values are dynamically allocated,
|
|
you should either free them first or create the #GHashTable with destroy
|
|
notifiers using g_hash_table_new_full(). In the latter case the destroy
|
|
functions you supplied will be called on all keys and values during the
|
|
destruction phase.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="hash_table_freeze" c:identifier="g_hash_table_freeze" introspectable="0">
|
|
<doc xml:space="preserve">This function is deprecated and will be removed in the next major
|
|
release of GLib. It does nothing.</doc>
|
|
<parameters>
|
|
<parameter name="hash_table">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="hash_table_insert" c:identifier="g_hash_table_insert" moved-to="HashTable.insert">
|
|
<doc xml:space="preserve">Inserts a new key and value into a #GHashTable.
|
|
|
|
If the key already exists in the #GHashTable its current
|
|
value is replaced with the new value. If you supplied a
|
|
@value_destroy_func when creating the #GHashTable, the old
|
|
value is freed using that function. If you supplied a
|
|
@key_destroy_func when creating the #GHashTable, the passed
|
|
key is freed using that function.
|
|
|
|
Starting from GLib 2.40, this function returns a boolean value to
|
|
indicate whether the newly added value was already in the hash table
|
|
or not.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key did not exist yet</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a key to insert</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the value to associate with the key</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hash_table_lookup" c:identifier="g_hash_table_lookup" moved-to="HashTable.lookup">
|
|
<doc xml:space="preserve">Looks up a key in a #GHashTable. Note that this function cannot
|
|
distinguish between a key that is not present and one which is present
|
|
and has the value %NULL. If you need this distinction, use
|
|
g_hash_table_lookup_extended().</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the associated value, or %NULL if the key is not found</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the key to look up</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hash_table_lookup_extended" c:identifier="g_hash_table_lookup_extended" moved-to="HashTable.lookup_extended">
|
|
<doc xml:space="preserve">Looks up a key in the #GHashTable, returning the original key and the
|
|
associated value and a #gboolean which is %TRUE if the key was found. This
|
|
is useful if you need to free the memory allocated for the original key,
|
|
for example before calling g_hash_table_remove().
|
|
|
|
You can actually pass %NULL for @lookup_key to test
|
|
whether the %NULL key exists, provided the hash and equal functions
|
|
of @hash_table are %NULL-safe.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key was found in the #GHashTable</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="lookup_key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the key to look up</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="orig_key" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the original key</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</parameter>
|
|
<parameter name="value" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the value associated
|
|
with the key</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hash_table_remove" c:identifier="g_hash_table_remove" moved-to="HashTable.remove">
|
|
<doc xml:space="preserve">Removes a key and its associated value from a #GHashTable.
|
|
|
|
If the #GHashTable was created using g_hash_table_new_full(), the
|
|
key and value are freed using the supplied destroy functions, otherwise
|
|
you have to make sure that any dynamically allocated values are freed
|
|
yourself.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key was found and removed from the #GHashTable</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the key to remove</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hash_table_remove_all" c:identifier="g_hash_table_remove_all" moved-to="HashTable.remove_all" version="2.12">
|
|
<doc xml:space="preserve">Removes all keys and their associated values from a #GHashTable.
|
|
|
|
If the #GHashTable was created using g_hash_table_new_full(),
|
|
the keys and values are freed using the supplied destroy functions,
|
|
otherwise you have to make sure that any dynamically allocated
|
|
values are freed yourself.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hash_table_replace" c:identifier="g_hash_table_replace" moved-to="HashTable.replace">
|
|
<doc xml:space="preserve">Inserts a new key and value into a #GHashTable similar to
|
|
g_hash_table_insert(). The difference is that if the key
|
|
already exists in the #GHashTable, it gets replaced by the
|
|
new key. If you supplied a @value_destroy_func when creating
|
|
the #GHashTable, the old value is freed using that function.
|
|
If you supplied a @key_destroy_func when creating the
|
|
#GHashTable, the old key is freed using that function.
|
|
|
|
Starting from GLib 2.40, this function returns a boolean value to
|
|
indicate whether the newly added value was already in the hash table
|
|
or not.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key did not exist yet</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a key to insert</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the value to associate with the key</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hash_table_size" c:identifier="g_hash_table_size" moved-to="HashTable.size">
|
|
<doc xml:space="preserve">Returns the number of elements contained in the #GHashTable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of key/value pairs in the #GHashTable.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hash_table_steal" c:identifier="g_hash_table_steal" moved-to="HashTable.steal">
|
|
<doc xml:space="preserve">Removes a key and its associated value from a #GHashTable without
|
|
calling the key and value destroy functions.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key was found and removed from the #GHashTable</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the key to remove</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hash_table_steal_all" c:identifier="g_hash_table_steal_all" moved-to="HashTable.steal_all" version="2.12">
|
|
<doc xml:space="preserve">Removes all keys and their associated values from a #GHashTable
|
|
without calling the key and value destroy functions.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hash_table_steal_extended" c:identifier="g_hash_table_steal_extended" moved-to="HashTable.steal_extended" version="2.58">
|
|
<doc xml:space="preserve">Looks up a key in the #GHashTable, stealing the original key and the
|
|
associated value and returning %TRUE if the key was found. If the key was
|
|
not found, %FALSE is returned.
|
|
|
|
If found, the stolen key and value are removed from the hash table without
|
|
calling the key and value destroy functions, and ownership is transferred to
|
|
the caller of this method; as with g_hash_table_steal().
|
|
|
|
You can pass %NULL for @lookup_key, provided the hash and equal functions
|
|
of @hash_table are %NULL-safe.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the key was found in the #GHashTable</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
<parameter name="lookup_key" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the key to look up</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="stolen_key" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the
|
|
original key</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</parameter>
|
|
<parameter name="stolen_value" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location
|
|
for the value associated with the key</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="hash_table_thaw" c:identifier="g_hash_table_thaw" introspectable="0">
|
|
<doc xml:space="preserve">This function is deprecated and will be removed in the next major
|
|
release of GLib. It does nothing.</doc>
|
|
<parameters>
|
|
<parameter name="hash_table">
|
|
<doc xml:space="preserve">a #GHashTable</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="hash_table_unref" c:identifier="g_hash_table_unref" moved-to="HashTable.unref" version="2.10">
|
|
<doc xml:space="preserve">Atomically decrements the reference count of @hash_table by one.
|
|
If the reference count drops to 0, all keys and values will be
|
|
destroyed, and all memory allocated by the hash table is released.
|
|
This function is MT-safe and may be called from any thread.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hash_table" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid #GHashTable</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</type>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="hash_tables">
|
|
<doc xml:space="preserve">A #GHashTable provides associations between keys and values which is
|
|
optimized so that given a key, the associated value can be found,
|
|
inserted or removed in amortized O(1). All operations going through
|
|
each element take O(n) time (list all keys/values, table resize, etc.).
|
|
|
|
Note that neither keys nor values are copied when inserted into the
|
|
#GHashTable, so they must exist for the lifetime of the #GHashTable.
|
|
This means that the use of static strings is OK, but temporary
|
|
strings (i.e. those created in buffers and those returned by GTK
|
|
widgets) should be copied with g_strdup() before being inserted.
|
|
|
|
If keys or values are dynamically allocated, you must be careful to
|
|
ensure that they are freed when they are removed from the
|
|
#GHashTable, and also when they are overwritten by new insertions
|
|
into the #GHashTable. It is also not advisable to mix static strings
|
|
and dynamically-allocated strings in a #GHashTable, because it then
|
|
becomes difficult to determine whether the string should be freed.
|
|
|
|
To create a #GHashTable, use g_hash_table_new().
|
|
|
|
To insert a key and value into a #GHashTable, use
|
|
g_hash_table_insert().
|
|
|
|
To look up a value corresponding to a given key, use
|
|
g_hash_table_lookup() and g_hash_table_lookup_extended().
|
|
|
|
g_hash_table_lookup_extended() can also be used to simply
|
|
check if a key is present in the hash table.
|
|
|
|
To remove a key and value, use g_hash_table_remove().
|
|
|
|
To call a function for each key and value pair use
|
|
g_hash_table_foreach() or use an iterator to iterate over the
|
|
key/value pairs in the hash table, see #GHashTableIter. The iteration order
|
|
of a hash table is not defined, and you must not rely on iterating over
|
|
keys/values in the same order as they were inserted.
|
|
|
|
To destroy a #GHashTable use g_hash_table_destroy().
|
|
|
|
A common use-case for hash tables is to store information about a
|
|
set of keys, without associating any particular value with each
|
|
key. GHashTable optimizes one way of doing so: If you store only
|
|
key-value pairs where key == value, then GHashTable does not
|
|
allocate memory to store the values, which can be a considerable
|
|
space saving, if your set is large. The functions
|
|
g_hash_table_add() and g_hash_table_contains() are designed to be
|
|
used when using #GHashTable this way.
|
|
|
|
#GHashTable is not designed to be statically initialised with keys and
|
|
values known at compile time. To build a static hash table, use a tool such
|
|
as [gperf](https://www.gnu.org/software/gperf/).</doc>
|
|
</docsection>
|
|
<docsection name="hmac">
|
|
<doc xml:space="preserve">HMACs should be used when producing a cookie or hash based on data
|
|
and a key. Simple mechanisms for using SHA1 and other algorithms to
|
|
digest a key and data together are vulnerable to various security
|
|
issues.
|
|
[HMAC](http://en.wikipedia.org/wiki/HMAC)
|
|
uses algorithms like SHA1 in a secure way to produce a digest of a
|
|
key and data.
|
|
|
|
Both the key and data are arbitrary byte arrays of bytes or characters.
|
|
|
|
Support for HMAC Digests has been added in GLib 2.30, and support for SHA-512
|
|
in GLib 2.42. Support for SHA-384 was added in GLib 2.52.</doc>
|
|
</docsection>
|
|
<function-macro name="hook_append" c:identifier="g_hook_append" introspectable="0">
|
|
<doc xml:space="preserve">Appends a #GHook onto the end of a #GHookList.</doc>
|
|
<parameters>
|
|
<parameter name="hook_list">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
</parameter>
|
|
<parameter name="hook">
|
|
<doc xml:space="preserve">the #GHook to add to the end of @hook_list</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="hook_destroy" c:identifier="g_hook_destroy" moved-to="Hook.destroy">
|
|
<doc xml:space="preserve">Destroys a #GHook, given its ID.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the #GHook was found in the #GHookList and destroyed</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="hook_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">a hook ID</doc>
|
|
<type name="gulong" c:type="gulong"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hook_destroy_link" c:identifier="g_hook_destroy_link" moved-to="Hook.destroy_link">
|
|
<doc xml:space="preserve">Removes one #GHook from a #GHookList, marking it
|
|
inactive and calling g_hook_unref() on it.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GHook to remove</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hook_free" c:identifier="g_hook_free" moved-to="Hook.free">
|
|
<doc xml:space="preserve">Calls the #GHookList @finalize_hook function if it exists,
|
|
and frees the memory allocated for the #GHook.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GHook to free</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hook_insert_before" c:identifier="g_hook_insert_before" moved-to="Hook.insert_before">
|
|
<doc xml:space="preserve">Inserts a #GHook into a #GHookList, before a given #GHook.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="sibling" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the #GHook to insert the new #GHook before</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
<parameter name="hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GHook to insert</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hook_prepend" c:identifier="g_hook_prepend" moved-to="Hook.prepend">
|
|
<doc xml:space="preserve">Prepends a #GHook on the start of a #GHookList.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GHook to add to the start of @hook_list</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hook_unref" c:identifier="g_hook_unref" moved-to="Hook.unref">
|
|
<doc xml:space="preserve">Decrements the reference count of a #GHook.
|
|
If the reference count falls to 0, the #GHook is removed
|
|
from the #GHookList and g_hook_free() is called to free it.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hook_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GHookList</doc>
|
|
<type name="HookList" c:type="GHookList*"/>
|
|
</parameter>
|
|
<parameter name="hook" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GHook to unref</doc>
|
|
<type name="Hook" c:type="GHook*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="hooks">
|
|
<doc xml:space="preserve">The #GHookList, #GHook and their related functions provide support for
|
|
lists of hook functions. Functions can be added and removed from the lists,
|
|
and the list of hook functions can be invoked.</doc>
|
|
</docsection>
|
|
<function name="hostname_is_ascii_encoded" c:identifier="g_hostname_is_ascii_encoded" version="2.22">
|
|
<doc xml:space="preserve">Tests if @hostname contains segments with an ASCII-compatible
|
|
encoding of an Internationalized Domain Name. If this returns
|
|
%TRUE, you should decode the hostname with g_hostname_to_unicode()
|
|
before displaying it to the user.
|
|
|
|
Note that a hostname might contain a mix of encoded and unencoded
|
|
segments, and so it is possible for g_hostname_is_non_ascii() and
|
|
g_hostname_is_ascii_encoded() to both return %TRUE for a name.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @hostname contains any ASCII-encoded
|
|
segments.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hostname" transfer-ownership="none">
|
|
<doc xml:space="preserve">a hostname</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hostname_is_ip_address" c:identifier="g_hostname_is_ip_address" version="2.22">
|
|
<doc xml:space="preserve">Tests if @hostname is the string form of an IPv4 or IPv6 address.
|
|
(Eg, "192.168.0.1".)
|
|
|
|
Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @hostname is an IP address</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hostname" transfer-ownership="none">
|
|
<doc xml:space="preserve">a hostname (or IP address in string form)</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hostname_is_non_ascii" c:identifier="g_hostname_is_non_ascii" version="2.22">
|
|
<doc xml:space="preserve">Tests if @hostname contains Unicode characters. If this returns
|
|
%TRUE, you need to encode the hostname with g_hostname_to_ascii()
|
|
before using it in non-IDN-aware contexts.
|
|
|
|
Note that a hostname might contain a mix of encoded and unencoded
|
|
segments, and so it is possible for g_hostname_is_non_ascii() and
|
|
g_hostname_is_ascii_encoded() to both return %TRUE for a name.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @hostname contains any non-ASCII characters</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hostname" transfer-ownership="none">
|
|
<doc xml:space="preserve">a hostname</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hostname_to_ascii" c:identifier="g_hostname_to_ascii" version="2.22">
|
|
<doc xml:space="preserve">Converts @hostname to its canonical ASCII form; an ASCII-only
|
|
string containing no uppercase letters and not ending with a
|
|
trailing dot.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an ASCII hostname, which must be freed, or %NULL if
|
|
@hostname is in some way invalid.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hostname" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid UTF-8 or ASCII hostname</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="hostname_to_unicode" c:identifier="g_hostname_to_unicode" version="2.22">
|
|
<doc xml:space="preserve">Converts @hostname to its canonical presentation form; a UTF-8
|
|
string in Unicode normalization form C, containing no uppercase
|
|
letters, no forbidden characters, and no ASCII-encoded segments,
|
|
and not ending with a trailing dot.
|
|
|
|
Of course if @hostname is not an internationalized hostname, then
|
|
the canonical presentation form will be entirely ASCII.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a UTF-8 hostname, which must be freed, or %NULL if
|
|
@hostname is in some way invalid.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="hostname" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid UTF-8 or ASCII hostname</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="htonl" c:identifier="g_htonl" introspectable="0">
|
|
<doc xml:space="preserve">Converts a 32-bit integer value from host to network byte order.</doc>
|
|
<parameters>
|
|
<parameter name="val">
|
|
<doc xml:space="preserve">a 32-bit integer value in host byte order</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="htons" c:identifier="g_htons" introspectable="0">
|
|
<doc xml:space="preserve">Converts a 16-bit integer value from host to network byte order.</doc>
|
|
<parameters>
|
|
<parameter name="val">
|
|
<doc xml:space="preserve">a 16-bit integer value in host byte order</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<docsection name="i18n">
|
|
<doc xml:space="preserve">GLib doesn't force any particular localization method upon its users.
|
|
But since GLib itself is localized using the gettext() mechanism, it seems
|
|
natural to offer the de-facto standard gettext() support macros in an
|
|
easy-to-use form.
|
|
|
|
In order to use these macros in an application, you must include
|
|
`<glib/gi18n.h>`. For use in a library, you must include
|
|
`<glib/gi18n-lib.h>`
|
|
after defining the %GETTEXT_PACKAGE macro suitably for your library:
|
|
|[<!-- language="C" -->
|
|
#define GETTEXT_PACKAGE "gtk20"
|
|
#include <glib/gi18n-lib.h>
|
|
]|
|
|
For an application, note that you also have to call bindtextdomain(),
|
|
bind_textdomain_codeset(), textdomain() and setlocale() early on in your
|
|
main() to make gettext() work. For example:
|
|
|[<!-- language="C" -->
|
|
#include <glib/gi18n.h>
|
|
#include <locale.h>
|
|
|
|
int
|
|
main (int argc, char **argv)
|
|
{
|
|
setlocale (LC_ALL, "");
|
|
bindtextdomain (GETTEXT_PACKAGE, DATADIR "/locale");
|
|
bind_textdomain_codeset (GETTEXT_PACKAGE, "UTF-8");
|
|
textdomain (GETTEXT_PACKAGE);
|
|
|
|
// Rest of your application.
|
|
}
|
|
]|
|
|
where `DATADIR` is as typically provided by automake or Meson.
|
|
|
|
For a library, you only have to call bindtextdomain() and
|
|
bind_textdomain_codeset() in your initialization function. If your library
|
|
doesn't have an initialization function, you can call the functions before
|
|
the first translated message.
|
|
|
|
The
|
|
[gettext manual](http://www.gnu.org/software/gettext/manual/gettext.html#Maintainers)
|
|
covers details of how to integrate gettext into a project’s build system and
|
|
workflow.</doc>
|
|
</docsection>
|
|
<function name="iconv" c:identifier="g_iconv" introspectable="0">
|
|
<doc xml:space="preserve">Same as the standard UNIX routine iconv(), but
|
|
may be implemented via libiconv on UNIX flavors that lack
|
|
a native implementation.
|
|
|
|
GLib provides g_convert() and g_locale_to_utf8() which are likely
|
|
more convenient than the raw iconv wrappers.
|
|
|
|
Note that the behaviour of iconv() for characters which are valid in the
|
|
input character set, but which have no representation in the output character
|
|
set, is implementation defined. This function may return success (with a
|
|
positive number of non-reversible conversions as replacement characters were
|
|
used), or it may return -1 and set an error such as %EILSEQ, in such a
|
|
situation.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">count of non-reversible conversions, or -1 on error</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="converter" transfer-ownership="none">
|
|
<doc xml:space="preserve">conversion descriptor from g_iconv_open()</doc>
|
|
<type name="IConv" c:type="GIConv"/>
|
|
</parameter>
|
|
<parameter name="inbuf" transfer-ownership="none">
|
|
<doc xml:space="preserve">bytes to convert</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="inbytes_left" transfer-ownership="none">
|
|
<doc xml:space="preserve">inout parameter, bytes remaining to convert in @inbuf</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
<parameter name="outbuf" transfer-ownership="none">
|
|
<doc xml:space="preserve">converted output bytes</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="outbytes_left" transfer-ownership="none">
|
|
<doc xml:space="preserve">inout parameter, bytes available to fill in @outbuf</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="iconv_open" c:identifier="g_iconv_open" moved-to="IConv.open" introspectable="0">
|
|
<doc xml:space="preserve">Same as the standard UNIX routine iconv_open(), but
|
|
may be implemented via libiconv on UNIX flavors that lack
|
|
a native implementation.
|
|
|
|
GLib provides g_convert() and g_locale_to_utf8() which are likely
|
|
more convenient than the raw iconv wrappers.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a "conversion descriptor", or (GIConv)-1 if
|
|
opening the converter failed.</doc>
|
|
<type name="IConv" c:type="GIConv"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="to_codeset" transfer-ownership="none">
|
|
<doc xml:space="preserve">destination codeset</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="from_codeset" transfer-ownership="none">
|
|
<doc xml:space="preserve">source codeset</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="idle_add" c:identifier="g_idle_add" shadowed-by="idle_add_full" introspectable="0">
|
|
<doc xml:space="preserve">Adds a function to be called whenever there are no higher priority
|
|
events pending to the default main loop. The function is given the
|
|
default idle priority, #G_PRIORITY_DEFAULT_IDLE. If the function
|
|
returns %FALSE it is automatically removed from the list of event
|
|
sources and will not be called again.
|
|
|
|
See [memory management of sources][mainloop-memory-management] for details
|
|
on how to handle the return value and memory management of @data.
|
|
|
|
This internally creates a main loop source using g_idle_source_new()
|
|
and attaches it to the global #GMainContext using g_source_attach(), so
|
|
the callback will be invoked in whichever thread is running that main
|
|
context. You can do these steps manually if you need greater control or to
|
|
use a custom main context.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the ID (greater than 0) of the event source.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="function" transfer-ownership="none" closure="1">
|
|
<doc xml:space="preserve">function to call</doc>
|
|
<type name="SourceFunc" c:type="GSourceFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @function.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="idle_add_full" c:identifier="g_idle_add_full" shadows="idle_add">
|
|
<doc xml:space="preserve">Adds a function to be called whenever there are no higher priority
|
|
events pending. If the function returns %FALSE it is automatically
|
|
removed from the list of event sources and will not be called again.
|
|
|
|
See [memory management of sources][mainloop-memory-management] for details
|
|
on how to handle the return value and memory management of @data.
|
|
|
|
This internally creates a main loop source using g_idle_source_new()
|
|
and attaches it to the global #GMainContext using g_source_attach(), so
|
|
the callback will be invoked in whichever thread is running that main
|
|
context. You can do these steps manually if you need greater control or to
|
|
use a custom main context.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the ID (greater than 0) of the event source.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="priority" transfer-ownership="none">
|
|
<doc xml:space="preserve">the priority of the idle source. Typically this will be in the
|
|
range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="function" transfer-ownership="none" scope="notified" closure="2" destroy="3">
|
|
<doc xml:space="preserve">function to call</doc>
|
|
<type name="SourceFunc" c:type="GSourceFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">function to call when the idle is removed, or %NULL</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="idle_remove_by_data" c:identifier="g_idle_remove_by_data">
|
|
<doc xml:space="preserve">Removes the idle function with the given data.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if an idle source was found and removed.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the idle source's callback.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="idle_source_new" c:identifier="g_idle_source_new">
|
|
<doc xml:space="preserve">Creates a new idle source.
|
|
|
|
The source will not initially be associated with any #GMainContext
|
|
and must be added to one with g_source_attach() before it will be
|
|
executed. Note that the default priority for idle sources is
|
|
%G_PRIORITY_DEFAULT_IDLE, as compared to other sources which
|
|
have a default priority of %G_PRIORITY_DEFAULT.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the newly-created idle source</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="int64_equal" c:identifier="g_int64_equal" version="2.22">
|
|
<doc xml:space="preserve">Compares the two #gint64 values being pointed to and returns
|
|
%TRUE if they are equal.
|
|
It can be passed to g_hash_table_new() as the @key_equal_func
|
|
parameter, when using non-%NULL pointers to 64-bit integers as keys in a
|
|
#GHashTable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the two keys match.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="v1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gint64 key</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="v2" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gint64 key to compare with @v1</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="int64_hash" c:identifier="g_int64_hash" version="2.22">
|
|
<doc xml:space="preserve">Converts a pointer to a #gint64 to a hash value.
|
|
|
|
It can be passed to g_hash_table_new() as the @hash_func parameter,
|
|
when using non-%NULL pointers to 64-bit integer values as keys in a
|
|
#GHashTable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a hash value corresponding to the key.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="v" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gint64 key</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="int_equal" c:identifier="g_int_equal">
|
|
<doc xml:space="preserve">Compares the two #gint values being pointed to and returns
|
|
%TRUE if they are equal.
|
|
It can be passed to g_hash_table_new() as the @key_equal_func
|
|
parameter, when using non-%NULL pointers to integers as keys in a
|
|
#GHashTable.
|
|
|
|
Note that this function acts on pointers to #gint, not on #gint
|
|
directly: if your hash table's keys are of the form
|
|
`GINT_TO_POINTER (n)`, use g_direct_equal() instead.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the two keys match.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="v1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gint key</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="v2" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gint key to compare with @v1</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="int_hash" c:identifier="g_int_hash">
|
|
<doc xml:space="preserve">Converts a pointer to a #gint to a hash value.
|
|
It can be passed to g_hash_table_new() as the @hash_func parameter,
|
|
when using non-%NULL pointers to integer values as keys in a #GHashTable.
|
|
|
|
Note that this function acts on pointers to #gint, not on #gint
|
|
directly: if your hash table's keys are of the form
|
|
`GINT_TO_POINTER (n)`, use g_direct_hash() instead.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a hash value corresponding to the key.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="v" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gint key</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="intern_static_string" c:identifier="g_intern_static_string" version="2.10">
|
|
<doc xml:space="preserve">Returns a canonical representation for @string. Interned strings
|
|
can be compared for equality by comparing the pointers, instead of
|
|
using strcmp(). g_intern_static_string() does not copy the string,
|
|
therefore @string must not be freed or modified.
|
|
|
|
This function must not be used before library constructors have finished
|
|
running. In particular, this means it cannot be used to initialize global
|
|
variables in C++.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a canonical representation for the string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a static string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="intern_string" c:identifier="g_intern_string" version="2.10">
|
|
<doc xml:space="preserve">Returns a canonical representation for @string. Interned strings
|
|
can be compared for equality by comparing the pointers, instead of
|
|
using strcmp().
|
|
|
|
This function must not be used before library constructors have finished
|
|
running. In particular, this means it cannot be used to initialize global
|
|
variables in C++.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a canonical representation for the string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="io_add_watch" c:identifier="g_io_add_watch" shadowed-by="io_add_watch_full" introspectable="0">
|
|
<doc xml:space="preserve">Adds the #GIOChannel into the default main loop context
|
|
with the default priority.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the event source id</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</parameter>
|
|
<parameter name="condition" transfer-ownership="none">
|
|
<doc xml:space="preserve">the condition to watch for</doc>
|
|
<type name="IOCondition" c:type="GIOCondition"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" closure="3">
|
|
<doc xml:space="preserve">the function to call when the condition is satisfied</doc>
|
|
<type name="IOFunc" c:type="GIOFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to @func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="io_add_watch_full" c:identifier="g_io_add_watch_full" shadows="io_add_watch">
|
|
<doc xml:space="preserve">Adds the #GIOChannel into the default main loop context
|
|
with the given priority.
|
|
|
|
This internally creates a main loop source using g_io_create_watch()
|
|
and attaches it to the main loop context with g_source_attach().
|
|
You can do these steps manually if you need greater control.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the event source id</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</parameter>
|
|
<parameter name="priority" transfer-ownership="none">
|
|
<doc xml:space="preserve">the priority of the #GIOChannel source</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="condition" transfer-ownership="none">
|
|
<doc xml:space="preserve">the condition to watch for</doc>
|
|
<type name="IOCondition" c:type="GIOCondition"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none" scope="notified" closure="4" destroy="5">
|
|
<doc xml:space="preserve">the function to call when the condition is satisfied</doc>
|
|
<type name="IOFunc" c:type="GIOFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data to pass to @func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="notify" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">the function to call when the source is removed</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="io_channel_error_from_errno" c:identifier="g_io_channel_error_from_errno" moved-to="IOChannel.error_from_errno">
|
|
<doc xml:space="preserve">Converts an `errno` error number to a #GIOChannelError.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannelError error number, e.g.
|
|
%G_IO_CHANNEL_ERROR_INVAL.</doc>
|
|
<type name="IOChannelError" c:type="GIOChannelError"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="en" transfer-ownership="none">
|
|
<doc xml:space="preserve">an `errno` error number, e.g. `EINVAL`</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="io_channel_error_quark" c:identifier="g_io_channel_error_quark" moved-to="IOChannel.error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="io_create_watch" c:identifier="g_io_create_watch">
|
|
<doc xml:space="preserve">Creates a #GSource that's dispatched when @condition is met for the
|
|
given @channel. For example, if condition is #G_IO_IN, the source will
|
|
be dispatched when there's data available for reading.
|
|
|
|
The callback function invoked by the #GSource should be added with
|
|
g_source_set_callback(), but it has type #GIOFunc (not #GSourceFunc).
|
|
|
|
g_io_add_watch() is a simpler interface to this same functionality, for
|
|
the case where you want to add the source to the default main loop context
|
|
at the default priority.
|
|
|
|
On Windows, polling a #GSource created to watch a channel for a socket
|
|
puts the socket in non-blocking mode. This is a side-effect of the
|
|
implementation and unavoidable.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="channel" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GIOChannel to watch</doc>
|
|
<type name="IOChannel" c:type="GIOChannel*"/>
|
|
</parameter>
|
|
<parameter name="condition" transfer-ownership="none">
|
|
<doc xml:space="preserve">conditions to watch for</doc>
|
|
<type name="IOCondition" c:type="GIOCondition"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="iochannels">
|
|
<doc xml:space="preserve">The #GIOChannel data type aims to provide a portable method for
|
|
using file descriptors, pipes, and sockets, and integrating them
|
|
into the [main event loop][glib-The-Main-Event-Loop]. Currently,
|
|
full support is available on UNIX platforms, support for Windows
|
|
is only partially complete.
|
|
|
|
To create a new #GIOChannel on UNIX systems use
|
|
g_io_channel_unix_new(). This works for plain file descriptors,
|
|
pipes and sockets. Alternatively, a channel can be created for a
|
|
file in a system independent manner using g_io_channel_new_file().
|
|
|
|
Once a #GIOChannel has been created, it can be used in a generic
|
|
manner with the functions g_io_channel_read_chars(),
|
|
g_io_channel_write_chars(), g_io_channel_seek_position(), and
|
|
g_io_channel_shutdown().
|
|
|
|
To add a #GIOChannel to the [main event loop][glib-The-Main-Event-Loop],
|
|
use g_io_add_watch() or g_io_add_watch_full(). Here you specify which
|
|
events you are interested in on the #GIOChannel, and provide a
|
|
function to be called whenever these events occur.
|
|
|
|
#GIOChannel instances are created with an initial reference count of 1.
|
|
g_io_channel_ref() and g_io_channel_unref() can be used to
|
|
increment or decrement the reference count respectively. When the
|
|
reference count falls to 0, the #GIOChannel is freed. (Though it
|
|
isn't closed automatically, unless it was created using
|
|
g_io_channel_new_file().) Using g_io_add_watch() or
|
|
g_io_add_watch_full() increments a channel's reference count.
|
|
|
|
The new functions g_io_channel_read_chars(),
|
|
g_io_channel_read_line(), g_io_channel_read_line_string(),
|
|
g_io_channel_read_to_end(), g_io_channel_write_chars(),
|
|
g_io_channel_seek_position(), and g_io_channel_flush() should not be
|
|
mixed with the deprecated functions g_io_channel_read(),
|
|
g_io_channel_write(), and g_io_channel_seek() on the same channel.</doc>
|
|
</docsection>
|
|
<function name="key_file_error_quark" c:identifier="g_key_file_error_quark" moved-to="KeyFile.error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<docsection name="keyfile">
|
|
<doc xml:space="preserve">#GKeyFile lets you parse, edit or create files containing groups of
|
|
key-value pairs, which we call "key files" for lack of a better name.
|
|
Several freedesktop.org specifications use key files now, e.g the
|
|
[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec)
|
|
and the
|
|
[Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec).
|
|
|
|
The syntax of key files is described in detail in the
|
|
[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec),
|
|
here is a quick summary: Key files
|
|
consists of groups of key-value pairs, interspersed with comments.
|
|
|
|
|[
|
|
# this is just an example
|
|
# there can be comments before the first group
|
|
|
|
[First Group]
|
|
|
|
Name=Key File Example\tthis value shows\nescaping
|
|
|
|
# localized strings are stored in multiple key-value pairs
|
|
Welcome=Hello
|
|
Welcome[de]=Hallo
|
|
Welcome[fr_FR]=Bonjour
|
|
Welcome[it]=Ciao
|
|
Welcome[be@latin]=Hello
|
|
|
|
[Another Group]
|
|
|
|
Numbers=2;20;-200;0
|
|
|
|
Booleans=true;false;true;true
|
|
]|
|
|
|
|
Lines beginning with a '#' and blank lines are considered comments.
|
|
|
|
Groups are started by a header line containing the group name enclosed
|
|
in '[' and ']', and ended implicitly by the start of the next group or
|
|
the end of the file. Each key-value pair must be contained in a group.
|
|
|
|
Key-value pairs generally have the form `key=value`, with the
|
|
exception of localized strings, which have the form
|
|
`key[locale]=value`, with a locale identifier of the
|
|
form `lang_COUNTRY@MODIFIER` where `COUNTRY` and `MODIFIER`
|
|
are optional.
|
|
Space before and after the '=' character are ignored. Newline, tab,
|
|
carriage return and backslash characters in value are escaped as \n,
|
|
\t, \r, and \\\\, respectively. To preserve leading spaces in values,
|
|
these can also be escaped as \s.
|
|
|
|
Key files can store strings (possibly with localized variants), integers,
|
|
booleans and lists of these. Lists are separated by a separator character,
|
|
typically ';' or ','. To use the list separator character in a value in
|
|
a list, it has to be escaped by prefixing it with a backslash.
|
|
|
|
This syntax is obviously inspired by the .ini files commonly met
|
|
on Windows, but there are some important differences:
|
|
|
|
- .ini files use the ';' character to begin comments,
|
|
key files use the '#' character.
|
|
|
|
- Key files do not allow for ungrouped keys meaning only
|
|
comments can precede the first group.
|
|
|
|
- Key files are always encoded in UTF-8.
|
|
|
|
- Key and Group names are case-sensitive. For example, a group called
|
|
[GROUP] is a different from [group].
|
|
|
|
- .ini files don't have a strongly typed boolean entry type,
|
|
they only have GetProfileInt(). In key files, only
|
|
true and false (in lower case) are allowed.
|
|
|
|
Note that in contrast to the
|
|
[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec),
|
|
groups in key files may contain the same
|
|
key multiple times; the last entry wins. Key files may also contain
|
|
multiple groups with the same name; they are merged together.
|
|
Another difference is that keys and group names in key files are not
|
|
restricted to ASCII characters.
|
|
|
|
Here is an example of loading a key file and reading a value:
|
|
|[<!-- language="C" -->
|
|
g_autoptr(GError) error = NULL;
|
|
g_autoptr(GKeyFile) key_file = g_key_file_new ();
|
|
|
|
if (!g_key_file_load_from_file (key_file, "key-file.ini", flags, &error))
|
|
{
|
|
if (!g_error_matches (error, G_FILE_ERROR, G_FILE_ERROR_NOENT))
|
|
g_warning ("Error loading key file: %s", error->message);
|
|
return;
|
|
}
|
|
|
|
g_autofree gchar *val = g_key_file_get_string (key_file, "Group Name", "SomeKey", &error);
|
|
if (val == NULL &&
|
|
!g_error_matches (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_KEY_NOT_FOUND))
|
|
{
|
|
g_warning ("Error finding key in key file: %s", error->message);
|
|
return;
|
|
}
|
|
else if (val == NULL)
|
|
{
|
|
// Fall back to a default value.
|
|
val = g_strdup ("default-value");
|
|
}
|
|
]|
|
|
|
|
Here is an example of creating and saving a key file:
|
|
|[<!-- language="C" -->
|
|
g_autoptr(GKeyFile) key_file = g_key_file_new ();
|
|
const gchar *val = …;
|
|
g_autoptr(GError) error = NULL;
|
|
|
|
g_key_file_set_string (key_file, "Group Name", "SomeKey", val);
|
|
|
|
// Save as a file.
|
|
if (!g_key_file_save_to_file (key_file, "key-file.ini", &error))
|
|
{
|
|
g_warning ("Error saving key file: %s", error->message);
|
|
return;
|
|
}
|
|
|
|
// Or store to a GBytes for use elsewhere.
|
|
gsize data_len;
|
|
g_autofree guint8 *data = (guint8 *) g_key_file_to_data (key_file, &data_len, &error);
|
|
if (data == NULL)
|
|
{
|
|
g_warning ("Error saving key file: %s", error->message);
|
|
return;
|
|
}
|
|
g_autoptr(GBytes) bytes = g_bytes_new_take (g_steal_pointer (&data), data_len);
|
|
]|</doc>
|
|
</docsection>
|
|
<docsection name="linked_lists_double">
|
|
<doc xml:space="preserve">The #GList structure and its associated functions provide a standard
|
|
doubly-linked list data structure. The benefit of this data-structure
|
|
is to provide insertion/deletion operations in O(1) complexity where
|
|
access/search operations are in O(n). The benefit of #GList over
|
|
#GSList (singly linked list) is that the worst case on access/search
|
|
operations is divided by two which comes at a cost in space as we need
|
|
to retain two pointers in place of one.
|
|
|
|
Each element in the list contains a piece of data, together with
|
|
pointers which link to the previous and next elements in the list.
|
|
Using these pointers it is possible to move through the list in both
|
|
directions (unlike the singly-linked [GSList][glib-Singly-Linked-Lists],
|
|
which only allows movement through the list in the forward direction).
|
|
|
|
The double linked list does not keep track of the number of items
|
|
and does not keep track of both the start and end of the list. If
|
|
you want fast access to both the start and the end of the list,
|
|
and/or the number of items in the list, use a
|
|
[GQueue][glib-Double-ended-Queues] instead.
|
|
|
|
The data contained in each element can be either integer values, by
|
|
using one of the [Type Conversion Macros][glib-Type-Conversion-Macros],
|
|
or simply pointers to any type of data.
|
|
|
|
List elements are allocated from the [slice allocator][glib-Memory-Slices],
|
|
which is more efficient than allocating elements individually.
|
|
|
|
Note that most of the #GList functions expect to be passed a pointer
|
|
to the first element in the list. The functions which insert
|
|
elements return the new start of the list, which may have changed.
|
|
|
|
There is no function to create a #GList. %NULL is considered to be
|
|
a valid, empty list so you simply set a #GList* to %NULL to initialize
|
|
it.
|
|
|
|
To add elements, use g_list_append(), g_list_prepend(),
|
|
g_list_insert() and g_list_insert_sorted().
|
|
|
|
To visit all elements in the list, use a loop over the list:
|
|
|[<!-- language="C" -->
|
|
GList *l;
|
|
for (l = list; l != NULL; l = l->next)
|
|
{
|
|
// do something with l->data
|
|
}
|
|
]|
|
|
|
|
To call a function for each element in the list, use g_list_foreach().
|
|
|
|
To loop over the list and modify it (e.g. remove a certain element)
|
|
a while loop is more appropriate, for example:
|
|
|[<!-- language="C" -->
|
|
GList *l = list;
|
|
while (l != NULL)
|
|
{
|
|
GList *next = l->next;
|
|
if (should_be_removed (l))
|
|
{
|
|
// possibly free l->data
|
|
list = g_list_delete_link (list, l);
|
|
}
|
|
l = next;
|
|
}
|
|
]|
|
|
|
|
To remove elements, use g_list_remove().
|
|
|
|
To navigate in a list, use g_list_first(), g_list_last(),
|
|
g_list_next(), g_list_previous().
|
|
|
|
To find elements in the list use g_list_nth(), g_list_nth_data(),
|
|
g_list_find() and g_list_find_custom().
|
|
|
|
To find the index of an element use g_list_position() and
|
|
g_list_index().
|
|
|
|
To free the entire list, use g_list_free() or g_list_free_full().</doc>
|
|
</docsection>
|
|
<docsection name="linked_lists_single">
|
|
<doc xml:space="preserve">The #GSList structure and its associated functions provide a
|
|
standard singly-linked list data structure. The benefit of this
|
|
data-structure is to provide insertion/deletion operations in O(1)
|
|
complexity where access/search operations are in O(n). The benefit
|
|
of #GSList over #GList (doubly linked list) is that they are lighter
|
|
in space as they only need to retain one pointer but it double the
|
|
cost of the worst case access/search operations.
|
|
|
|
Each element in the list contains a piece of data, together with a
|
|
pointer which links to the next element in the list. Using this
|
|
pointer it is possible to move through the list in one direction
|
|
only (unlike the [double-linked lists][glib-Doubly-Linked-Lists],
|
|
which allow movement in both directions).
|
|
|
|
The data contained in each element can be either integer values, by
|
|
using one of the [Type Conversion Macros][glib-Type-Conversion-Macros],
|
|
or simply pointers to any type of data.
|
|
|
|
List elements are allocated from the [slice allocator][glib-Memory-Slices],
|
|
which is more efficient than allocating elements individually.
|
|
|
|
Note that most of the #GSList functions expect to be passed a
|
|
pointer to the first element in the list. The functions which insert
|
|
elements return the new start of the list, which may have changed.
|
|
|
|
There is no function to create a #GSList. %NULL is considered to be
|
|
the empty list so you simply set a #GSList* to %NULL.
|
|
|
|
To add elements, use g_slist_append(), g_slist_prepend(),
|
|
g_slist_insert() and g_slist_insert_sorted().
|
|
|
|
To remove elements, use g_slist_remove().
|
|
|
|
To find elements in the list use g_slist_last(), g_slist_next(),
|
|
g_slist_nth(), g_slist_nth_data(), g_slist_find() and
|
|
g_slist_find_custom().
|
|
|
|
To find the index of an element use g_slist_position() and
|
|
g_slist_index().
|
|
|
|
To call a function for each element in the list use
|
|
g_slist_foreach().
|
|
|
|
To free the entire list, use g_slist_free().</doc>
|
|
</docsection>
|
|
<function-macro name="list_next" c:identifier="g_list_next" introspectable="0">
|
|
<doc xml:space="preserve">A convenience macro to get the next element in a #GList.
|
|
Note that it is considered perfectly acceptable to access
|
|
@list->next directly.</doc>
|
|
<parameters>
|
|
<parameter name="list">
|
|
<doc xml:space="preserve">an element in a #GList</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="list_previous" c:identifier="g_list_previous" introspectable="0">
|
|
<doc xml:space="preserve">A convenience macro to get the previous element in a #GList.
|
|
Note that it is considered perfectly acceptable to access
|
|
@list->prev directly.</doc>
|
|
<parameters>
|
|
<parameter name="list">
|
|
<doc xml:space="preserve">an element in a #GList</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="listenv" c:identifier="g_listenv" version="2.8">
|
|
<doc xml:space="preserve">Gets the names of all variables set in the environment.
|
|
|
|
Programs that want to be portable to Windows should typically use
|
|
this function and g_getenv() instead of using the environ array
|
|
from the C library directly. On Windows, the strings in the environ
|
|
array are in system codepage encoding, while in most of the typical
|
|
use cases for environment variables in GLib-using programs you want
|
|
the UTF-8 encoding that this function and g_getenv() provide.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">
|
|
a %NULL-terminated list of strings which must be freed with
|
|
g_strfreev().</doc>
|
|
<array c:type="gchar**">
|
|
<type name="filename"/>
|
|
</array>
|
|
</return-value>
|
|
</function>
|
|
<function name="locale_from_utf8" c:identifier="g_locale_from_utf8" throws="1">
|
|
<doc xml:space="preserve">Converts a string from UTF-8 to the encoding used for strings by
|
|
the C runtime (usually the same as that used by the operating
|
|
system) in the [current locale][setlocale]. On Windows this means
|
|
the system codepage.
|
|
|
|
The input string shall not contain nul characters even if the @len
|
|
argument is positive. A nul character found inside the string will result
|
|
in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. Use g_convert() to convert
|
|
input that may contain embedded nul characters.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">
|
|
A newly-allocated buffer containing the converted string,
|
|
or %NULL on an error, and error will be set.</doc>
|
|
<array length="3" zero-terminated="0" c:type="gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="utf8string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the string, or -1 if the string is
|
|
nul-terminated.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store the number of bytes in the
|
|
input string that were successfully converted, or %NULL.
|
|
Even if the conversion was successful, this may be
|
|
less than @len if there were partial characters
|
|
at the end of the input. If the error
|
|
%G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
|
|
stored will be the byte offset after the last valid
|
|
input sequence.</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
<parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">the number of bytes stored in the output
|
|
buffer (not including the terminating nul).</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="locale_to_utf8" c:identifier="g_locale_to_utf8" throws="1">
|
|
<doc xml:space="preserve">Converts a string which is in the encoding used for strings by
|
|
the C runtime (usually the same as that used by the operating
|
|
system) in the [current locale][setlocale] into a UTF-8 string.
|
|
|
|
If the source encoding is not UTF-8 and the conversion output contains a
|
|
nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the
|
|
function returns %NULL.
|
|
If the source encoding is UTF-8, an embedded nul character is treated with
|
|
the %G_CONVERT_ERROR_ILLEGAL_SEQUENCE error for backward compatibility with
|
|
earlier versions of this library. Use g_convert() to produce output that
|
|
may contain embedded nul characters.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">The converted string, or %NULL on an error.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="opsysstring" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string in the
|
|
encoding of the current locale. On Windows
|
|
this means the system codepage.</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the string, or -1 if the string is
|
|
nul-terminated (Note that some encodings may allow nul
|
|
bytes to occur inside strings. In that case, using -1
|
|
for the @len parameter is unsafe)</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="bytes_read" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store the number of bytes in the
|
|
input string that were successfully converted, or %NULL.
|
|
Even if the conversion was successful, this may be
|
|
less than @len if there were partial characters
|
|
at the end of the input. If the error
|
|
%G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
|
|
stored will be the byte offset after the last valid
|
|
input sequence.</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
<parameter name="bytes_written" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">the number of bytes stored in the output
|
|
buffer (not including the terminating nul).</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log" c:identifier="g_log" introspectable="0">
|
|
<doc xml:space="preserve">Logs an error or debugging message.
|
|
|
|
If the log level has been set as fatal, G_BREAKPOINT() is called
|
|
to terminate the program. See the documentation for G_BREAKPOINT() for
|
|
details of the debugging options this provides.
|
|
|
|
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
|
|
manually.
|
|
|
|
If [structured logging is enabled][using-structured-logging] this will
|
|
output via the structured log writer function (see g_log_set_writer_func()).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_domain" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the log domain, usually #G_LOG_DOMAIN, or %NULL
|
|
for the default</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="log_level" transfer-ownership="none">
|
|
<doc xml:space="preserve">the log level, either from #GLogLevelFlags
|
|
or a user-defined level</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">the message format. See the printf() documentation</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">the parameters to insert into the format string</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_default_handler" c:identifier="g_log_default_handler">
|
|
<doc xml:space="preserve">The default log handler set up by GLib; g_log_set_default_handler()
|
|
allows to install an alternate default log handler.
|
|
This is used if no log handler has been set for the particular log
|
|
domain and log level combination. It outputs the message to stderr
|
|
or stdout and if the log level is fatal it calls G_BREAKPOINT(). It automatically
|
|
prints a new-line character after the message, so one does not need to be
|
|
manually included in @message.
|
|
|
|
The behavior of this log handler can be influenced by a number of
|
|
environment variables:
|
|
|
|
- `G_MESSAGES_PREFIXED`: A :-separated list of log levels for which
|
|
messages should be prefixed by the program name and PID of the
|
|
application.
|
|
|
|
- `G_MESSAGES_DEBUG`: A space-separated list of log domains for
|
|
which debug and informational messages are printed. By default
|
|
these messages are not printed.
|
|
|
|
stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL,
|
|
%G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for
|
|
the rest.
|
|
|
|
This has no effect if structured logging is enabled; see
|
|
[Using Structured Logging][using-structured-logging].</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_domain" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the log domain of the message, or %NULL for the
|
|
default "" application domain</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="log_level" transfer-ownership="none">
|
|
<doc xml:space="preserve">the level of the message</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
<parameter name="message" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the message</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="unused_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data passed from g_log() which is unused</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_remove_handler" c:identifier="g_log_remove_handler">
|
|
<doc xml:space="preserve">Removes the log handler.
|
|
|
|
This has no effect if structured logging is enabled; see
|
|
[Using Structured Logging][using-structured-logging].</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_domain" transfer-ownership="none">
|
|
<doc xml:space="preserve">the log domain</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="handler_id" transfer-ownership="none">
|
|
<doc xml:space="preserve">the id of the handler, which was returned
|
|
in g_log_set_handler()</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_set_always_fatal" c:identifier="g_log_set_always_fatal">
|
|
<doc xml:space="preserve">Sets the message levels which are always fatal, in any log domain.
|
|
When a message with any of these levels is logged the program terminates.
|
|
You can only set the levels defined by GLib to be fatal.
|
|
%G_LOG_LEVEL_ERROR is always fatal.
|
|
|
|
You can also make some message levels fatal at runtime by setting
|
|
the `G_DEBUG` environment variable (see
|
|
[Running GLib Applications](glib-running.html)).
|
|
|
|
Libraries should not call this function, as it affects all messages logged
|
|
by a process, including those from other libraries.
|
|
|
|
Structured log messages (using g_log_structured() and
|
|
g_log_structured_array()) are fatal only if the default log writer is used;
|
|
otherwise it is up to the writer function to determine which log messages
|
|
are fatal. See [Using Structured Logging][using-structured-logging].</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the old fatal mask</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="fatal_mask" transfer-ownership="none">
|
|
<doc xml:space="preserve">the mask containing bits set for each level
|
|
of error which is to be fatal</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_set_default_handler" c:identifier="g_log_set_default_handler" version="2.6" introspectable="0">
|
|
<doc xml:space="preserve">Installs a default log handler which is used if no
|
|
log handler has been set for the particular log domain
|
|
and log level combination. By default, GLib uses
|
|
g_log_default_handler() as default log handler.
|
|
|
|
This has no effect if structured logging is enabled; see
|
|
[Using Structured Logging][using-structured-logging].</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the previous default log handler</doc>
|
|
<type name="LogFunc" c:type="GLogFunc"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_func" transfer-ownership="none" closure="1">
|
|
<doc xml:space="preserve">the log handler function</doc>
|
|
<type name="LogFunc" c:type="GLogFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data passed to the log handler</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_set_fatal_mask" c:identifier="g_log_set_fatal_mask">
|
|
<doc xml:space="preserve">Sets the log levels which are fatal in the given domain.
|
|
%G_LOG_LEVEL_ERROR is always fatal.
|
|
|
|
This has no effect on structured log messages (using g_log_structured() or
|
|
g_log_structured_array()). To change the fatal behaviour for specific log
|
|
messages, programs must install a custom log writer function using
|
|
g_log_set_writer_func(). See
|
|
[Using Structured Logging][using-structured-logging].
|
|
|
|
This function is mostly intended to be used with
|
|
%G_LOG_LEVEL_CRITICAL. You should typically not set
|
|
%G_LOG_LEVEL_WARNING, %G_LOG_LEVEL_MESSAGE, %G_LOG_LEVEL_INFO or
|
|
%G_LOG_LEVEL_DEBUG as fatal except inside of test programs.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the old fatal mask for the log domain</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_domain" transfer-ownership="none">
|
|
<doc xml:space="preserve">the log domain</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="fatal_mask" transfer-ownership="none">
|
|
<doc xml:space="preserve">the new fatal mask</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_set_handler" c:identifier="g_log_set_handler" shadowed-by="log_set_handler_full" introspectable="0">
|
|
<doc xml:space="preserve">Sets the log handler for a domain and a set of log levels.
|
|
To handle fatal and recursive messages the @log_levels parameter
|
|
must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION
|
|
bit flags.
|
|
|
|
Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if
|
|
you want to set a handler for this log level you must combine it with
|
|
#G_LOG_FLAG_FATAL.
|
|
|
|
This has no effect if structured logging is enabled; see
|
|
[Using Structured Logging][using-structured-logging].
|
|
|
|
Here is an example for adding a log handler for all warning messages
|
|
in the default domain:
|
|
|[<!-- language="C" -->
|
|
g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
|
|
| G_LOG_FLAG_RECURSION, my_log_handler, NULL);
|
|
]|
|
|
|
|
This example adds a log handler for all critical messages from GTK+:
|
|
|[<!-- language="C" -->
|
|
g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
|
|
| G_LOG_FLAG_RECURSION, my_log_handler, NULL);
|
|
]|
|
|
|
|
This example adds a log handler for all messages from GLib:
|
|
|[<!-- language="C" -->
|
|
g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
|
|
| G_LOG_FLAG_RECURSION, my_log_handler, NULL);
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the id of the new handler</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_domain" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the log domain, or %NULL for the default ""
|
|
application domain</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="log_levels" transfer-ownership="none">
|
|
<doc xml:space="preserve">the log levels to apply the log handler for.
|
|
To handle fatal and recursive messages as well, combine
|
|
the log levels with the #G_LOG_FLAG_FATAL and
|
|
#G_LOG_FLAG_RECURSION bit flags.</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
<parameter name="log_func" transfer-ownership="none" closure="3">
|
|
<doc xml:space="preserve">the log handler function</doc>
|
|
<type name="LogFunc" c:type="GLogFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data passed to the log handler</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_set_handler_full" c:identifier="g_log_set_handler_full" shadows="log_set_handler" version="2.46">
|
|
<doc xml:space="preserve">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].</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the id of the new handler</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_domain" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the log domain, or %NULL for the default ""
|
|
application domain</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="log_levels" transfer-ownership="none">
|
|
<doc xml:space="preserve">the log levels to apply the log handler for.
|
|
To handle fatal and recursive messages as well, combine
|
|
the log levels with the #G_LOG_FLAG_FATAL and
|
|
#G_LOG_FLAG_RECURSION bit flags.</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
<parameter name="log_func" transfer-ownership="none" scope="notified" closure="3" destroy="4">
|
|
<doc xml:space="preserve">the log handler function</doc>
|
|
<type name="LogFunc" c:type="GLogFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data passed to the log handler</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="destroy" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">destroy notify for @user_data, or %NULL</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_set_writer_func" c:identifier="g_log_set_writer_func" version="2.50">
|
|
<doc xml:space="preserve">Set a writer function which will be called to format and write out each log
|
|
message. Each program should set a writer function, or the default writer
|
|
(g_log_writer_default()) will be used.
|
|
|
|
Libraries **must not** call this function — only programs are allowed to
|
|
install a writer function, as there must be a single, central point where
|
|
log messages are formatted and outputted.
|
|
|
|
There can only be one writer function. It is an error to set more than one.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="func" transfer-ownership="none" nullable="1" allow-none="1" scope="notified" closure="1" destroy="2">
|
|
<doc xml:space="preserve">log writer function, which must not be %NULL</doc>
|
|
<type name="LogWriterFunc" c:type="GLogWriterFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1" closure="0">
|
|
<doc xml:space="preserve">user data to pass to @func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="user_data_free" transfer-ownership="none" scope="async" destroy="0">
|
|
<doc xml:space="preserve">function to free @user_data once it’s
|
|
finished with, if non-%NULL</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_structured" c:identifier="g_log_structured" version="2.50" introspectable="0">
|
|
<doc xml:space="preserve">Log a message with structured data. The message will be passed through to
|
|
the log writer set by the application using g_log_set_writer_func(). If the
|
|
message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will
|
|
be aborted by calling G_BREAKPOINT() at the end of this function. If the log writer returns
|
|
%G_LOG_WRITER_UNHANDLED (failure), no other fallback writers will be tried.
|
|
See the documentation for #GLogWriterFunc for information on chaining
|
|
writers.
|
|
|
|
The structured data is provided as key–value pairs, where keys are UTF-8
|
|
strings, and values are arbitrary pointers — typically pointing to UTF-8
|
|
strings, but that is not a requirement. To pass binary (non-nul-terminated)
|
|
structured data, use g_log_structured_array(). The keys for structured data
|
|
should follow the [systemd journal
|
|
fields](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html)
|
|
specification. It is suggested that custom keys are namespaced according to
|
|
the code which sets them. For example, custom keys from GLib all have a
|
|
`GLIB_` prefix.
|
|
|
|
The @log_domain will be converted into a `GLIB_DOMAIN` field. @log_level will
|
|
be converted into a
|
|
[`PRIORITY`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#PRIORITY=)
|
|
field. The format string will have its placeholders substituted for the provided
|
|
values and be converted into a
|
|
[`MESSAGE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE=)
|
|
field.
|
|
|
|
Other fields you may commonly want to pass into this function:
|
|
|
|
* [`MESSAGE_ID`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=)
|
|
* [`CODE_FILE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FILE=)
|
|
* [`CODE_LINE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_LINE=)
|
|
* [`CODE_FUNC`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FUNC=)
|
|
* [`ERRNO`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#ERRNO=)
|
|
|
|
Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by
|
|
the logging macros, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(),
|
|
g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including
|
|
glib.h.
|
|
|
|
For example:
|
|
|[<!-- language="C" -->
|
|
g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,
|
|
"MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e",
|
|
"MY_APPLICATION_CUSTOM_FIELD", "some debug string",
|
|
"MESSAGE", "This is a debug message about pointer %p and integer %u.",
|
|
some_pointer, some_integer);
|
|
]|
|
|
|
|
Note that each `MESSAGE_ID` must be [uniquely and randomly
|
|
generated](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=).
|
|
If adding a `MESSAGE_ID`, consider shipping a [message
|
|
catalog](https://www.freedesktop.org/wiki/Software/systemd/catalog/) with
|
|
your software.
|
|
|
|
To pass a user data pointer to the log writer function which is specific to
|
|
this logging call, you must use g_log_structured_array() and pass the pointer
|
|
as a field with #GLogField.length set to zero, otherwise it will be
|
|
interpreted as a string.
|
|
|
|
For example:
|
|
|[<!-- language="C" -->
|
|
const GLogField fields[] = {
|
|
{ "MESSAGE", "This is a debug message.", -1 },
|
|
{ "MESSAGE_ID", "fcfb2e1e65c3494386b74878f1abf893", -1 },
|
|
{ "MY_APPLICATION_CUSTOM_FIELD", "some debug string", -1 },
|
|
{ "MY_APPLICATION_STATE", state_object, 0 },
|
|
};
|
|
g_log_structured_array (G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields));
|
|
]|
|
|
|
|
Note also that, even if no other structured fields are specified, there
|
|
must always be a `MESSAGE` key before the format string. The `MESSAGE`-format
|
|
pair has to be the last of the key-value pairs, and `MESSAGE` is the only
|
|
field for which printf()-style formatting is supported.
|
|
|
|
The default writer function for `stdout` and `stderr` will automatically
|
|
append a new-line character after the message, so you should not add one
|
|
manually to the format string.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_domain" transfer-ownership="none">
|
|
<doc xml:space="preserve">log domain, usually %G_LOG_DOMAIN</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="log_level" transfer-ownership="none">
|
|
<doc xml:space="preserve">log level, either from #GLogLevelFlags, or a user-defined
|
|
level</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">key-value pairs of structured data to add to the log entry, followed
|
|
by the key "MESSAGE", followed by a printf()-style message format,
|
|
followed by parameters to insert in the format string</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_structured_array" c:identifier="g_log_structured_array" version="2.50">
|
|
<doc xml:space="preserve">Log a message with structured data. The message will be passed through to the
|
|
log writer set by the application using g_log_set_writer_func(). If the
|
|
message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will
|
|
be aborted at the end of this function.
|
|
|
|
See g_log_structured() for more documentation.
|
|
|
|
This assumes that @log_level is already present in @fields (typically as the
|
|
`PRIORITY` field).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_level" transfer-ownership="none">
|
|
<doc xml:space="preserve">log level, either from #GLogLevelFlags, or a user-defined
|
|
level</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
<parameter name="fields" transfer-ownership="none">
|
|
<doc xml:space="preserve">key–value pairs of structured data to add
|
|
to the log message</doc>
|
|
<array length="2" zero-terminated="0" c:type="const GLogField*">
|
|
<type name="LogField" c:type="GLogField"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="n_fields" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of elements in the @fields array</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_structured_standard" c:identifier="g_log_structured_standard" introspectable="0">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_domain" transfer-ownership="none">
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="log_level" transfer-ownership="none">
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
<parameter name="file" transfer-ownership="none">
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="line" transfer-ownership="none">
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="message_format" transfer-ownership="none">
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_variant" c:identifier="g_log_variant" version="2.50">
|
|
<doc xml:space="preserve">Log a message with structured data, accepting the data within a #GVariant. This
|
|
version is especially useful for use in other languages, via introspection.
|
|
|
|
The only mandatory item in the @fields dictionary is the "MESSAGE" which must
|
|
contain the text shown to the user.
|
|
|
|
The values in the @fields dictionary are likely to be of type String
|
|
(#G_VARIANT_TYPE_STRING). Array of bytes (#G_VARIANT_TYPE_BYTESTRING) is also
|
|
supported. In this case the message is handled as binary and will be forwarded
|
|
to the log writer as such. The size of the array should not be higher than
|
|
%G_MAXSSIZE. Otherwise it will be truncated to this size. For other types
|
|
g_variant_print() will be used to convert the value into a string.
|
|
|
|
For more details on its usage and about the parameters, see g_log_structured().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_domain" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">log domain, usually %G_LOG_DOMAIN</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="log_level" transfer-ownership="none">
|
|
<doc xml:space="preserve">log level, either from #GLogLevelFlags, or a user-defined
|
|
level</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
<parameter name="fields" transfer-ownership="none">
|
|
<doc xml:space="preserve">a dictionary (#GVariant of the type %G_VARIANT_TYPE_VARDICT)
|
|
containing the key-value pairs of message data.</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_writer_default" c:identifier="g_log_writer_default" version="2.50">
|
|
<doc xml:space="preserve">Format a structured log message and output it to the default log destination
|
|
for the platform. On Linux, this is typically the systemd journal, falling
|
|
back to `stdout` or `stderr` if running from the terminal or if output is
|
|
being redirected to a file.
|
|
|
|
Support for other platform-specific logging mechanisms may be added in
|
|
future. Distributors of GLib may modify this function to impose their own
|
|
(documented) platform-specific log writing policies.
|
|
|
|
This is suitable for use as a #GLogWriterFunc, and is the default writer used
|
|
if no other is set using g_log_set_writer_func().
|
|
|
|
As with g_log_default_handler(), this function drops debug and informational
|
|
messages unless their log domain (or `all`) is listed in the space-separated
|
|
`G_MESSAGES_DEBUG` environment variable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise</doc>
|
|
<type name="LogWriterOutput" c:type="GLogWriterOutput"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_level" transfer-ownership="none">
|
|
<doc xml:space="preserve">log level, either from #GLogLevelFlags, or a user-defined
|
|
level</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
<parameter name="fields" transfer-ownership="none">
|
|
<doc xml:space="preserve">key–value pairs of structured data forming
|
|
the log message</doc>
|
|
<array length="2" zero-terminated="0" c:type="const GLogField*">
|
|
<type name="LogField" c:type="GLogField"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="n_fields" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of elements in the @fields array</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to g_log_set_writer_func()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_writer_format_fields" c:identifier="g_log_writer_format_fields" version="2.50">
|
|
<doc xml:space="preserve">Format a structured log message as a string suitable for outputting to the
|
|
terminal (or elsewhere). This will include the values of all fields it knows
|
|
how to interpret, which includes `MESSAGE` and `GLIB_DOMAIN` (see the
|
|
documentation for g_log_structured()). It does not include values from
|
|
unknown fields.
|
|
|
|
The returned string does **not** have a trailing new-line character. It is
|
|
encoded in the character set of the current locale, which is not necessarily
|
|
UTF-8.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">string containing the formatted log message, in
|
|
the character set of the current locale</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_level" transfer-ownership="none">
|
|
<doc xml:space="preserve">log level, either from #GLogLevelFlags, or a user-defined
|
|
level</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
<parameter name="fields" transfer-ownership="none">
|
|
<doc xml:space="preserve">key–value pairs of structured data forming
|
|
the log message</doc>
|
|
<array length="2" zero-terminated="0" c:type="const GLogField*">
|
|
<type name="LogField" c:type="GLogField"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="n_fields" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of elements in the @fields array</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="use_color" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE to use ANSI color escape sequences when formatting the
|
|
message, %FALSE to not</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_writer_is_journald" c:identifier="g_log_writer_is_journald" version="2.50">
|
|
<doc xml:space="preserve">Check whether the given @output_fd file descriptor is a connection to the
|
|
systemd journal, or something else (like a log file or `stdout` or
|
|
`stderr`).
|
|
|
|
Invalid file descriptors are accepted and return %FALSE, which allows for
|
|
the following construct without needing any additional error handling:
|
|
|[<!-- language="C" -->
|
|
is_journald = g_log_writer_is_journald (fileno (stderr));
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @output_fd points to the journal, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="output_fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">output file descriptor to check</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_writer_journald" c:identifier="g_log_writer_journald" version="2.50">
|
|
<doc xml:space="preserve">Format a structured log message and send it to the systemd journal as a set
|
|
of key–value pairs. All fields are sent to the journal, but if a field has
|
|
length zero (indicating program-specific data) then only its key will be
|
|
sent.
|
|
|
|
This is suitable for use as a #GLogWriterFunc.
|
|
|
|
If GLib has been compiled without systemd support, this function is still
|
|
defined, but will always return %G_LOG_WRITER_UNHANDLED.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise</doc>
|
|
<type name="LogWriterOutput" c:type="GLogWriterOutput"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_level" transfer-ownership="none">
|
|
<doc xml:space="preserve">log level, either from #GLogLevelFlags, or a user-defined
|
|
level</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
<parameter name="fields" transfer-ownership="none">
|
|
<doc xml:space="preserve">key–value pairs of structured data forming
|
|
the log message</doc>
|
|
<array length="2" zero-terminated="0" c:type="const GLogField*">
|
|
<type name="LogField" c:type="GLogField"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="n_fields" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of elements in the @fields array</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to g_log_set_writer_func()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_writer_standard_streams" c:identifier="g_log_writer_standard_streams" version="2.50">
|
|
<doc xml:space="preserve">Format a structured log message and print it to either `stdout` or `stderr`,
|
|
depending on its log level. %G_LOG_LEVEL_INFO and %G_LOG_LEVEL_DEBUG messages
|
|
are sent to `stdout`; all other log levels are sent to `stderr`. Only fields
|
|
which are understood by this function are included in the formatted string
|
|
which is printed.
|
|
|
|
If the output stream supports ANSI color escape sequences, they will be used
|
|
in the output.
|
|
|
|
A trailing new-line character is added to the log message when it is printed.
|
|
|
|
This is suitable for use as a #GLogWriterFunc.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise</doc>
|
|
<type name="LogWriterOutput" c:type="GLogWriterOutput"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_level" transfer-ownership="none">
|
|
<doc xml:space="preserve">log level, either from #GLogLevelFlags, or a user-defined
|
|
level</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
<parameter name="fields" transfer-ownership="none">
|
|
<doc xml:space="preserve">key–value pairs of structured data forming
|
|
the log message</doc>
|
|
<array length="2" zero-terminated="0" c:type="const GLogField*">
|
|
<type name="LogField" c:type="GLogField"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="n_fields" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of elements in the @fields array</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data passed to g_log_set_writer_func()</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="log_writer_supports_color" c:identifier="g_log_writer_supports_color" version="2.50">
|
|
<doc xml:space="preserve">Check whether the given @output_fd file descriptor supports ANSI color
|
|
escape sequences. If so, they can safely be used when formatting log
|
|
messages.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if ANSI color escapes are supported, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="output_fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">output file descriptor to check</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="logv" c:identifier="g_logv" introspectable="0">
|
|
<doc xml:space="preserve">Logs an error or debugging message.
|
|
|
|
If the log level has been set as fatal, G_BREAKPOINT() is called
|
|
to terminate the program. See the documentation for G_BREAKPOINT() for
|
|
details of the debugging options this provides.
|
|
|
|
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
|
|
manually.
|
|
|
|
If [structured logging is enabled][using-structured-logging] this will
|
|
output via the structured log writer function (see g_log_set_writer_func()).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_domain" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the log domain, or %NULL for the default ""
|
|
application domain</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="log_level" transfer-ownership="none">
|
|
<doc xml:space="preserve">the log level</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">the message format. See the printf() documentation</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="args" transfer-ownership="none">
|
|
<doc xml:space="preserve">the parameters to insert into the format string</doc>
|
|
<type name="va_list" c:type="va_list"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="macro__has_attribute" c:identifier="g_macro__has_attribute" introspectable="0">
|
|
<parameters>
|
|
<parameter name="x">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="macro__has_builtin" c:identifier="g_macro__has_builtin" introspectable="0">
|
|
<parameters>
|
|
<parameter name="x">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="macro__has_feature" c:identifier="g_macro__has_feature" introspectable="0">
|
|
<parameters>
|
|
<parameter name="x">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<docsection name="macros">
|
|
<doc xml:space="preserve">These macros provide a few commonly-used features.</doc>
|
|
</docsection>
|
|
<docsection name="macros_misc">
|
|
<doc xml:space="preserve">These macros provide more specialized features which are not
|
|
needed so often by application programmers.</doc>
|
|
</docsection>
|
|
<docsection name="main">
|
|
<doc xml:space="preserve">The main event loop manages all the available sources of events for
|
|
GLib and GTK+ applications. These events can come from any number of
|
|
different types of sources such as file descriptors (plain files,
|
|
pipes or sockets) and timeouts. New types of event sources can also
|
|
be added using g_source_attach().
|
|
|
|
To allow multiple independent sets of sources to be handled in
|
|
different threads, each source is associated with a #GMainContext.
|
|
A #GMainContext can only be running in a single thread, but
|
|
sources can be added to it and removed from it from other threads. All
|
|
functions which operate on a #GMainContext or a built-in #GSource are
|
|
thread-safe.
|
|
|
|
Each event source is assigned a priority. The default priority,
|
|
#G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities.
|
|
Values greater than 0 denote lower priorities. Events from high priority
|
|
sources are always processed before events from lower priority sources.
|
|
|
|
Idle functions can also be added, and assigned a priority. These will
|
|
be run whenever no events with a higher priority are ready to be processed.
|
|
|
|
The #GMainLoop data type represents a main event loop. A GMainLoop is
|
|
created with g_main_loop_new(). After adding the initial event sources,
|
|
g_main_loop_run() is called. This continuously checks for new events from
|
|
each of the event sources and dispatches them. Finally, the processing of
|
|
an event from one of the sources leads to a call to g_main_loop_quit() to
|
|
exit the main loop, and g_main_loop_run() returns.
|
|
|
|
It is possible to create new instances of #GMainLoop recursively.
|
|
This is often used in GTK+ applications when showing modal dialog
|
|
boxes. Note that event sources are associated with a particular
|
|
#GMainContext, and will be checked and dispatched for all main
|
|
loops associated with that GMainContext.
|
|
|
|
GTK+ contains wrappers of some of these functions, e.g. gtk_main(),
|
|
gtk_main_quit() and gtk_events_pending().
|
|
|
|
## Creating new source types
|
|
|
|
One of the unusual features of the #GMainLoop functionality
|
|
is that new types of event source can be created and used in
|
|
addition to the builtin type of event source. A new event source
|
|
type is used for handling GDK events. A new source type is created
|
|
by "deriving" from the #GSource structure. The derived type of
|
|
source is represented by a structure that has the #GSource structure
|
|
as a first element, and other elements specific to the new source
|
|
type. To create an instance of the new source type, call
|
|
g_source_new() passing in the size of the derived structure and
|
|
a table of functions. These #GSourceFuncs determine the behavior of
|
|
the new source type.
|
|
|
|
New source types basically interact with the main context
|
|
in two ways. Their prepare function in #GSourceFuncs can set a timeout
|
|
to determine the maximum amount of time that the main loop will sleep
|
|
before checking the source again. In addition, or as well, the source
|
|
can add file descriptors to the set that the main context checks using
|
|
g_source_add_poll().
|
|
|
|
## Customizing the main loop iteration
|
|
|
|
Single iterations of a #GMainContext can be run with
|
|
g_main_context_iteration(). In some cases, more detailed control
|
|
of exactly how the details of the main loop work is desired, for
|
|
instance, when integrating the #GMainLoop with an external main loop.
|
|
In such cases, you can call the component functions of
|
|
g_main_context_iteration() directly. These functions are
|
|
g_main_context_prepare(), g_main_context_query(),
|
|
g_main_context_check() and g_main_context_dispatch().
|
|
|
|
## State of a Main Context # {#mainloop-states}
|
|
|
|
The operation of these functions can best be seen in terms
|
|
of a state diagram, as shown in this image.
|
|
|
|
|
|
|
|
On UNIX, the GLib mainloop is incompatible with fork(). Any program
|
|
using the mainloop must either exec() or exit() from the child
|
|
without returning to the mainloop.
|
|
|
|
## Memory management of sources # {#mainloop-memory-management}
|
|
|
|
There are two options for memory management of the user data passed to a
|
|
#GSource to be passed to its callback on invocation. This data is provided
|
|
in calls to g_timeout_add(), g_timeout_add_full(), g_idle_add(), etc. and
|
|
more generally, using g_source_set_callback(). This data is typically an
|
|
object which ‘owns’ the timeout or idle callback, such as a widget or a
|
|
network protocol implementation. In many cases, it is an error for the
|
|
callback to be invoked after this owning object has been destroyed, as that
|
|
results in use of freed memory.
|
|
|
|
The first, and preferred, option is to store the source ID returned by
|
|
functions such as g_timeout_add() or g_source_attach(), and explicitly
|
|
remove that source from the main context using g_source_remove() when the
|
|
owning object is finalized. This ensures that the callback can only be
|
|
invoked while the object is still alive.
|
|
|
|
The second option is to hold a strong reference to the object in the
|
|
callback, and to release it in the callback’s #GDestroyNotify. This ensures
|
|
that the object is kept alive until after the source is finalized, which is
|
|
guaranteed to be after it is invoked for the final time. The #GDestroyNotify
|
|
is another callback passed to the ‘full’ variants of #GSource functions (for
|
|
example, g_timeout_add_full()). It is called when the source is finalized,
|
|
and is designed for releasing references like this.
|
|
|
|
One important caveat of this second approach is that it will keep the object
|
|
alive indefinitely if the main loop is stopped before the #GSource is
|
|
invoked, which may be undesirable.</doc>
|
|
</docsection>
|
|
<function name="main_context_default" c:identifier="g_main_context_default" moved-to="MainContext.default">
|
|
<doc xml:space="preserve">Returns the global default main context. This is the main context
|
|
used for main loop functions when a main loop is not explicitly
|
|
specified, and corresponds to the "main" main loop. See also
|
|
g_main_context_get_thread_default().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the global default main context.</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="main_context_get_thread_default" c:identifier="g_main_context_get_thread_default" moved-to="MainContext.get_thread_default" version="2.22">
|
|
<doc xml:space="preserve">Gets the thread-default #GMainContext for this thread. Asynchronous
|
|
operations that want to be able to be run in contexts other than
|
|
the default one should call this method or
|
|
g_main_context_ref_thread_default() to get a #GMainContext to add
|
|
their #GSources to. (Note that even in single-threaded
|
|
programs applications may sometimes want to temporarily push a
|
|
non-default context, so it is not safe to assume that this will
|
|
always return %NULL if you are running in the default thread.)
|
|
|
|
If you need to hold a reference on the context, use
|
|
g_main_context_ref_thread_default() instead.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the thread-default #GMainContext, or
|
|
%NULL if the thread-default context is the global default context.</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="main_context_ref_thread_default" c:identifier="g_main_context_ref_thread_default" moved-to="MainContext.ref_thread_default" version="2.32">
|
|
<doc xml:space="preserve">Gets the thread-default #GMainContext for this thread, as with
|
|
g_main_context_get_thread_default(), but also adds a reference to
|
|
it with g_main_context_ref(). In addition, unlike
|
|
g_main_context_get_thread_default(), if the thread-default context
|
|
is the global default context, this will return that #GMainContext
|
|
(with a ref added to it) rather than returning %NULL.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the thread-default #GMainContext. Unref
|
|
with g_main_context_unref() when you are done with it.</doc>
|
|
<type name="MainContext" c:type="GMainContext*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="main_current_source" c:identifier="g_main_current_source" version="2.12">
|
|
<doc xml:space="preserve">Returns the currently firing source for this thread.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">The currently firing source or %NULL.</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="main_depth" c:identifier="g_main_depth">
|
|
<doc xml:space="preserve">Returns the depth of the stack of calls to
|
|
g_main_context_dispatch() on any #GMainContext in the current thread.
|
|
That is, when called from the toplevel, it gives 0. When
|
|
called from within a callback from g_main_context_iteration()
|
|
(or g_main_loop_run(), etc.) it returns 1. When called from within
|
|
a callback to a recursive call to g_main_context_iteration(),
|
|
it returns 2. And so forth.
|
|
|
|
This function is useful in a situation like the following:
|
|
Imagine an extremely simple "garbage collected" system.
|
|
|
|
|[<!-- language="C" -->
|
|
static GList *free_list;
|
|
|
|
gpointer
|
|
allocate_memory (gsize size)
|
|
{
|
|
gpointer result = g_malloc (size);
|
|
free_list = g_list_prepend (free_list, result);
|
|
return result;
|
|
}
|
|
|
|
void
|
|
free_allocated_memory (void)
|
|
{
|
|
GList *l;
|
|
for (l = free_list; l; l = l->next);
|
|
g_free (l->data);
|
|
g_list_free (free_list);
|
|
free_list = NULL;
|
|
}
|
|
|
|
[...]
|
|
|
|
while (TRUE);
|
|
{
|
|
g_main_context_iteration (NULL, TRUE);
|
|
free_allocated_memory();
|
|
}
|
|
]|
|
|
|
|
This works from an application, however, if you want to do the same
|
|
thing from a library, it gets more difficult, since you no longer
|
|
control the main loop. You might think you can simply use an idle
|
|
function to make the call to free_allocated_memory(), but that
|
|
doesn't work, since the idle function could be called from a
|
|
recursive callback. This can be fixed by using g_main_depth()
|
|
|
|
|[<!-- language="C" -->
|
|
gpointer
|
|
allocate_memory (gsize size)
|
|
{
|
|
FreeListBlock *block = g_new (FreeListBlock, 1);
|
|
block->mem = g_malloc (size);
|
|
block->depth = g_main_depth ();
|
|
free_list = g_list_prepend (free_list, block);
|
|
return block->mem;
|
|
}
|
|
|
|
void
|
|
free_allocated_memory (void)
|
|
{
|
|
GList *l;
|
|
|
|
int depth = g_main_depth ();
|
|
for (l = free_list; l; );
|
|
{
|
|
GList *next = l->next;
|
|
FreeListBlock *block = l->data;
|
|
if (block->depth > depth)
|
|
{
|
|
g_free (block->mem);
|
|
g_free (block);
|
|
free_list = g_list_delete_link (free_list, l);
|
|
}
|
|
|
|
l = next;
|
|
}
|
|
}
|
|
]|
|
|
|
|
There is a temptation to use g_main_depth() to solve
|
|
problems with reentrancy. For instance, while waiting for data
|
|
to be received from the network in response to a menu item,
|
|
the menu item might be selected again. It might seem that
|
|
one could make the menu item's callback return immediately
|
|
and do nothing if g_main_depth() returns a value greater than 1.
|
|
However, this should be avoided since the user then sees selecting
|
|
the menu item do nothing. Furthermore, you'll find yourself adding
|
|
these checks all over your code, since there are doubtless many,
|
|
many things that the user could do. Instead, you can use the
|
|
following techniques:
|
|
|
|
1. Use gtk_widget_set_sensitive() or modal dialogs to prevent
|
|
the user from interacting with elements while the main
|
|
loop is recursing.
|
|
|
|
2. Avoid main loop recursion in situations where you can't handle
|
|
arbitrary callbacks. Instead, structure your code so that you
|
|
simply return to the main loop and then get called again when
|
|
there is more work to do.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">The main loop recursion level in the current thread</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="malloc" c:identifier="g_malloc">
|
|
<doc xml:space="preserve">Allocates @n_bytes bytes of memory.
|
|
If @n_bytes is 0 it returns %NULL.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">a pointer to the allocated memory</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="n_bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes to allocate</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="malloc0" c:identifier="g_malloc0">
|
|
<doc xml:space="preserve">Allocates @n_bytes bytes of memory, initialized to 0's.
|
|
If @n_bytes is 0 it returns %NULL.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">a pointer to the allocated memory</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="n_bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes to allocate</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="malloc0_n" c:identifier="g_malloc0_n" version="2.24">
|
|
<doc xml:space="preserve">This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
|
|
but care is taken to detect possible overflow during multiplication.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">a pointer to the allocated memory</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="n_blocks" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of blocks to allocate</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="n_block_bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of each block in bytes</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="malloc_n" c:identifier="g_malloc_n" version="2.24">
|
|
<doc xml:space="preserve">This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
|
|
but care is taken to detect possible overflow during multiplication.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">a pointer to the allocated memory</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="n_blocks" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of blocks to allocate</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="n_block_bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of each block in bytes</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="markup">
|
|
<doc xml:space="preserve">The "GMarkup" parser is intended to parse a simple markup format
|
|
that's a subset of XML. This is a small, efficient, easy-to-use
|
|
parser. It should not be used if you expect to interoperate with
|
|
other applications generating full-scale XML, and must not be used if you
|
|
expect to parse untrusted input. However, it's very
|
|
useful for application data files, config files, etc. where you
|
|
know your application will be the only one writing the file.
|
|
Full-scale XML parsers should be able to parse the subset used by
|
|
GMarkup, so you can easily migrate to full-scale XML at a later
|
|
time if the need arises.
|
|
|
|
GMarkup is not guaranteed to signal an error on all invalid XML;
|
|
the parser may accept documents that an XML parser would not.
|
|
However, XML documents which are not well-formed (which is a
|
|
weaker condition than being valid. See the
|
|
[XML specification](http://www.w3.org/TR/REC-xml/)
|
|
for definitions of these terms.) are not considered valid GMarkup
|
|
documents.
|
|
|
|
Simplifications to XML include:
|
|
|
|
- Only UTF-8 encoding is allowed
|
|
|
|
- No user-defined entities
|
|
|
|
- Processing instructions, comments and the doctype declaration
|
|
are "passed through" but are not interpreted in any way
|
|
|
|
- No DTD or validation
|
|
|
|
The markup format does support:
|
|
|
|
- Elements
|
|
|
|
- Attributes
|
|
|
|
- 5 standard entities: &amp; &lt; &gt; &quot; &apos;
|
|
|
|
- Character references
|
|
|
|
- Sections marked as CDATA</doc>
|
|
</docsection>
|
|
<function name="markup_collect_attributes" c:identifier="g_markup_collect_attributes" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Collects the attributes of the element from the data passed to the
|
|
#GMarkupParser start_element function, dealing with common error
|
|
conditions and supporting boolean values.
|
|
|
|
This utility function is not required to write a parser but can save
|
|
a lot of typing.
|
|
|
|
The @element_name, @attribute_names, @attribute_values and @error
|
|
parameters passed to the start_element callback should be passed
|
|
unmodified to this function.
|
|
|
|
Following these arguments is a list of "supported" attributes to collect.
|
|
It is an error to specify multiple attributes with the same name. If any
|
|
attribute not in the list appears in the @attribute_names array then an
|
|
unknown attribute error will result.
|
|
|
|
The #GMarkupCollectType field allows specifying the type of collection
|
|
to perform and if a given attribute must appear or is optional.
|
|
|
|
The attribute name is simply the name of the attribute to collect.
|
|
|
|
The pointer should be of the appropriate type (see the descriptions
|
|
under #GMarkupCollectType) and may be %NULL in case a particular
|
|
attribute is to be allowed but ignored.
|
|
|
|
This function deals with issuing errors for missing attributes
|
|
(of type %G_MARKUP_ERROR_MISSING_ATTRIBUTE), unknown attributes
|
|
(of type %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE) and duplicate
|
|
attributes (of type %G_MARKUP_ERROR_INVALID_CONTENT) as well
|
|
as parse errors for boolean-valued attributes (again of type
|
|
%G_MARKUP_ERROR_INVALID_CONTENT). In all of these cases %FALSE
|
|
will be returned and @error will be set as appropriate.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if successful</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="element_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">the current tag name</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="attribute_names" transfer-ownership="none">
|
|
<doc xml:space="preserve">the attribute names</doc>
|
|
<type name="utf8" c:type="const gchar**"/>
|
|
</parameter>
|
|
<parameter name="attribute_values" transfer-ownership="none">
|
|
<doc xml:space="preserve">the attribute values</doc>
|
|
<type name="utf8" c:type="const gchar**"/>
|
|
</parameter>
|
|
<parameter name="error" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #GError or %NULL</doc>
|
|
<type name="Error" c:type="GError**"/>
|
|
</parameter>
|
|
<parameter name="first_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GMarkupCollectType of the first attribute</doc>
|
|
<type name="MarkupCollectType" c:type="GMarkupCollectType"/>
|
|
</parameter>
|
|
<parameter name="first_attr" transfer-ownership="none">
|
|
<doc xml:space="preserve">the name of the first attribute</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to the storage location of the first attribute
|
|
(or %NULL), followed by more types names and pointers, ending
|
|
with %G_MARKUP_COLLECT_INVALID</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="markup_error_quark" c:identifier="g_markup_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="markup_escape_text" c:identifier="g_markup_escape_text">
|
|
<doc xml:space="preserve">Escapes text so that the markup parser will parse it verbatim.
|
|
Less than, greater than, ampersand, etc. are replaced with the
|
|
corresponding entities. This function would typically be used
|
|
when writing out a file to be parsed with the markup parser.
|
|
|
|
Note that this function doesn't protect whitespace and line endings
|
|
from being processed according to the XML rules for normalization
|
|
of line endings and attribute values.
|
|
|
|
Note also that this function will produce character references in
|
|
the range of &#x1; ... &#x1f; for all control sequences
|
|
except for tabstop, newline and carriage return. The character
|
|
references in this range are not valid XML 1.0, but they are
|
|
valid XML 1.1 and will be accepted by the GMarkup parser.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string with the escaped text</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="text" transfer-ownership="none">
|
|
<doc xml:space="preserve">some valid UTF-8 text</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @text in bytes, or -1 if the text is nul-terminated</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="markup_printf_escaped" c:identifier="g_markup_printf_escaped" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Formats arguments according to @format, escaping
|
|
all string and character arguments in the fashion
|
|
of g_markup_escape_text(). This is useful when you
|
|
want to insert literal strings into XML-style markup
|
|
output, without having to worry that the strings
|
|
might themselves contain markup.
|
|
|
|
|[<!-- language="C" -->
|
|
const char *store = "Fortnum & Mason";
|
|
const char *item = "Tea";
|
|
char *output;
|
|
|
|
output = g_markup_printf_escaped ("<purchase>"
|
|
"<store>%s</store>"
|
|
"<item>%s</item>"
|
|
"</purchase>",
|
|
store, item);
|
|
]|</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">newly allocated result from formatting
|
|
operation. Free with g_free().</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">printf() style format string</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">the arguments to insert in the format string</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="markup_vprintf_escaped" c:identifier="g_markup_vprintf_escaped" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Formats the data in @args according to @format, escaping
|
|
all string and character arguments in the fashion
|
|
of g_markup_escape_text(). See g_markup_printf_escaped().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">newly allocated result from formatting
|
|
operation. Free with g_free().</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">printf() style format string</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="args" transfer-ownership="none">
|
|
<doc xml:space="preserve">variable argument list, similar to vprintf()</doc>
|
|
<type name="va_list" c:type="va_list"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="mem_is_system_malloc" c:identifier="g_mem_is_system_malloc" deprecated="1" deprecated-version="2.46">
|
|
<doc xml:space="preserve">Checks whether the allocator used by g_malloc() is the system's
|
|
malloc implementation. If it returns %TRUE memory allocated with
|
|
malloc() can be used interchangeably with memory allocated using g_malloc().
|
|
This function is useful for avoiding an extra copy of allocated memory returned
|
|
by a non-GLib-based API.</doc>
|
|
<doc-deprecated xml:space="preserve">GLib always uses the system malloc, so this function always
|
|
returns %TRUE.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">if %TRUE, malloc() and g_malloc() can be mixed.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="mem_profile" c:identifier="g_mem_profile" deprecated="1" deprecated-version="2.46">
|
|
<doc xml:space="preserve">GLib used to support some tools for memory profiling, but this
|
|
no longer works. There are many other useful tools for memory
|
|
profiling these days which can be used instead.</doc>
|
|
<doc-deprecated xml:space="preserve">Use other memory profiling tools instead</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="mem_set_vtable" c:identifier="g_mem_set_vtable" deprecated="1" deprecated-version="2.46">
|
|
<doc xml:space="preserve">This function used to let you override the memory allocation function.
|
|
However, its use was incompatible with the use of global constructors
|
|
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.</doc>
|
|
<doc-deprecated xml:space="preserve">This function now does nothing. Use other memory
|
|
profiling tools instead</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="vtable" transfer-ownership="none">
|
|
<doc xml:space="preserve">table of memory allocation routines.</doc>
|
|
<type name="MemVTable" c:type="GMemVTable*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="memdup" c:identifier="g_memdup">
|
|
<doc xml:space="preserve">Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
|
|
from @mem. If @mem is %NULL it returns %NULL.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">a pointer to the newly-allocated copy of the memory, or %NULL if @mem
|
|
is %NULL.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mem" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the memory to copy.</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="byte_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes to copy.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="memmove" c:identifier="g_memmove" introspectable="0" deprecated="1" deprecated-version="2.40">
|
|
<doc xml:space="preserve">Copies a block of memory @len bytes long, from @src to @dest.
|
|
The source and destination areas may overlap.</doc>
|
|
<doc-deprecated xml:space="preserve">Just use memmove().</doc-deprecated>
|
|
<parameters>
|
|
<parameter name="dest">
|
|
<doc xml:space="preserve">the destination address to copy the bytes to.</doc>
|
|
</parameter>
|
|
<parameter name="src">
|
|
<doc xml:space="preserve">the source address to copy the bytes from.</doc>
|
|
</parameter>
|
|
<parameter name="len">
|
|
<doc xml:space="preserve">the number of bytes to copy.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<docsection name="memory">
|
|
<doc xml:space="preserve">These functions provide support for allocating and freeing memory.
|
|
|
|
If any call to allocate memory using functions g_new(), g_new0(), g_renew(),
|
|
g_malloc(), g_malloc0(), g_malloc0_n(), g_realloc(), and g_realloc_n()
|
|
fails, the application is terminated. This also means that there is no
|
|
need to check if the call succeeded. On the other hand, the `g_try_...()` family
|
|
of functions returns %NULL on failure that can be used as a check
|
|
for unsuccessful memory allocation. The application is not terminated
|
|
in this case.
|
|
|
|
As all GLib functions and data structures use `g_malloc()` internally, unless
|
|
otherwise specified, any allocation failure will result in the application
|
|
being terminated.
|
|
|
|
It's important to match g_malloc() (and wrappers such as g_new()) with
|
|
g_free(), g_slice_alloc() (and wrappers such as g_slice_new()) with
|
|
g_slice_free(), plain malloc() with free(), and (if you're using C++)
|
|
new with delete and new[] with delete[]. Otherwise bad things can happen,
|
|
since these allocators may use different memory pools (and new/delete call
|
|
constructors and destructors).
|
|
|
|
Since GLib 2.46 g_malloc() is hardcoded to always use the system malloc
|
|
implementation.</doc>
|
|
</docsection>
|
|
<docsection name="memory_slices">
|
|
<doc xml:space="preserve">Memory slices provide a space-efficient and multi-processing scalable
|
|
way to allocate equal-sized pieces of memory, just like the original
|
|
#GMemChunks (from GLib 2.8), while avoiding their excessive
|
|
memory-waste, scalability and performance problems.
|
|
|
|
To achieve these goals, the slice allocator uses a sophisticated,
|
|
layered design that has been inspired by Bonwick's slab allocator
|
|
([Bonwick94](http://citeseer.ist.psu.edu/bonwick94slab.html)
|
|
Jeff Bonwick, The slab allocator: An object-caching kernel
|
|
memory allocator. USENIX 1994, and
|
|
[Bonwick01](http://citeseer.ist.psu.edu/bonwick01magazines.html)
|
|
Bonwick and Jonathan Adams, Magazines and vmem: Extending the
|
|
slab allocator to many cpu's and arbitrary resources. USENIX 2001)
|
|
|
|
It uses posix_memalign() to optimize allocations of many equally-sized
|
|
chunks, and has per-thread free lists (the so-called magazine layer)
|
|
to quickly satisfy allocation requests of already known structure sizes.
|
|
This is accompanied by extra caching logic to keep freed memory around
|
|
for some time before returning it to the system. Memory that is unused
|
|
due to alignment constraints is used for cache colorization (random
|
|
distribution of chunk addresses) to improve CPU cache utilization. The
|
|
caching layer of the slice allocator adapts itself to high lock contention
|
|
to improve scalability.
|
|
|
|
The slice allocator can allocate blocks as small as two pointers, and
|
|
unlike malloc(), it does not reserve extra space per block. For large block
|
|
sizes, g_slice_new() and g_slice_alloc() will automatically delegate to the
|
|
system malloc() implementation. For newly written code it is recommended
|
|
to use the new `g_slice` API instead of g_malloc() and
|
|
friends, as long as objects are not resized during their lifetime and the
|
|
object size used at allocation time is still available when freeing.
|
|
|
|
Here is an example for using the slice allocator:
|
|
|[<!-- language="C" -->
|
|
gchar *mem[10000];
|
|
gint i;
|
|
|
|
// Allocate 10000 blocks.
|
|
for (i = 0; i < 10000; i++)
|
|
{
|
|
mem[i] = g_slice_alloc (50);
|
|
|
|
// Fill in the memory with some junk.
|
|
for (j = 0; j < 50; j++)
|
|
mem[i][j] = i * j;
|
|
}
|
|
|
|
// Now free all of the blocks.
|
|
for (i = 0; i < 10000; i++)
|
|
g_slice_free1 (50, mem[i]);
|
|
]|
|
|
|
|
And here is an example for using the using the slice allocator
|
|
with data structures:
|
|
|[<!-- language="C" -->
|
|
GRealArray *array;
|
|
|
|
// Allocate one block, using the g_slice_new() macro.
|
|
array = g_slice_new (GRealArray);
|
|
|
|
// We can now use array just like a normal pointer to a structure.
|
|
array->data = NULL;
|
|
array->len = 0;
|
|
array->alloc = 0;
|
|
array->zero_terminated = (zero_terminated ? 1 : 0);
|
|
array->clear = (clear ? 1 : 0);
|
|
array->elt_size = elt_size;
|
|
|
|
// We can free the block, so it can be reused.
|
|
g_slice_free (GRealArray, array);
|
|
]|</doc>
|
|
</docsection>
|
|
<docsection name="messages">
|
|
<doc xml:space="preserve">These functions provide support for outputting messages.
|
|
|
|
The g_return family of macros (g_return_if_fail(),
|
|
g_return_val_if_fail(), g_return_if_reached(),
|
|
g_return_val_if_reached()) should only be used for programming
|
|
errors, a typical use case is checking for invalid parameters at
|
|
the beginning of a public function. They should not be used if
|
|
you just mean "if (error) return", they should only be used if
|
|
you mean "if (bug in program) return". The program behavior is
|
|
generally considered undefined after one of these checks fails.
|
|
They are not intended for normal control flow, only to give a
|
|
perhaps-helpful warning before giving up.
|
|
|
|
Structured logging output is supported using g_log_structured(). This differs
|
|
from the traditional g_log() API in that log messages are handled as a
|
|
collection of key–value pairs representing individual pieces of information,
|
|
rather than as a single string containing all the information in an arbitrary
|
|
format.
|
|
|
|
The convenience macros g_info(), g_message(), g_debug(), g_warning() and g_error()
|
|
will use the traditional g_log() API unless you define the symbol
|
|
%G_LOG_USE_STRUCTURED before including `glib.h`. But note that even messages
|
|
logged through the traditional g_log() API are ultimatively passed to
|
|
g_log_structured(), so that all log messages end up in same destination.
|
|
If %G_LOG_USE_STRUCTURED is defined, g_test_expect_message() will become
|
|
ineffective for the wrapper macros g_warning() and friends (see
|
|
[Testing for Messages][testing-for-messages]).
|
|
|
|
The support for structured logging was motivated by the following needs (some
|
|
of which were supported previously; others weren’t):
|
|
* Support for multiple logging levels.
|
|
* Structured log support with the ability to add `MESSAGE_ID`s (see
|
|
g_log_structured()).
|
|
* Moving the responsibility for filtering log messages from the program to
|
|
the log viewer — instead of libraries and programs installing log handlers
|
|
(with g_log_set_handler()) which filter messages before output, all log
|
|
messages are outputted, and the log viewer program (such as `journalctl`)
|
|
must filter them. This is based on the idea that bugs are sometimes hard
|
|
to reproduce, so it is better to log everything possible and then use
|
|
tools to analyse the logs than it is to not be able to reproduce a bug to
|
|
get additional log data. Code which uses logging in performance-critical
|
|
sections should compile out the g_log_structured() calls in
|
|
release builds, and compile them in in debugging builds.
|
|
* A single writer function which handles all log messages in a process, from
|
|
all libraries and program code; rather than multiple log handlers with
|
|
poorly defined interactions between them. This allows a program to easily
|
|
change its logging policy by changing the writer function, for example to
|
|
log to an additional location or to change what logging output fallbacks
|
|
are used. The log writer functions provided by GLib are exposed publicly
|
|
so they can be used from programs’ log writers. This allows log writer
|
|
policy and implementation to be kept separate.
|
|
* If a library wants to add standard information to all of its log messages
|
|
(such as library state) or to redact private data (such as passwords or
|
|
network credentials), it should use a wrapper function around its
|
|
g_log_structured() calls or implement that in the single log writer
|
|
function.
|
|
* If a program wants to pass context data from a g_log_structured() call to
|
|
its log writer function so that, for example, it can use the correct
|
|
server connection to submit logs to, that user data can be passed as a
|
|
zero-length #GLogField to g_log_structured_array().
|
|
* Color output needed to be supported on the terminal, to make reading
|
|
through logs easier.
|
|
|
|
## Using Structured Logging ## {#using-structured-logging}
|
|
|
|
To use structured logging (rather than the old-style logging), either use
|
|
the g_log_structured() and g_log_structured_array() functions; or define
|
|
`G_LOG_USE_STRUCTURED` before including any GLib header, and use the
|
|
g_message(), g_debug(), g_error() (etc.) macros.
|
|
|
|
You do not need to define `G_LOG_USE_STRUCTURED` to use g_log_structured(),
|
|
but it is a good idea to avoid confusion.
|
|
|
|
## Log Domains ## {#log-domains}
|
|
|
|
Log domains may be used to broadly split up the origins of log messages.
|
|
Typically, there are one or a few log domains per application or library.
|
|
%G_LOG_DOMAIN should be used to define the default log domain for the current
|
|
compilation unit — it is typically defined at the top of a source file, or in
|
|
the preprocessor flags for a group of source files.
|
|
|
|
Log domains must be unique, and it is recommended that they are the
|
|
application or library name, optionally followed by a hyphen and a sub-domain
|
|
name. For example, `bloatpad` or `bloatpad-io`.
|
|
|
|
## Debug Message Output ## {#debug-message-output}
|
|
|
|
The default log functions (g_log_default_handler() for the old-style API and
|
|
g_log_writer_default() for the structured API) both drop debug and
|
|
informational messages by default, unless the log domains of those messages
|
|
are listed in the `G_MESSAGES_DEBUG` environment variable (or it is set to
|
|
`all`).
|
|
|
|
It is recommended that custom log writer functions re-use the
|
|
`G_MESSAGES_DEBUG` environment variable, rather than inventing a custom one,
|
|
so that developers can re-use the same debugging techniques and tools across
|
|
projects.
|
|
|
|
## Testing for Messages ## {#testing-for-messages}
|
|
|
|
With the old g_log() API, g_test_expect_message() and
|
|
g_test_assert_expected_messages() could be used in simple cases to check
|
|
whether some code under test had emitted a given log message. These
|
|
functions have been deprecated with the structured logging API, for several
|
|
reasons:
|
|
* They relied on an internal queue which was too inflexible for many use
|
|
cases, where messages might be emitted in several orders, some
|
|
messages might not be emitted deterministically, or messages might be
|
|
emitted by unrelated log domains.
|
|
* They do not support structured log fields.
|
|
* Examining the log output of code is a bad approach to testing it, and
|
|
while it might be necessary for legacy code which uses g_log(), it should
|
|
be avoided for new code using g_log_structured().
|
|
|
|
They will continue to work as before if g_log() is in use (and
|
|
%G_LOG_USE_STRUCTURED is not defined). They will do nothing if used with the
|
|
structured logging API.
|
|
|
|
Examining the log output of code is discouraged: libraries should not emit to
|
|
`stderr` during defined behaviour, and hence this should not be tested. If
|
|
the log emissions of a library during undefined behaviour need to be tested,
|
|
they should be limited to asserting that the library aborts and prints a
|
|
suitable error message before aborting. This should be done with
|
|
g_test_trap_assert_stderr().
|
|
|
|
If it is really necessary to test the structured log messages emitted by a
|
|
particular piece of code – and the code cannot be restructured to be more
|
|
suitable to more conventional unit testing – you should write a custom log
|
|
writer function (see g_log_set_writer_func()) which appends all log messages
|
|
to a queue. When you want to check the log messages, examine and clear the
|
|
queue, ignoring irrelevant log messages (for example, from log domains other
|
|
than the one under test).</doc>
|
|
</docsection>
|
|
<docsection name="misc_utils">
|
|
<doc xml:space="preserve">These are portable utility functions.</doc>
|
|
</docsection>
|
|
<function name="mkdir_with_parents" c:identifier="g_mkdir_with_parents" version="2.8">
|
|
<doc xml:space="preserve">Create a directory if it doesn't already exist. Create intermediate
|
|
parent directories as needed, too.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">0 if the directory already exists, or was successfully
|
|
created. Returns -1 if an error occurred, with errno set.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="pathname" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pathname in the GLib file name encoding</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="mode" transfer-ownership="none">
|
|
<doc xml:space="preserve">permissions to use for newly created directories</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="mkdtemp" c:identifier="g_mkdtemp" version="2.30" introspectable="0">
|
|
<doc xml:space="preserve">Creates a temporary directory. See the mkdtemp() documentation
|
|
on most UNIX-like systems.
|
|
|
|
The parameter is a string that should follow the rules for
|
|
mkdtemp() templates, i.e. contain the string "XXXXXX".
|
|
g_mkdtemp() is slightly more flexible than mkdtemp() in that the
|
|
sequence does not have to occur at the very end of the template.
|
|
The X string will be modified to form the name of a directory that
|
|
didn't exist.
|
|
The string should be in the GLib file name encoding. Most importantly,
|
|
on Windows it should be in UTF-8.
|
|
|
|
If you are going to be creating a temporary directory inside the
|
|
directory returned by g_get_tmp_dir(), you might want to use
|
|
g_dir_make_tmp() instead.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">A pointer to @tmpl, which has been
|
|
modified to hold the directory name. In case of errors, %NULL is
|
|
returned and %errno will be set.</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="tmpl" transfer-ownership="none">
|
|
<doc xml:space="preserve">template directory name</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="mkdtemp_full" c:identifier="g_mkdtemp_full" version="2.30" introspectable="0">
|
|
<doc xml:space="preserve">Creates a temporary directory. See the mkdtemp() documentation
|
|
on most UNIX-like systems.
|
|
|
|
The parameter is a string that should follow the rules for
|
|
mkdtemp() templates, i.e. contain the string "XXXXXX".
|
|
g_mkdtemp_full() is slightly more flexible than mkdtemp() in that the
|
|
sequence does not have to occur at the very end of the template
|
|
and you can pass a @mode. The X string will be modified to form
|
|
the name of a directory that didn't exist. The string should be
|
|
in the GLib file name encoding. Most importantly, on Windows it
|
|
should be in UTF-8.
|
|
|
|
If you are going to be creating a temporary directory inside the
|
|
directory returned by g_get_tmp_dir(), you might want to use
|
|
g_dir_make_tmp() instead.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">A pointer to @tmpl, which has been
|
|
modified to hold the directory name. In case of errors, %NULL is
|
|
returned, and %errno will be set.</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="tmpl" transfer-ownership="none">
|
|
<doc xml:space="preserve">template directory name</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="mode" transfer-ownership="none">
|
|
<doc xml:space="preserve">permissions to create the temporary directory with</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="mkstemp" c:identifier="g_mkstemp" introspectable="0">
|
|
<doc xml:space="preserve">Opens a temporary file. See the mkstemp() documentation
|
|
on most UNIX-like systems.
|
|
|
|
The parameter is a string that should follow the rules for
|
|
mkstemp() templates, i.e. contain the string "XXXXXX".
|
|
g_mkstemp() is slightly more flexible than mkstemp() in that the
|
|
sequence does not have to occur at the very end of the template.
|
|
The X string will be modified to form the name of a file that
|
|
didn't exist. The string should be in the GLib file name encoding.
|
|
Most importantly, on Windows it should be in UTF-8.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">A file handle (as from open()) to the file
|
|
opened for reading and writing. The file is opened in binary
|
|
mode on platforms where there is a difference. The file handle
|
|
should be closed with close(). In case of errors, -1 is
|
|
returned and %errno will be set.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="tmpl" transfer-ownership="none">
|
|
<doc xml:space="preserve">template filename</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="mkstemp_full" c:identifier="g_mkstemp_full" version="2.22" introspectable="0">
|
|
<doc xml:space="preserve">Opens a temporary file. See the mkstemp() documentation
|
|
on most UNIX-like systems.
|
|
|
|
The parameter is a string that should follow the rules for
|
|
mkstemp() templates, i.e. contain the string "XXXXXX".
|
|
g_mkstemp_full() is slightly more flexible than mkstemp()
|
|
in that the sequence does not have to occur at the very end of the
|
|
template and you can pass a @mode and additional @flags. The X
|
|
string will be modified to form the name of a file that didn't exist.
|
|
The string should be in the GLib file name encoding. Most importantly,
|
|
on Windows it should be in UTF-8.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">A file handle (as from open()) to the file
|
|
opened for reading and writing. The file handle should be
|
|
closed with close(). In case of errors, -1 is returned
|
|
and %errno will be set.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="tmpl" transfer-ownership="none">
|
|
<doc xml:space="preserve">template filename</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags to pass to an open() call in addition to O_EXCL
|
|
and O_CREAT, which are passed automatically</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="mode" transfer-ownership="none">
|
|
<doc xml:space="preserve">permissions to create the temporary file with</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="new" c:identifier="g_new" introspectable="0">
|
|
<doc xml:space="preserve">Allocates @n_structs elements of type @struct_type.
|
|
The returned pointer is cast to a pointer to the given type.
|
|
If @n_structs is 0 it returns %NULL.
|
|
Care is taken to avoid overflow when calculating the size of the allocated block.
|
|
|
|
Since the returned pointer is already casted to the right type,
|
|
it is normally unnecessary to cast it explicitly, and doing
|
|
so might hide memory allocation errors.</doc>
|
|
<parameters>
|
|
<parameter name="struct_type">
|
|
<doc xml:space="preserve">the type of the elements to allocate</doc>
|
|
</parameter>
|
|
<parameter name="n_structs">
|
|
<doc xml:space="preserve">the number of elements to allocate</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="new0" c:identifier="g_new0" introspectable="0">
|
|
<doc xml:space="preserve">Allocates @n_structs elements of type @struct_type, initialized to 0's.
|
|
The returned pointer is cast to a pointer to the given type.
|
|
If @n_structs is 0 it returns %NULL.
|
|
Care is taken to avoid overflow when calculating the size of the allocated block.
|
|
|
|
Since the returned pointer is already casted to the right type,
|
|
it is normally unnecessary to cast it explicitly, and doing
|
|
so might hide memory allocation errors.</doc>
|
|
<parameters>
|
|
<parameter name="struct_type">
|
|
<doc xml:space="preserve">the type of the elements to allocate.</doc>
|
|
</parameter>
|
|
<parameter name="n_structs">
|
|
<doc xml:space="preserve">the number of elements to allocate.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="newa" c:identifier="g_newa" introspectable="0">
|
|
<doc xml:space="preserve">Wraps g_alloca() in a more typesafe manner.</doc>
|
|
<parameters>
|
|
<parameter name="struct_type">
|
|
<doc xml:space="preserve">Type of memory chunks to be allocated</doc>
|
|
</parameter>
|
|
<parameter name="n_structs">
|
|
<doc xml:space="preserve">Number of chunks to be allocated</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="node_append" c:identifier="g_node_append" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a #GNode as the last child of the given parent.</doc>
|
|
<parameters>
|
|
<parameter name="parent">
|
|
<doc xml:space="preserve">the #GNode to place the new #GNode under</doc>
|
|
</parameter>
|
|
<parameter name="node">
|
|
<doc xml:space="preserve">the #GNode to insert</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="node_append_data" c:identifier="g_node_append_data" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a new #GNode as the last child of the given parent.</doc>
|
|
<parameters>
|
|
<parameter name="parent">
|
|
<doc xml:space="preserve">the #GNode to place the new #GNode under</doc>
|
|
</parameter>
|
|
<parameter name="data">
|
|
<doc xml:space="preserve">the data for the new #GNode</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="node_first_child" c:identifier="g_node_first_child" introspectable="0">
|
|
<doc xml:space="preserve">Gets the first child of a #GNode.</doc>
|
|
<parameters>
|
|
<parameter name="node">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="node_insert_data" c:identifier="g_node_insert_data" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a new #GNode at the given position.</doc>
|
|
<parameters>
|
|
<parameter name="parent">
|
|
<doc xml:space="preserve">the #GNode to place the new #GNode under</doc>
|
|
</parameter>
|
|
<parameter name="position">
|
|
<doc xml:space="preserve">the position to place the new #GNode at. If position is -1,
|
|
the new #GNode is inserted as the last child of @parent</doc>
|
|
</parameter>
|
|
<parameter name="data">
|
|
<doc xml:space="preserve">the data for the new #GNode</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="node_insert_data_after" c:identifier="g_node_insert_data_after" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a new #GNode after the given sibling.</doc>
|
|
<parameters>
|
|
<parameter name="parent">
|
|
<doc xml:space="preserve">the #GNode to place the new #GNode under</doc>
|
|
</parameter>
|
|
<parameter name="sibling">
|
|
<doc xml:space="preserve">the sibling #GNode to place the new #GNode after</doc>
|
|
</parameter>
|
|
<parameter name="data">
|
|
<doc xml:space="preserve">the data for the new #GNode</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="node_insert_data_before" c:identifier="g_node_insert_data_before" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a new #GNode before the given sibling.</doc>
|
|
<parameters>
|
|
<parameter name="parent">
|
|
<doc xml:space="preserve">the #GNode to place the new #GNode under</doc>
|
|
</parameter>
|
|
<parameter name="sibling">
|
|
<doc xml:space="preserve">the sibling #GNode to place the new #GNode before</doc>
|
|
</parameter>
|
|
<parameter name="data">
|
|
<doc xml:space="preserve">the data for the new #GNode</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="node_next_sibling" c:identifier="g_node_next_sibling" introspectable="0">
|
|
<doc xml:space="preserve">Gets the next sibling of a #GNode.</doc>
|
|
<parameters>
|
|
<parameter name="node">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="node_prepend_data" c:identifier="g_node_prepend_data" introspectable="0">
|
|
<doc xml:space="preserve">Inserts a new #GNode as the first child of the given parent.</doc>
|
|
<parameters>
|
|
<parameter name="parent">
|
|
<doc xml:space="preserve">the #GNode to place the new #GNode under</doc>
|
|
</parameter>
|
|
<parameter name="data">
|
|
<doc xml:space="preserve">the data for the new #GNode</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="node_prev_sibling" c:identifier="g_node_prev_sibling" introspectable="0">
|
|
<doc xml:space="preserve">Gets the previous sibling of a #GNode.</doc>
|
|
<parameters>
|
|
<parameter name="node">
|
|
<doc xml:space="preserve">a #GNode</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="ntohl" c:identifier="g_ntohl" introspectable="0">
|
|
<doc xml:space="preserve">Converts a 32-bit integer value from network to host byte order.</doc>
|
|
<parameters>
|
|
<parameter name="val">
|
|
<doc xml:space="preserve">a 32-bit integer value in network byte order</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="ntohs" c:identifier="g_ntohs" introspectable="0">
|
|
<doc xml:space="preserve">Converts a 16-bit integer value from network to host byte order.</doc>
|
|
<parameters>
|
|
<parameter name="val">
|
|
<doc xml:space="preserve">a 16-bit integer value in network byte order</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="nullify_pointer" c:identifier="g_nullify_pointer">
|
|
<doc xml:space="preserve">Set the pointer at the specified location to %NULL.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="nullify_location" transfer-ownership="none">
|
|
<doc xml:space="preserve">the memory address of the pointer.</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="number_parser_error_quark" c:identifier="g_number_parser_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<docsection name="numerical">
|
|
<doc xml:space="preserve">GLib offers mathematical constants such as #G_PI for the value of pi;
|
|
many platforms have these in the C library, but some don't, the GLib
|
|
versions always exist.
|
|
|
|
The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the
|
|
sign, mantissa and exponent of IEEE floats and doubles. These unions are
|
|
defined as appropriate for a given platform. IEEE floats and doubles are
|
|
supported (used for storage) by at least Intel, PPC and Sparc. See
|
|
[IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float)
|
|
for more information about IEEE number formats.</doc>
|
|
</docsection>
|
|
<function name="on_error_query" c:identifier="g_on_error_query">
|
|
<doc xml:space="preserve">Prompts the user with
|
|
`[E]xit, [H]alt, show [S]tack trace or [P]roceed`.
|
|
This function is intended to be used for debugging use only.
|
|
The following example shows how it can be used together with
|
|
the g_log() functions.
|
|
|
|
|[<!-- language="C" -->
|
|
#include <glib.h>
|
|
|
|
static void
|
|
log_handler (const gchar *log_domain,
|
|
GLogLevelFlags log_level,
|
|
const gchar *message,
|
|
gpointer user_data)
|
|
{
|
|
g_log_default_handler (log_domain, log_level, message, user_data);
|
|
|
|
g_on_error_query (MY_PROGRAM_NAME);
|
|
}
|
|
|
|
int
|
|
main (int argc, char *argv[])
|
|
{
|
|
g_log_set_handler (MY_LOG_DOMAIN,
|
|
G_LOG_LEVEL_WARNING |
|
|
G_LOG_LEVEL_ERROR |
|
|
G_LOG_LEVEL_CRITICAL,
|
|
log_handler,
|
|
NULL);
|
|
...
|
|
]|
|
|
|
|
If "[E]xit" is selected, the application terminates with a call
|
|
to _exit(0).
|
|
|
|
If "[S]tack" trace is selected, g_on_error_stack_trace() is called.
|
|
This invokes gdb, which attaches to the current process and shows
|
|
a stack trace. The prompt is then shown again.
|
|
|
|
If "[P]roceed" is selected, the function returns.
|
|
|
|
This function may cause different actions on non-UNIX platforms.
|
|
|
|
On Windows consider using the `G_DEBUGGER` environment
|
|
variable (see [Running GLib Applications](glib-running.html)) and
|
|
calling g_on_error_stack_trace() instead.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="prg_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">the program name, needed by gdb for the "[S]tack trace"
|
|
option. If @prg_name is %NULL, g_get_prgname() is called to get
|
|
the program name (which will work correctly if gdk_init() or
|
|
gtk_init() has been called)</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="on_error_stack_trace" c:identifier="g_on_error_stack_trace">
|
|
<doc xml:space="preserve">Invokes gdb, which attaches to the current process and shows a
|
|
stack trace. Called by g_on_error_query() when the "[S]tack trace"
|
|
option is selected. You can get the current process's program name
|
|
with g_get_prgname(), assuming that you have called gtk_init() or
|
|
gdk_init().
|
|
|
|
This function may cause different actions on non-UNIX platforms.
|
|
|
|
When running on Windows, this function is *not* called by
|
|
g_on_error_query(). If called directly, it will raise an
|
|
exception, which will crash the program. If the `G_DEBUGGER` environment
|
|
variable is set, a debugger will be invoked to attach and
|
|
handle that exception (see [Running GLib Applications](glib-running.html)).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="prg_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">the program name, needed by gdb for the "[S]tack trace"
|
|
option</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="once" c:identifier="g_once" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">The first call to this routine by a process with a given #GOnce
|
|
struct calls @func with the given argument. Thereafter, subsequent
|
|
calls to g_once() with the same #GOnce struct do not call @func
|
|
again, but return the stored result of the first call. On return
|
|
from g_once(), the status of @once will be %G_ONCE_STATUS_READY.
|
|
|
|
For example, a mutex or a thread-specific data key must be created
|
|
exactly once. In a threaded environment, calling g_once() ensures
|
|
that the initialization is serialized across multiple threads.
|
|
|
|
Calling g_once() recursively on the same #GOnce struct in
|
|
@func will lead to a deadlock.
|
|
|
|
|[<!-- language="C" -->
|
|
gpointer
|
|
get_debug_flags (void)
|
|
{
|
|
static GOnce my_once = G_ONCE_INIT;
|
|
|
|
g_once (&my_once, parse_debug_flags, NULL);
|
|
|
|
return my_once.retval;
|
|
}
|
|
]|</doc>
|
|
<parameters>
|
|
<parameter name="once">
|
|
<doc xml:space="preserve">a #GOnce structure</doc>
|
|
</parameter>
|
|
<parameter name="func">
|
|
<doc xml:space="preserve">the #GThreadFunc function associated to @once. This function
|
|
is called only once, regardless of the number of times it and
|
|
its associated #GOnce struct are passed to g_once().</doc>
|
|
</parameter>
|
|
<parameter name="arg">
|
|
<doc xml:space="preserve">data to be passed to @func</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="once_init_enter" c:identifier="g_once_init_enter" moved-to="Once.init_enter" version="2.14">
|
|
<doc xml:space="preserve">Function to be called when starting a critical initialization
|
|
section. The argument @location must point to a static
|
|
0-initialized variable that will be set to a value other than 0 at
|
|
the end of the initialization section. In combination with
|
|
g_once_init_leave() and the unique address @value_location, it can
|
|
be ensured that an initialization section will be executed only once
|
|
during a program's life time, and that concurrent threads are
|
|
blocked until initialization completed. To be used in constructs
|
|
like this:
|
|
|
|
|[<!-- language="C" -->
|
|
static gsize initialization_value = 0;
|
|
|
|
if (g_once_init_enter (&initialization_value))
|
|
{
|
|
gsize setup_value = 42; // initialization code here
|
|
|
|
g_once_init_leave (&initialization_value, setup_value);
|
|
}
|
|
|
|
// use initialization_value here
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the initialization section should be entered,
|
|
%FALSE and blocks otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="location" transfer-ownership="none">
|
|
<doc xml:space="preserve">location of a static initializable variable
|
|
containing 0</doc>
|
|
<type name="gpointer" c:type="void*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="once_init_leave" c:identifier="g_once_init_leave" moved-to="Once.init_leave" version="2.14">
|
|
<doc xml:space="preserve">Counterpart to g_once_init_enter(). Expects a location of a static
|
|
0-initialized initialization variable, and an initialization value
|
|
other than 0. Sets the variable to the initialization value, and
|
|
releases concurrent threads blocking in g_once_init_enter() on this
|
|
initialization variable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="location" transfer-ownership="none">
|
|
<doc xml:space="preserve">location of a static initializable variable
|
|
containing 0</doc>
|
|
<type name="gpointer" c:type="void*"/>
|
|
</parameter>
|
|
<parameter name="result" transfer-ownership="none">
|
|
<doc xml:space="preserve">new non-0 value for *@value_location</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="option">
|
|
<doc xml:space="preserve">The GOption commandline parser is intended to be a simpler replacement
|
|
for the popt library. It supports short and long commandline options,
|
|
as shown in the following example:
|
|
|
|
`testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2`
|
|
|
|
The example demonstrates a number of features of the GOption
|
|
commandline parser:
|
|
|
|
- Options can be single letters, prefixed by a single dash.
|
|
|
|
- Multiple short options can be grouped behind a single dash.
|
|
|
|
- Long options are prefixed by two consecutive dashes.
|
|
|
|
- Options can have an extra argument, which can be a number, a string or
|
|
a filename. For long options, the extra argument can be appended with
|
|
an equals sign after the option name, which is useful if the extra
|
|
argument starts with a dash, which would otherwise cause it to be
|
|
interpreted as another option.
|
|
|
|
- Non-option arguments are returned to the application as rest arguments.
|
|
|
|
- An argument consisting solely of two dashes turns off further parsing,
|
|
any remaining arguments (even those starting with a dash) are returned
|
|
to the application as rest arguments.
|
|
|
|
Another important feature of GOption is that it can automatically
|
|
generate nicely formatted help output. Unless it is explicitly turned
|
|
off with g_option_context_set_help_enabled(), GOption will recognize
|
|
the `--help`, `-?`, `--help-all` and `--help-groupname` options
|
|
(where `groupname` is the name of a #GOptionGroup) and write a text
|
|
similar to the one shown in the following example to stdout.
|
|
|
|
|[
|
|
Usage:
|
|
testtreemodel [OPTION...] - test tree model performance
|
|
|
|
Help Options:
|
|
-h, --help Show help options
|
|
--help-all Show all help options
|
|
--help-gtk Show GTK+ Options
|
|
|
|
Application Options:
|
|
-r, --repeats=N Average over N repetitions
|
|
-m, --max-size=M Test up to 2^M items
|
|
--display=DISPLAY X display to use
|
|
-v, --verbose Be verbose
|
|
-b, --beep Beep when done
|
|
--rand Randomize the data
|
|
]|
|
|
|
|
GOption groups options in #GOptionGroups, which makes it easy to
|
|
incorporate options from multiple sources. The intended use for this is
|
|
to let applications collect option groups from the libraries it uses,
|
|
add them to their #GOptionContext, and parse all options by a single call
|
|
to g_option_context_parse(). See gtk_get_option_group() for an example.
|
|
|
|
If an option is declared to be of type string or filename, GOption takes
|
|
care of converting it to the right encoding; strings are returned in
|
|
UTF-8, filenames are returned in the GLib filename encoding. Note that
|
|
this only works if setlocale() has been called before
|
|
g_option_context_parse().
|
|
|
|
Here is a complete example of setting up GOption to parse the example
|
|
commandline above and produce the example help output.
|
|
|[<!-- language="C" -->
|
|
static gint repeats = 2;
|
|
static gint max_size = 8;
|
|
static gboolean verbose = FALSE;
|
|
static gboolean beep = FALSE;
|
|
static gboolean randomize = FALSE;
|
|
|
|
static GOptionEntry entries[] =
|
|
{
|
|
{ "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Average over N repetitions", "N" },
|
|
{ "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" },
|
|
{ "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL },
|
|
{ "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL },
|
|
{ "rand", 0, 0, G_OPTION_ARG_NONE, &randomize, "Randomize the data", NULL },
|
|
{ NULL }
|
|
};
|
|
|
|
int
|
|
main (int argc, char *argv[])
|
|
{
|
|
GError *error = NULL;
|
|
GOptionContext *context;
|
|
|
|
context = g_option_context_new ("- test tree model performance");
|
|
g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);
|
|
g_option_context_add_group (context, gtk_get_option_group (TRUE));
|
|
if (!g_option_context_parse (context, &argc, &argv, &error))
|
|
{
|
|
g_print ("option parsing failed: %s\n", error->message);
|
|
exit (1);
|
|
}
|
|
|
|
...
|
|
|
|
}
|
|
]|
|
|
|
|
On UNIX systems, the argv that is passed to main() has no particular
|
|
encoding, even to the extent that different parts of it may have
|
|
different encodings. In general, normal arguments and flags will be
|
|
in the current locale and filenames should be considered to be opaque
|
|
byte strings. Proper use of %G_OPTION_ARG_FILENAME vs
|
|
%G_OPTION_ARG_STRING is therefore important.
|
|
|
|
Note that on Windows, filenames do have an encoding, but using
|
|
#GOptionContext with the argv as passed to main() will result in a
|
|
program that can only accept commandline arguments with characters
|
|
from the system codepage. This can cause problems when attempting to
|
|
deal with filenames containing Unicode characters that fall outside
|
|
of the codepage.
|
|
|
|
A solution to this is to use g_win32_get_command_line() and
|
|
g_option_context_parse_strv() which will properly handle full Unicode
|
|
filenames. If you are using #GApplication, this is done
|
|
automatically for you.
|
|
|
|
The following example shows how you can use #GOptionContext directly
|
|
in order to correctly deal with Unicode filenames on Windows:
|
|
|
|
|[<!-- language="C" -->
|
|
int
|
|
main (int argc, char **argv)
|
|
{
|
|
GError *error = NULL;
|
|
GOptionContext *context;
|
|
gchar **args;
|
|
|
|
#ifdef G_OS_WIN32
|
|
args = g_win32_get_command_line ();
|
|
#else
|
|
args = g_strdupv (argv);
|
|
#endif
|
|
|
|
// set up context
|
|
|
|
if (!g_option_context_parse_strv (context, &args, &error))
|
|
{
|
|
// error happened
|
|
}
|
|
|
|
...
|
|
|
|
g_strfreev (args);
|
|
|
|
...
|
|
}
|
|
]|</doc>
|
|
</docsection>
|
|
<function name="option_error_quark" c:identifier="g_option_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="parse_debug_string" c:identifier="g_parse_debug_string">
|
|
<doc xml:space="preserve">Parses a string containing debugging options
|
|
into a %guint containing bit flags. This is used
|
|
within GDK and GTK+ to parse the debug options passed on the
|
|
command line or through environment variables.
|
|
|
|
If @string is equal to "all", all flags are set. Any flags
|
|
specified along with "all" in @string are inverted; thus,
|
|
"all,foo,bar" or "foo,bar,all" sets all flags except those
|
|
corresponding to "foo" and "bar".
|
|
|
|
If @string is equal to "help", all the available keys in @keys
|
|
are printed out to standard error.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the combined set of bit flags.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a list of debug options separated by colons, spaces, or
|
|
commas, or %NULL.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="keys" transfer-ownership="none">
|
|
<doc xml:space="preserve">pointer to an array of #GDebugKey which associate
|
|
strings with bit flags.</doc>
|
|
<array length="2" zero-terminated="0" c:type="const GDebugKey*">
|
|
<type name="DebugKey" c:type="GDebugKey"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="nkeys" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of #GDebugKeys in the array.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="path_get_basename" c:identifier="g_path_get_basename">
|
|
<doc xml:space="preserve">Gets the last component of the filename.
|
|
|
|
If @file_name ends with a directory separator it gets the component
|
|
before the last slash. If @file_name consists only of directory
|
|
separators (and on Windows, possibly a drive letter), a single
|
|
separator is returned. If @file_name is empty, it gets ".".</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string containing the last
|
|
component of the filename</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="file_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">the name of the file</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="path_get_dirname" c:identifier="g_path_get_dirname">
|
|
<doc xml:space="preserve">Gets the directory components of a file name. For example, the directory
|
|
component of `/usr/bin/test` is `/usr/bin`. The directory component of `/`
|
|
is `/`.
|
|
|
|
If the file name has no directory components "." is returned.
|
|
The returned string should be freed when no longer needed.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the directory components of the file</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="file_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">the name of the file</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="path_is_absolute" c:identifier="g_path_is_absolute">
|
|
<doc xml:space="preserve">Returns %TRUE if the given @file_name is an absolute file name.
|
|
Note that this is a somewhat vague concept on Windows.
|
|
|
|
On POSIX systems, an absolute file name is well-defined. It always
|
|
starts from the single root directory. For example "/usr/local".
|
|
|
|
On Windows, the concepts of current drive and drive-specific
|
|
current directory introduce vagueness. This function interprets as
|
|
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
|
|
backslashes are accepted.
|
|
|
|
Note that a file name relative to the current drive root does not
|
|
truly specify a file uniquely over time and across processes, as
|
|
the current drive is a per-process value and can be changed.
|
|
|
|
File names relative the current directory on some specific drive,
|
|
such as "D:foo/bar", are not interpreted as absolute by this
|
|
function, but they obviously are not relative to the normal current
|
|
directory as returned by getcwd() or g_get_current_dir()
|
|
either. Such paths should be avoided, or need to be handled using
|
|
Windows-specific code.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @file_name is absolute</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="file_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a file name</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="path_skip_root" c:identifier="g_path_skip_root">
|
|
<doc xml:space="preserve">Returns a pointer into @file_name after the root component,
|
|
i.e. after the "/" in UNIX or "C:\" under Windows. If @file_name
|
|
is not an absolute path it returns %NULL.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">a pointer into @file_name after the
|
|
root component</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="file_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a file name</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="pattern_match" c:identifier="g_pattern_match">
|
|
<doc xml:space="preserve">Matches a string against a compiled pattern. Passing the correct
|
|
length of the string given is mandatory. The reversed string can be
|
|
omitted by passing %NULL, this is more efficient if the reversed
|
|
version of the string to be matched is not at hand, as
|
|
g_pattern_match() will only construct it if the compiled pattern
|
|
requires reverse matches.
|
|
|
|
Note that, if the user code will (possibly) match a string against a
|
|
multitude of patterns containing wildcards, chances are high that
|
|
some patterns will require a reversed string. In this case, it's
|
|
more efficient to provide the reversed string to avoid multiple
|
|
constructions thereof in the various calls to g_pattern_match().
|
|
|
|
Note also that the reverse of a UTF-8 encoded string can in general
|
|
not be obtained by g_strreverse(). This works only if the string
|
|
does not contain any multibyte characters. GLib offers the
|
|
g_utf8_strreverse() function to reverse UTF-8 encoded strings.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @string matches @pspec</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="pspec" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPatternSpec</doc>
|
|
<type name="PatternSpec" c:type="GPatternSpec*"/>
|
|
</parameter>
|
|
<parameter name="string_length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @string (in bytes, i.e. strlen(),
|
|
not g_utf8_strlen())</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the UTF-8 encoded string to match</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="string_reversed" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the reverse of @string or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="pattern_match_simple" c:identifier="g_pattern_match_simple">
|
|
<doc xml:space="preserve">Matches a string against a pattern given as a string. If this
|
|
function is to be called in a loop, it's more efficient to compile
|
|
the pattern once with g_pattern_spec_new() and call
|
|
g_pattern_match_string() repeatedly.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @string matches @pspec</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="pattern" transfer-ownership="none">
|
|
<doc xml:space="preserve">the UTF-8 encoded pattern</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the UTF-8 encoded string to match</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="pattern_match_string" c:identifier="g_pattern_match_string">
|
|
<doc xml:space="preserve">Matches a string against a compiled pattern. If the string is to be
|
|
matched against more than one pattern, consider using
|
|
g_pattern_match() instead while supplying the reversed string.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @string matches @pspec</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="pspec" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GPatternSpec</doc>
|
|
<type name="PatternSpec" c:type="GPatternSpec*"/>
|
|
</parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the UTF-8 encoded string to match</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="patterns">
|
|
<doc xml:space="preserve">The g_pattern_match* functions match a string
|
|
against a pattern containing '*' and '?' wildcards with similar
|
|
semantics as the standard glob() function: '*' matches an arbitrary,
|
|
possibly empty, string, '?' matches an arbitrary character.
|
|
|
|
Note that in contrast to glob(), the '/' character can be matched by
|
|
the wildcards, there are no '[...]' character ranges and '*' and '?'
|
|
can not be escaped to include them literally in a pattern.
|
|
|
|
When multiple strings must be matched against the same pattern, it
|
|
is better to compile the pattern to a #GPatternSpec using
|
|
g_pattern_spec_new() and use g_pattern_match_string() instead of
|
|
g_pattern_match_simple(). This avoids the overhead of repeated
|
|
pattern compilation.</doc>
|
|
</docsection>
|
|
<function name="pointer_bit_lock" c:identifier="g_pointer_bit_lock" version="2.30">
|
|
<doc xml:space="preserve">This is equivalent to g_bit_lock, but working on pointers (or other
|
|
pointer-sized values).
|
|
|
|
For portability reasons, you may only lock on the bottom 32 bits of
|
|
the pointer.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="address" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gpointer-sized value</doc>
|
|
<type name="gpointer" c:type="void*"/>
|
|
</parameter>
|
|
<parameter name="lock_bit" transfer-ownership="none">
|
|
<doc xml:space="preserve">a bit value between 0 and 31</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="pointer_bit_trylock" c:identifier="g_pointer_bit_trylock" version="2.30">
|
|
<doc xml:space="preserve">This is equivalent to g_bit_trylock, but working on pointers (or
|
|
other pointer-sized values).
|
|
|
|
For portability reasons, you may only lock on the bottom 32 bits of
|
|
the pointer.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the lock was acquired</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="address" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gpointer-sized value</doc>
|
|
<type name="gpointer" c:type="void*"/>
|
|
</parameter>
|
|
<parameter name="lock_bit" transfer-ownership="none">
|
|
<doc xml:space="preserve">a bit value between 0 and 31</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="pointer_bit_unlock" c:identifier="g_pointer_bit_unlock" version="2.30">
|
|
<doc xml:space="preserve">This is equivalent to g_bit_unlock, but working on pointers (or other
|
|
pointer-sized values).
|
|
|
|
For portability reasons, you may only lock on the bottom 32 bits of
|
|
the pointer.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="address" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a #gpointer-sized value</doc>
|
|
<type name="gpointer" c:type="void*"/>
|
|
</parameter>
|
|
<parameter name="lock_bit" transfer-ownership="none">
|
|
<doc xml:space="preserve">a bit value between 0 and 31</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="poll" c:identifier="g_poll" version="2.20">
|
|
<doc xml:space="preserve">Polls @fds, as with the poll() system call, but portably. (On
|
|
systems that don't have poll(), it is emulated using select().)
|
|
This is used internally by #GMainContext, but it can be called
|
|
directly if you need to block until a file descriptor is ready, but
|
|
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
|
|
occurred.
|
|
|
|
On POSIX systems, the file descriptors in @fds can be any sort of
|
|
file descriptor, but the situation is much more complicated on
|
|
Windows. If you need to use g_poll() in code that has to run on
|
|
Windows, the easiest solution is to construct all of your
|
|
#GPollFDs with g_io_channel_win32_make_pollfd().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">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.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="fds" transfer-ownership="none">
|
|
<doc xml:space="preserve">file descriptors to poll</doc>
|
|
<type name="PollFD" c:type="GPollFD*"/>
|
|
</parameter>
|
|
<parameter name="nfds" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of file descriptors in @fds</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="timeout" transfer-ownership="none">
|
|
<doc xml:space="preserve">amount of time to wait, in milliseconds, or -1 to wait forever</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="prefix_error" c:identifier="g_prefix_error" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Formats a string according to @format and prefix it to an existing
|
|
error message. If @err is %NULL (ie: no error variable) then do
|
|
nothing.
|
|
|
|
If *@err is %NULL (ie: an error variable is present but there is no
|
|
error condition) then also do nothing.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="err" direction="inout" caller-allocates="0" transfer-ownership="full" nullable="1" allow-none="1" optional="1">
|
|
<doc xml:space="preserve">a return location for a #GError</doc>
|
|
<type name="Error" c:type="GError**"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">printf()-style format string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">arguments to @format</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="print" c:identifier="g_print" introspectable="0">
|
|
<doc xml:space="preserve">Outputs a formatted message via the print handler.
|
|
The default print handler simply outputs the message to stdout, without
|
|
appending a trailing new-line character. Typically, @format should end with
|
|
its own new-line character.
|
|
|
|
g_print() should not be used from within libraries for debugging
|
|
messages, since it may be redirected by applications to special
|
|
purpose message windows or even files. Instead, libraries should
|
|
use g_log(), g_log_structured(), or the convenience macros g_message(),
|
|
g_warning() and g_error().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">the message format. See the printf() documentation</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">the parameters to insert into the format string</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="printerr" c:identifier="g_printerr" introspectable="0">
|
|
<doc xml:space="preserve">Outputs a formatted message via the error message handler.
|
|
The default handler simply outputs the message to stderr, without appending
|
|
a trailing new-line character. Typically, @format should end with its own
|
|
new-line character.
|
|
|
|
g_printerr() should not be used from within libraries.
|
|
Instead g_log() or g_log_structured() should be used, or the convenience
|
|
macros g_message(), g_warning() and g_error().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">the message format. See the printf() documentation</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">the parameters to insert into the format string</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="printf" c:identifier="g_printf" version="2.2" introspectable="0">
|
|
<doc xml:space="preserve">An implementation of the standard printf() function which supports
|
|
positional parameters, as specified in the Single Unix Specification.
|
|
|
|
As with the standard printf(), this does not automatically append a trailing
|
|
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.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes printed.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">a standard printf() format string, but notice
|
|
[string precision pitfalls][string-precision]</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">the arguments to insert in the output.</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="printf_string_upper_bound" c:identifier="g_printf_string_upper_bound" introspectable="0">
|
|
<doc xml:space="preserve">Calculates the maximum space needed to store the output
|
|
of the sprintf() function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum space needed to store the formatted string</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">the format string. See the printf() documentation</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="args" transfer-ownership="none">
|
|
<doc xml:space="preserve">the parameters to be inserted into the format string</doc>
|
|
<type name="va_list" c:type="va_list"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="propagate_error" c:identifier="g_propagate_error">
|
|
<doc xml:space="preserve">If @dest is %NULL, free @src; otherwise, moves @src into *@dest.
|
|
The error variable @dest points to must be %NULL.
|
|
|
|
@src must be non-%NULL.
|
|
|
|
Note that @src is no longer valid after this call. If you want
|
|
to keep using the same GError*, you need to set it to %NULL
|
|
after calling this function on it.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dest" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">error return location</doc>
|
|
<type name="Error" c:type="GError**"/>
|
|
</parameter>
|
|
<parameter name="src" transfer-ownership="full">
|
|
<doc xml:space="preserve">error to move into the return location</doc>
|
|
<type name="Error" c:type="GError*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="propagate_prefixed_error" c:identifier="g_propagate_prefixed_error" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">If @dest is %NULL, free @src; otherwise, moves @src into *@dest.
|
|
*@dest must be %NULL. After the move, add a prefix as with
|
|
g_prefix_error().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dest" transfer-ownership="none">
|
|
<doc xml:space="preserve">error return location</doc>
|
|
<type name="Error" c:type="GError**"/>
|
|
</parameter>
|
|
<parameter name="src" transfer-ownership="none">
|
|
<doc xml:space="preserve">error to move into the return location</doc>
|
|
<type name="Error" c:type="GError*"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">printf()-style format string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">arguments to @format</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ptr_array_find" c:identifier="g_ptr_array_find" moved-to="PtrArray.find" version="2.54" introspectable="0">
|
|
<doc xml:space="preserve">Checks whether @needle exists in @haystack. If the element is found, %TRUE is
|
|
returned and the element’s index is returned in @index_ (if non-%NULL).
|
|
Otherwise, %FALSE is returned and @index_ is undefined. If @needle exists
|
|
multiple times in @haystack, the index of the first instance is returned.
|
|
|
|
This does pointer comparisons only. If you want to use more complex equality
|
|
checks, such as string comparisons, use g_ptr_array_find_with_equal_func().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @needle is one of the elements of @haystack</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="haystack" transfer-ownership="none">
|
|
<doc xml:space="preserve">pointer array to be searched</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="needle" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">pointer to look for</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="index_" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the index of
|
|
the element, if found</doc>
|
|
<type name="guint" c:type="guint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ptr_array_find_with_equal_func" c:identifier="g_ptr_array_find_with_equal_func" moved-to="PtrArray.find_with_equal_func" version="2.54" introspectable="0">
|
|
<doc xml:space="preserve">Checks whether @needle exists in @haystack, using the given @equal_func.
|
|
If the element is found, %TRUE is returned and the element’s index is
|
|
returned in @index_ (if non-%NULL). Otherwise, %FALSE is returned and @index_
|
|
is undefined. If @needle exists multiple times in @haystack, the index of
|
|
the first instance is returned.
|
|
|
|
@equal_func is called with the element from the array as its first parameter,
|
|
and @needle as its second parameter. If @equal_func is %NULL, pointer
|
|
equality is used.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @needle is one of the elements of @haystack</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="haystack" transfer-ownership="none">
|
|
<doc xml:space="preserve">pointer array to be searched</doc>
|
|
<array name="GLib.PtrArray" c:type="GPtrArray*">
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="needle" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">pointer to look for</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="equal_func" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the function to call for each element, which should
|
|
return %TRUE when the desired element is found; or %NULL to use pointer
|
|
equality</doc>
|
|
<type name="EqualFunc" c:type="GEqualFunc"/>
|
|
</parameter>
|
|
<parameter name="index_" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for the index of
|
|
the element, if found</doc>
|
|
<type name="guint" c:type="guint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="ptr_array_index" c:identifier="g_ptr_array_index" introspectable="0">
|
|
<doc xml:space="preserve">Returns the pointer at the given index of the pointer array.
|
|
|
|
This does not perform bounds checking on the given @index_,
|
|
so you are responsible for checking it against the array length.</doc>
|
|
<parameters>
|
|
<parameter name="array">
|
|
<doc xml:space="preserve">a #GPtrArray</doc>
|
|
</parameter>
|
|
<parameter name="index_">
|
|
<doc xml:space="preserve">the index of the pointer to return</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="qsort_with_data" c:identifier="g_qsort_with_data" introspectable="0">
|
|
<doc xml:space="preserve">This is just like the standard C qsort() function, but
|
|
the comparison routine accepts a user data argument.
|
|
|
|
This is guaranteed to be a stable sort since version 2.32.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="pbase" transfer-ownership="none">
|
|
<doc xml:space="preserve">start of array to sort</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="total_elems" transfer-ownership="none">
|
|
<doc xml:space="preserve">elements in the array</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="size" transfer-ownership="none">
|
|
<doc xml:space="preserve">size of each element</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="compare_func" transfer-ownership="none" closure="4">
|
|
<doc xml:space="preserve">function to compare elements</doc>
|
|
<type name="CompareDataFunc" c:type="GCompareDataFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @compare_func</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="quark_from_static_string" c:identifier="g_quark_from_static_string">
|
|
<doc xml:space="preserve">Gets the #GQuark identifying the given (static) string. If the
|
|
string does not currently have an associated #GQuark, a new #GQuark
|
|
is created, linked to the given string.
|
|
|
|
Note that this function is identical to g_quark_from_string() except
|
|
that if a new #GQuark is created the string itself is used rather
|
|
than a copy. This saves memory, but can only be used if the string
|
|
will continue to exist until the program terminates. It can be used
|
|
with statically allocated strings in the main program, but not with
|
|
statically allocated memory in dynamically loaded modules, if you
|
|
expect to ever unload the module again (e.g. do not use this
|
|
function in GTK+ theme engines).
|
|
|
|
This function must not be used before library constructors have finished
|
|
running. In particular, this means it cannot be used to initialize global
|
|
variables in C++.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GQuark identifying the string, or 0 if @string is %NULL</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="quark_from_string" c:identifier="g_quark_from_string">
|
|
<doc xml:space="preserve">Gets the #GQuark identifying the given string. If the string does
|
|
not currently have an associated #GQuark, a new #GQuark is created,
|
|
using a copy of the string.
|
|
|
|
This function must not be used before library constructors have finished
|
|
running. In particular, this means it cannot be used to initialize global
|
|
variables in C++.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GQuark identifying the string, or 0 if @string is %NULL</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="quark_to_string" c:identifier="g_quark_to_string">
|
|
<doc xml:space="preserve">Gets the string associated with the given #GQuark.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the string associated with the #GQuark</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="quark" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GQuark.</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="quark_try_string" c:identifier="g_quark_try_string">
|
|
<doc xml:space="preserve">Gets the #GQuark associated with the given string, or 0 if string is
|
|
%NULL or it has no associated #GQuark.
|
|
|
|
If you want the GQuark to be created if it doesn't already exist,
|
|
use g_quark_from_string() or g_quark_from_static_string().
|
|
|
|
This function must not be used before library constructors have finished
|
|
running.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GQuark associated with the string, or 0 if @string is
|
|
%NULL or there is no #GQuark associated with it</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="quarks">
|
|
<doc xml:space="preserve">Quarks are associations between strings and integer identifiers.
|
|
Given either the string or the #GQuark identifier it is possible to
|
|
retrieve the other.
|
|
|
|
Quarks are used for both [datasets][glib-Datasets] and
|
|
[keyed data lists][glib-Keyed-Data-Lists].
|
|
|
|
To create a new quark from a string, use g_quark_from_string() or
|
|
g_quark_from_static_string().
|
|
|
|
To find the string corresponding to a given #GQuark, use
|
|
g_quark_to_string().
|
|
|
|
To find the #GQuark corresponding to a given string, use
|
|
g_quark_try_string().
|
|
|
|
Another use for the string pool maintained for the quark functions
|
|
is string interning, using g_intern_string() or
|
|
g_intern_static_string(). An interned string is a canonical
|
|
representation for a string. One important advantage of interned
|
|
strings is that they can be compared for equality by a simple
|
|
pointer comparison, rather than using strcmp().</doc>
|
|
</docsection>
|
|
<docsection name="queue">
|
|
<doc xml:space="preserve">The #GQueue structure and its associated functions provide a standard
|
|
queue data structure. Internally, GQueue uses the same data structure
|
|
as #GList to store elements with the same complexity over
|
|
insertion/deletion (O(1)) and access/search (O(n)) operations.
|
|
|
|
The data contained in each element can be either integer values, by
|
|
using one of the [Type Conversion Macros][glib-Type-Conversion-Macros],
|
|
or simply pointers to any type of data.
|
|
|
|
As with all other GLib data structures, #GQueue is not thread-safe.
|
|
For a thread-safe queue, use #GAsyncQueue.
|
|
|
|
To create a new GQueue, use g_queue_new().
|
|
|
|
To initialize a statically-allocated GQueue, use #G_QUEUE_INIT or
|
|
g_queue_init().
|
|
|
|
To add elements, use g_queue_push_head(), g_queue_push_head_link(),
|
|
g_queue_push_tail() and g_queue_push_tail_link().
|
|
|
|
To remove elements, use g_queue_pop_head() and g_queue_pop_tail().
|
|
|
|
To free the entire queue, use g_queue_free().</doc>
|
|
</docsection>
|
|
<function-macro name="rand_boolean" c:identifier="g_rand_boolean" introspectable="0">
|
|
<doc xml:space="preserve">Returns a random #gboolean from @rand_.
|
|
This corresponds to an unbiased coin toss.</doc>
|
|
<parameters>
|
|
<parameter name="rand_">
|
|
<doc xml:space="preserve">a #GRand</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="random_double" c:identifier="g_random_double">
|
|
<doc xml:space="preserve">Returns a random #gdouble equally distributed over the range [0..1).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a random number</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="random_double_range" c:identifier="g_random_double_range">
|
|
<doc xml:space="preserve">Returns a random #gdouble equally distributed over the range
|
|
[@begin..@end).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a random number</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="begin" transfer-ownership="none">
|
|
<doc xml:space="preserve">lower closed bound of the interval</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</parameter>
|
|
<parameter name="end" transfer-ownership="none">
|
|
<doc xml:space="preserve">upper open bound of the interval</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="random_int" c:identifier="g_random_int">
|
|
<doc xml:space="preserve">Return a random #guint32 equally distributed over the range
|
|
[0..2^32-1].</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a random number</doc>
|
|
<type name="guint32" c:type="guint32"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="random_int_range" c:identifier="g_random_int_range">
|
|
<doc xml:space="preserve">Returns a random #gint32 equally distributed over the range
|
|
[@begin..@end-1].</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a random number</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="begin" transfer-ownership="none">
|
|
<doc xml:space="preserve">lower closed bound of the interval</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</parameter>
|
|
<parameter name="end" transfer-ownership="none">
|
|
<doc xml:space="preserve">upper open bound of the interval</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="random_numbers">
|
|
<doc xml:space="preserve">The following functions allow you to use a portable, fast and good
|
|
pseudo-random number generator (PRNG).
|
|
|
|
Do not use this API for cryptographic purposes such as key
|
|
generation, nonces, salts or one-time pads.
|
|
|
|
This PRNG is suitable for non-cryptographic use such as in games
|
|
(shuffling a card deck, generating levels), generating data for
|
|
a test suite, etc. If you need random data for cryptographic
|
|
purposes, it is recommended to use platform-specific APIs such
|
|
as `/dev/random` on UNIX, or CryptGenRandom() on Windows.
|
|
|
|
GRand uses the Mersenne Twister PRNG, which was originally
|
|
developed by Makoto Matsumoto and Takuji Nishimura. Further
|
|
information can be found at
|
|
[this page](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html).
|
|
|
|
If you just need a random number, you simply call the g_random_*
|
|
functions, which will create a globally used #GRand and use the
|
|
according g_rand_* functions internally. Whenever you need a
|
|
stream of reproducible random numbers, you better create a
|
|
#GRand yourself and use the g_rand_* functions directly, which
|
|
will also be slightly faster. Initializing a #GRand with a
|
|
certain seed will produce exactly the same series of random
|
|
numbers on all platforms. This can thus be used as a seed for
|
|
e.g. games.
|
|
|
|
The g_rand*_range functions will return high quality equally
|
|
distributed random numbers, whereas for example the
|
|
`(g_random_int()%max)` approach often
|
|
doesn't yield equally distributed numbers.
|
|
|
|
GLib changed the seeding algorithm for the pseudo-random number
|
|
generator Mersenne Twister, as used by #GRand. This was necessary,
|
|
because some seeds would yield very bad pseudo-random streams.
|
|
Also the pseudo-random integers generated by g_rand*_int_range()
|
|
will have a slightly better equal distribution with the new
|
|
version of GLib.
|
|
|
|
The original seeding and generation algorithms, as found in
|
|
GLib 2.0.x, can be used instead of the new ones by setting the
|
|
environment variable `G_RANDOM_VERSION` to the value of '2.0'.
|
|
Use the GLib-2.0 algorithms only if you have sequences of numbers
|
|
generated with Glib-2.0 that you need to reproduce exactly.</doc>
|
|
</docsection>
|
|
<function name="random_set_seed" c:identifier="g_random_set_seed">
|
|
<doc xml:space="preserve">Sets the seed for the global random number generator, which is used
|
|
by the g_random_* functions, to @seed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="seed" transfer-ownership="none">
|
|
<doc xml:space="preserve">a value to reinitialize the global random number generator</doc>
|
|
<type name="guint32" c:type="guint32"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="rc_box_acquire" c:identifier="g_rc_box_acquire" version="2.58">
|
|
<doc xml:space="preserve">Acquires a reference on the data pointed by @mem_block.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to the data,
|
|
with its reference count increased</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mem_block" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to reference counted data</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="rc_box_alloc" c:identifier="g_rc_box_alloc" version="2.58">
|
|
<doc xml:space="preserve">Allocates @block_size bytes of memory, and adds reference
|
|
counting semantics to it.
|
|
|
|
The data will be freed when its reference count drops to
|
|
zero.
|
|
|
|
The allocated data is guaranteed to be suitably aligned for any
|
|
built-in type.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to the allocated memory</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="block_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of the allocation, must be greater than 0</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="rc_box_alloc0" c:identifier="g_rc_box_alloc0" version="2.58">
|
|
<doc xml:space="preserve">Allocates @block_size bytes of memory, and adds reference
|
|
counting semantics to it.
|
|
|
|
The contents of the returned data is set to zero.
|
|
|
|
The data will be freed when its reference count drops to
|
|
zero.
|
|
|
|
The allocated data is guaranteed to be suitably aligned for any
|
|
built-in type.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to the allocated memory</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="block_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of the allocation, must be greater than 0</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="rc_box_dup" c:identifier="g_rc_box_dup" version="2.58">
|
|
<doc xml:space="preserve">Allocates a new block of data with reference counting
|
|
semantics, and copies @block_size bytes of @mem_block
|
|
into it.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to the allocated
|
|
memory</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="block_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes to copy, must be greater than 0</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="mem_block" transfer-ownership="none">
|
|
<doc xml:space="preserve">the memory to copy</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="rc_box_get_size" c:identifier="g_rc_box_get_size" version="2.58">
|
|
<doc xml:space="preserve">Retrieves the size of the reference counted data pointed by @mem_block.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of the data, in bytes</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mem_block" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to reference counted data</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="rc_box_new" c:identifier="g_rc_box_new" version="2.58" introspectable="0">
|
|
<doc xml:space="preserve">A convenience macro to allocate reference counted data with
|
|
the size of the given @type.
|
|
|
|
This macro calls g_rc_box_alloc() with `sizeof (@type)` and
|
|
casts the returned pointer to a pointer of the given @type,
|
|
avoiding a type cast in the source code.</doc>
|
|
<parameters>
|
|
<parameter name="type">
|
|
<doc xml:space="preserve">the type to allocate, typically a structure name</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="rc_box_new0" c:identifier="g_rc_box_new0" version="2.58" introspectable="0">
|
|
<doc xml:space="preserve">A convenience macro to allocate reference counted data with
|
|
the size of the given @type, and set its contents to zero.
|
|
|
|
This macro calls g_rc_box_alloc0() with `sizeof (@type)` and
|
|
casts the returned pointer to a pointer of the given @type,
|
|
avoiding a type cast in the source code.</doc>
|
|
<parameters>
|
|
<parameter name="type">
|
|
<doc xml:space="preserve">the type to allocate, typically a structure name</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="rc_box_release" c:identifier="g_rc_box_release" version="2.58">
|
|
<doc xml:space="preserve">Releases a reference on the data pointed by @mem_block.
|
|
|
|
If the reference was the last one, it will free the
|
|
resources allocated for @mem_block.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mem_block" transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to reference counted data</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="rc_box_release_full" c:identifier="g_rc_box_release_full" version="2.58">
|
|
<doc xml:space="preserve">Releases a reference on the data pointed by @mem_block.
|
|
|
|
If the reference was the last one, it will call @clear_func
|
|
to clear the contents of @mem_block, and then will free the
|
|
resources allocated for @mem_block.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mem_block" transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to reference counted data</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="clear_func" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">a function to call when clearing the data</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="rcbox">
|
|
<doc xml:space="preserve">A "reference counted box", or "RcBox", is an opaque wrapper data type
|
|
that is guaranteed to be as big as the size of a given data type, and
|
|
which augments the given data type with reference counting semantics
|
|
for its memory management.
|
|
|
|
RcBox is useful if you have a plain old data type, like a structure
|
|
typically placed on the stack, and you wish to provide additional API
|
|
to use it on the heap; or if you want to implement a new type to be
|
|
passed around by reference without necessarily implementing copy/free
|
|
semantics or your own reference counting.
|
|
|
|
The typical use is:
|
|
|
|
|[<!-- language="C" -->
|
|
typedef struct {
|
|
char *name;
|
|
char *address;
|
|
char *city;
|
|
char *state;
|
|
int age;
|
|
} Person;
|
|
|
|
Person *
|
|
person_new (void)
|
|
{
|
|
return g_rc_box_new0 (Person);
|
|
}
|
|
]|
|
|
|
|
Every time you wish to acquire a reference on the memory, you should
|
|
call g_rc_box_acquire(); similarly, when you wish to release a reference
|
|
you should call g_rc_box_release():
|
|
|
|
|[<!-- language="C" -->
|
|
// Add a Person to the Database; the Database acquires ownership
|
|
// of the Person instance
|
|
void
|
|
add_person_to_database (Database *db, Person *p)
|
|
{
|
|
db->persons = g_list_prepend (db->persons, g_rc_box_acquire (p));
|
|
}
|
|
|
|
// Removes a Person from the Database; the reference acquired by
|
|
// add_person_to_database() is released here
|
|
void
|
|
remove_person_from_database (Database *db, Person *p)
|
|
{
|
|
db->persons = g_list_remove (db->persons, p);
|
|
g_rc_box_release (p);
|
|
}
|
|
]|
|
|
|
|
If you have additional memory allocated inside the structure, you can
|
|
use g_rc_box_release_full(), which takes a function pointer, which
|
|
will be called if the reference released was the last:
|
|
|
|
|[<!-- language="C" -->
|
|
void
|
|
person_clear (Person *p)
|
|
{
|
|
g_free (p->name);
|
|
g_free (p->address);
|
|
g_free (p->city);
|
|
g_free (p->state);
|
|
}
|
|
|
|
void
|
|
remove_person_from_database (Database *db, Person *p)
|
|
{
|
|
db->persons = g_list_remove (db->persons, p);
|
|
g_rc_box_release_full (p, (GDestroyNotify) person_clear);
|
|
}
|
|
]|
|
|
|
|
If you wish to transfer the ownership of a reference counted data
|
|
type without increasing the reference count, you can use g_steal_pointer():
|
|
|
|
|[<!-- language="C" -->
|
|
Person *p = g_rc_box_new (Person);
|
|
|
|
// fill_person_details() is defined elsewhere
|
|
fill_person_details (p);
|
|
|
|
// add_person_to_database_no_ref() is defined elsewhere; it adds
|
|
// a Person to the Database without taking a reference
|
|
add_person_to_database_no_ref (db, g_steal_pointer (&p));
|
|
]|
|
|
|
|
## Thread safety
|
|
|
|
The reference counting operations on data allocated using g_rc_box_alloc(),
|
|
g_rc_box_new(), and g_rc_box_dup() are not thread safe; it is your code's
|
|
responsibility to ensure that references are acquired are released on the
|
|
same thread.
|
|
|
|
If you need thread safe reference counting, see the [atomic reference counted
|
|
data][arcbox] API.
|
|
|
|
## Automatic pointer clean up
|
|
|
|
If you want to add g_autoptr() support to your plain old data type through
|
|
reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and
|
|
g_rc_box_release():
|
|
|
|
|[<!-- language="C" -->
|
|
G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_rc_box_release)
|
|
]|
|
|
|
|
If you need to clear the contents of the data, you will need to use an
|
|
ancillary function that calls g_rc_box_release_full():
|
|
|
|
|[<!-- language="C" -->
|
|
static void
|
|
my_data_struct_release (MyDataStruct *data)
|
|
{
|
|
// my_data_struct_clear() is defined elsewhere
|
|
g_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear);
|
|
}
|
|
|
|
G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_release)
|
|
]|</doc>
|
|
</docsection>
|
|
<function name="realloc" c:identifier="g_realloc">
|
|
<doc xml:space="preserve">Reallocates the memory pointed to by @mem, so that it now has space for
|
|
@n_bytes bytes of memory. It returns the new address of the memory, which may
|
|
have been moved. @mem may be %NULL, in which case it's considered to
|
|
have zero-length. @n_bytes may be 0, in which case %NULL will be returned
|
|
and @mem will be freed unless it is %NULL.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the new address of the allocated memory</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mem" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the memory to reallocate</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="n_bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">new size of the memory in bytes</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="realloc_n" c:identifier="g_realloc_n" version="2.24">
|
|
<doc xml:space="preserve">This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
|
|
but care is taken to detect possible overflow during multiplication.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the new address of the allocated memory</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mem" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the memory to reallocate</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="n_blocks" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of blocks to allocate</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="n_block_bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of each block in bytes</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ref_count_compare" c:identifier="g_ref_count_compare" version="2.58">
|
|
<doc xml:space="preserve">Compares the current value of @rc with @val.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the reference count is the same
|
|
as the given value</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="rc" transfer-ownership="none">
|
|
<doc xml:space="preserve">the address of a reference count variable</doc>
|
|
<type name="gint" c:type="grefcount*"/>
|
|
</parameter>
|
|
<parameter name="val" transfer-ownership="none">
|
|
<doc xml:space="preserve">the value to compare</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ref_count_dec" c:identifier="g_ref_count_dec" version="2.58">
|
|
<doc xml:space="preserve">Decreases the reference count.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the reference count reached 0, and %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="rc" transfer-ownership="none">
|
|
<doc xml:space="preserve">the address of a reference count variable</doc>
|
|
<type name="gint" c:type="grefcount*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ref_count_inc" c:identifier="g_ref_count_inc" version="2.58">
|
|
<doc xml:space="preserve">Increases the reference count.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="rc" transfer-ownership="none">
|
|
<doc xml:space="preserve">the address of a reference count variable</doc>
|
|
<type name="gint" c:type="grefcount*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ref_count_init" c:identifier="g_ref_count_init" version="2.58">
|
|
<doc xml:space="preserve">Initializes a reference count variable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="rc" transfer-ownership="none">
|
|
<doc xml:space="preserve">the address of a reference count variable</doc>
|
|
<type name="gint" c:type="grefcount*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ref_string_acquire" c:identifier="g_ref_string_acquire" version="2.58">
|
|
<doc xml:space="preserve">Acquires a reference on a string.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the given string, with its reference count increased</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a reference counted string</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ref_string_length" c:identifier="g_ref_string_length" version="2.58">
|
|
<doc xml:space="preserve">Retrieves the length of @str.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the given string, in bytes</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a reference counted string</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ref_string_new" c:identifier="g_ref_string_new" version="2.58">
|
|
<doc xml:space="preserve">Creates a new reference counted string and copies the contents of @str
|
|
into it.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the newly created reference counted string</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a NUL-terminated string</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ref_string_new_intern" c:identifier="g_ref_string_new_intern" version="2.58">
|
|
<doc xml:space="preserve">Creates a new reference counted string and copies the content of @str
|
|
into it.
|
|
|
|
If you call this function multiple times with the same @str, or with
|
|
the same contents of @str, it will return a new reference, instead of
|
|
creating a new string.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the newly created reference
|
|
counted string, or a new reference to an existing string</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a NUL-terminated string</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ref_string_new_len" c:identifier="g_ref_string_new_len" version="2.58">
|
|
<doc xml:space="preserve">Creates a new reference counted string and copies the contents of @str
|
|
into it, up to @len bytes.
|
|
|
|
Since this function does not stop at nul bytes, it is the caller's
|
|
responsibility to ensure that @str has at least @len addressable bytes.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the newly created reference counted string</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @str to use, or -1 if @str is nul-terminated</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ref_string_release" c:identifier="g_ref_string_release" version="2.58">
|
|
<doc xml:space="preserve">Releases a reference on a string; if it was the last reference, the
|
|
resources allocated by the string are freed as well.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a reference counted string</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="refcount">
|
|
<doc xml:space="preserve">Reference counting is a garbage collection mechanism that is based on
|
|
assigning a counter to a data type, or any memory area; the counter is
|
|
increased whenever a new reference to that data type is acquired, and
|
|
decreased whenever the reference is released. Once the last reference
|
|
is released, the resources associated to that data type are freed.
|
|
|
|
GLib uses reference counting in many of its data types, and provides
|
|
the #grefcount and #gatomicrefcount types to implement safe and atomic
|
|
reference counting semantics in new data types.
|
|
|
|
It is important to note that #grefcount and #gatomicrefcount should be
|
|
considered completely opaque types; you should always use the provided
|
|
API to increase and decrease the counters, and you should never check
|
|
their content directly, or compare their content with other values.</doc>
|
|
</docsection>
|
|
<docsection name="refstring">
|
|
<doc xml:space="preserve">Reference counted strings are normal C strings that have been augmented
|
|
with a reference counter to manage their resources. You allocate a new
|
|
reference counted string and acquire and release references as needed,
|
|
instead of copying the string among callers; when the last reference on
|
|
the string is released, the resources allocated for it are freed.
|
|
|
|
Typically, reference counted strings can be used when parsing data from
|
|
files and storing them into data structures that are passed to various
|
|
callers:
|
|
|
|
|[<!-- language="C" -->
|
|
PersonDetails *
|
|
person_details_from_data (const char *data)
|
|
{
|
|
// Use g_autoptr() to simplify error cases
|
|
g_autoptr(GRefString) full_name = NULL;
|
|
g_autoptr(GRefString) address = NULL;
|
|
g_autoptr(GRefString) city = NULL;
|
|
g_autoptr(GRefString) state = NULL;
|
|
g_autoptr(GRefString) zip_code = NULL;
|
|
|
|
// parse_person_details() is defined elsewhere; returns refcounted strings
|
|
if (!parse_person_details (data, &full_name, &address, &city, &state, &zip_code))
|
|
return NULL;
|
|
|
|
if (!validate_zip_code (zip_code))
|
|
return NULL;
|
|
|
|
// add_address_to_cache() and add_full_name_to_cache() are defined
|
|
// elsewhere; they add strings to various caches, using refcounted
|
|
// strings to avoid copying data over and over again
|
|
add_address_to_cache (address, city, state, zip_code);
|
|
add_full_name_to_cache (full_name);
|
|
|
|
// person_details_new() is defined elsewhere; it takes a reference
|
|
// on each string
|
|
PersonDetails *res = person_details_new (full_name,
|
|
address,
|
|
city,
|
|
state,
|
|
zip_code);
|
|
|
|
return res;
|
|
}
|
|
]|
|
|
|
|
In the example above, we have multiple functions taking the same strings
|
|
for different uses; with typical C strings, we'd have to copy the strings
|
|
every time the life time rules of the data differ from the life time of
|
|
the string parsed from the original buffer. With reference counted strings,
|
|
each caller can take a reference on the data, and keep it as long as it
|
|
needs to own the string.
|
|
|
|
Reference counted strings can also be "interned" inside a global table
|
|
owned by GLib; while an interned string has at least a reference, creating
|
|
a new interned reference counted string with the same contents will return
|
|
a reference to the existing string instead of creating a new reference
|
|
counted string instance. Once the string loses its last reference, it will
|
|
be automatically removed from the global interned strings table.</doc>
|
|
</docsection>
|
|
<function name="regex_check_replacement" c:identifier="g_regex_check_replacement" moved-to="Regex.check_replacement" version="2.14" throws="1">
|
|
<doc xml:space="preserve">Checks whether @replacement is a valid replacement string
|
|
(see g_regex_replace()), i.e. that all escape sequences in
|
|
it are valid.
|
|
|
|
If @has_references is not %NULL then @replacement is checked
|
|
for pattern references. For instance, replacement text 'foo\n'
|
|
does not contain references and may be evaluated without information
|
|
about actual match, but '\0\1' (whole match followed by first
|
|
subpattern) requires valid #GMatchInfo object.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">whether @replacement is a valid replacement string</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="replacement" transfer-ownership="none">
|
|
<doc xml:space="preserve">the replacement string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="has_references" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store information about
|
|
references in @replacement or %NULL</doc>
|
|
<type name="gboolean" c:type="gboolean*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="regex_error_quark" c:identifier="g_regex_error_quark" moved-to="Regex.error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="regex_escape_nul" c:identifier="g_regex_escape_nul" moved-to="Regex.escape_nul" version="2.30">
|
|
<doc xml:space="preserve">Escapes the nul characters in @string to "\x00". It can be used
|
|
to compile a regex with embedded nul characters.
|
|
|
|
For completeness, @length can be -1 for a nul-terminated string.
|
|
In this case the output string will be of course equal to @string.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated escaped string</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to escape</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @string</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="regex_escape_string" c:identifier="g_regex_escape_string" moved-to="Regex.escape_string" version="2.14">
|
|
<doc xml:space="preserve">Escapes the special characters used for regular expressions
|
|
in @string, for instance "a.b*c" becomes "a\.b\*c". This
|
|
function is useful to dynamically generate regular expressions.
|
|
|
|
@string can contain nul characters that are replaced with "\0",
|
|
in this case remember to specify the correct length of @string
|
|
in @length.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated escaped string</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to escape</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar*">
|
|
<type name="utf8" c:type="gchar"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @string, in bytes, or -1 if @string is nul-terminated</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="regex_match_simple" c:identifier="g_regex_match_simple" moved-to="Regex.match_simple" version="2.14">
|
|
<doc xml:space="preserve">Scans for a match in @string for @pattern.
|
|
|
|
This function is equivalent to g_regex_match() but it does not
|
|
require to compile the pattern with g_regex_new(), avoiding some
|
|
lines of code when you need just to do a match without extracting
|
|
substrings, capture counts, and so on.
|
|
|
|
If this function is to be called on the same @pattern more than
|
|
once, it's more efficient to compile the pattern once with
|
|
g_regex_new() and then use g_regex_match().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the string matched, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="pattern" transfer-ownership="none">
|
|
<doc xml:space="preserve">the regular expression</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to scan for matches</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="compile_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">compile options for the regular expression, or 0</doc>
|
|
<type name="RegexCompileFlags" c:type="GRegexCompileFlags"/>
|
|
</parameter>
|
|
<parameter name="match_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">match options, or 0</doc>
|
|
<type name="RegexMatchFlags" c:type="GRegexMatchFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="regex_split_simple" c:identifier="g_regex_split_simple" moved-to="Regex.split_simple" version="2.14">
|
|
<doc xml:space="preserve">Breaks the string on the pattern, and returns an array of
|
|
the tokens. If the pattern contains capturing parentheses,
|
|
then the text for each of the substrings will also be returned.
|
|
If the pattern does not match anywhere in the string, then the
|
|
whole string is returned as the first token.
|
|
|
|
This function is equivalent to g_regex_split() but it does
|
|
not require to compile the pattern with g_regex_new(), avoiding
|
|
some lines of code when you need just to do a split without
|
|
extracting substrings, capture counts, and so on.
|
|
|
|
If this function is to be called on the same @pattern more than
|
|
once, it's more efficient to compile the pattern once with
|
|
g_regex_new() and then use g_regex_split().
|
|
|
|
As a special case, the result of splitting the empty string ""
|
|
is an empty vector, not a vector containing a single string.
|
|
The reason for this special case is that being able to represent
|
|
an empty vector is typically more useful than consistent handling
|
|
of empty elements. If you do need to represent empty elements,
|
|
you'll need to check for the empty string before calling this
|
|
function.
|
|
|
|
A pattern that can match empty strings splits @string into
|
|
separate characters wherever it matches the empty string between
|
|
characters. For example splitting "ab c" using as a separator
|
|
"\s*", you will get "a", "b" and "c".</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a %NULL-terminated array of strings. Free
|
|
it using g_strfreev()</doc>
|
|
<array c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="pattern" transfer-ownership="none">
|
|
<doc xml:space="preserve">the regular expression</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to scan for matches</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="compile_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">compile options for the regular expression, or 0</doc>
|
|
<type name="RegexCompileFlags" c:type="GRegexCompileFlags"/>
|
|
</parameter>
|
|
<parameter name="match_options" transfer-ownership="none">
|
|
<doc xml:space="preserve">match options, or 0</doc>
|
|
<type name="RegexMatchFlags" c:type="GRegexMatchFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="reload_user_special_dirs_cache" c:identifier="g_reload_user_special_dirs_cache" version="2.22">
|
|
<doc xml:space="preserve">Resets the cache used for g_get_user_special_dir(), so
|
|
that the latest on-disk version is used. Call this only
|
|
if you just changed the data on disk yourself.
|
|
|
|
Due to thread safety issues this may cause leaking of strings
|
|
that were previously returned from g_get_user_special_dir()
|
|
that can't be freed. We ensure to only leak the data for
|
|
the directories that actually changed value though.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
</function>
|
|
<function-macro name="renew" c:identifier="g_renew" introspectable="0">
|
|
<doc xml:space="preserve">Reallocates the memory pointed to by @mem, so that it now has space for
|
|
@n_structs elements of type @struct_type. It returns the new address of
|
|
the memory, which may have been moved.
|
|
Care is taken to avoid overflow when calculating the size of the allocated block.</doc>
|
|
<parameters>
|
|
<parameter name="struct_type">
|
|
<doc xml:space="preserve">the type of the elements to allocate</doc>
|
|
</parameter>
|
|
<parameter name="mem">
|
|
<doc xml:space="preserve">the currently allocated memory</doc>
|
|
</parameter>
|
|
<parameter name="n_structs">
|
|
<doc xml:space="preserve">the number of elements to allocate</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="return_if_fail" c:identifier="g_return_if_fail" introspectable="0">
|
|
<parameters>
|
|
<parameter name="expr">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="return_if_fail_warning" c:identifier="g_return_if_fail_warning" introspectable="0">
|
|
<doc xml:space="preserve">Internal function used to print messages from the public g_return_if_fail()
|
|
and g_return_val_if_fail() macros.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_domain" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">log domain</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="pretty_function" transfer-ownership="none">
|
|
<doc xml:space="preserve">function containing the assertion</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="expression" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">expression which failed</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="return_val_if_fail" c:identifier="g_return_val_if_fail" introspectable="0">
|
|
<parameters>
|
|
<parameter name="expr">
|
|
</parameter>
|
|
<parameter name="val">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="return_val_if_reached" c:identifier="g_return_val_if_reached" introspectable="0">
|
|
<parameters>
|
|
<parameter name="val">
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="rmdir" c:identifier="g_rmdir" version="2.6">
|
|
<doc xml:space="preserve">A wrapper for the POSIX rmdir() function. The rmdir() function
|
|
deletes a directory from the filesystem.
|
|
|
|
See your C library manual for more details about how rmdir() works
|
|
on your system.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">0 if the directory was successfully removed, -1 if an error
|
|
occurred</doc>
|
|
<type name="gint" c:type="int"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="filename" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pathname in the GLib file name encoding
|
|
(UTF-8 on Windows)</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="scanner">
|
|
<doc xml:space="preserve">The #GScanner and its associated functions provide a
|
|
general purpose lexical scanner.</doc>
|
|
</docsection>
|
|
<function-macro name="scanner_add_symbol" c:identifier="g_scanner_add_symbol" introspectable="0" deprecated="1" deprecated-version="2.2">
|
|
<doc xml:space="preserve">Adds a symbol to the default scope.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_scanner_scope_add_symbol() instead.</doc-deprecated>
|
|
<parameters>
|
|
<parameter name="scanner">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
</parameter>
|
|
<parameter name="symbol">
|
|
<doc xml:space="preserve">the symbol to add</doc>
|
|
</parameter>
|
|
<parameter name="value">
|
|
<doc xml:space="preserve">the value of the symbol</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="scanner_foreach_symbol" c:identifier="g_scanner_foreach_symbol" introspectable="0" deprecated="1" deprecated-version="2.2">
|
|
<doc xml:space="preserve">Calls a function for each symbol in the default scope.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_scanner_scope_foreach_symbol() instead.</doc-deprecated>
|
|
<parameters>
|
|
<parameter name="scanner">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
</parameter>
|
|
<parameter name="func">
|
|
<doc xml:space="preserve">the function to call with each symbol</doc>
|
|
</parameter>
|
|
<parameter name="data">
|
|
<doc xml:space="preserve">data to pass to the function</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="scanner_freeze_symbol_table" c:identifier="g_scanner_freeze_symbol_table" introspectable="0" deprecated="1" deprecated-version="2.2">
|
|
<doc xml:space="preserve">There is no reason to use this macro, since it does nothing.</doc>
|
|
<doc-deprecated xml:space="preserve">This macro does nothing.</doc-deprecated>
|
|
<parameters>
|
|
<parameter name="scanner">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="scanner_remove_symbol" c:identifier="g_scanner_remove_symbol" introspectable="0" deprecated="1" deprecated-version="2.2">
|
|
<doc xml:space="preserve">Removes a symbol from the default scope.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_scanner_scope_remove_symbol() instead.</doc-deprecated>
|
|
<parameters>
|
|
<parameter name="scanner">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
</parameter>
|
|
<parameter name="symbol">
|
|
<doc xml:space="preserve">the symbol to remove</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="scanner_thaw_symbol_table" c:identifier="g_scanner_thaw_symbol_table" introspectable="0" deprecated="1" deprecated-version="2.2">
|
|
<doc xml:space="preserve">There is no reason to use this macro, since it does nothing.</doc>
|
|
<doc-deprecated xml:space="preserve">This macro does nothing.</doc-deprecated>
|
|
<parameters>
|
|
<parameter name="scanner">
|
|
<doc xml:space="preserve">a #GScanner</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<docsection name="sequence">
|
|
<doc xml:space="preserve">The #GSequence data structure has the API of a list, but is
|
|
implemented internally with a balanced binary tree. This means that
|
|
most of the operations (access, search, insertion, deletion, ...) on
|
|
#GSequence are O(log(n)) in average and O(n) in worst case for time
|
|
complexity. But, note that maintaining a balanced sorted list of n
|
|
elements is done in time O(n log(n)).
|
|
The data contained in each element can be either integer values, by using
|
|
of the [Type Conversion Macros][glib-Type-Conversion-Macros], or simply
|
|
pointers to any type of data.
|
|
|
|
A #GSequence is accessed through "iterators", represented by a
|
|
#GSequenceIter. An iterator represents a position between two
|
|
elements of the sequence. For example, the "begin" iterator
|
|
represents the gap immediately before the first element of the
|
|
sequence, and the "end" iterator represents the gap immediately
|
|
after the last element. In an empty sequence, the begin and end
|
|
iterators are the same.
|
|
|
|
Some methods on #GSequence operate on ranges of items. For example
|
|
g_sequence_foreach_range() will call a user-specified function on
|
|
each element with the given range. The range is delimited by the
|
|
gaps represented by the passed-in iterators, so if you pass in the
|
|
begin and end iterators, the range in question is the entire
|
|
sequence.
|
|
|
|
The function g_sequence_get() is used with an iterator to access the
|
|
element immediately following the gap that the iterator represents.
|
|
The iterator is said to "point" to that element.
|
|
|
|
Iterators are stable across most operations on a #GSequence. For
|
|
example an iterator pointing to some element of a sequence will
|
|
continue to point to that element even after the sequence is sorted.
|
|
Even moving an element to another sequence using for example
|
|
g_sequence_move_range() will not invalidate the iterators pointing
|
|
to it. The only operation that will invalidate an iterator is when
|
|
the element it points to is removed from any sequence.
|
|
|
|
To sort the data, either use g_sequence_insert_sorted() or
|
|
g_sequence_insert_sorted_iter() to add data to the #GSequence or, if
|
|
you want to add a large amount of data, it is more efficient to call
|
|
g_sequence_sort() or g_sequence_sort_iter() after doing unsorted
|
|
insertions.</doc>
|
|
</docsection>
|
|
<function name="sequence_get" c:identifier="g_sequence_get" moved-to="Sequence.get" version="2.14">
|
|
<doc xml:space="preserve">Returns the data that @iter points to.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the data that @iter points to</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sequence_insert_before" c:identifier="g_sequence_insert_before" moved-to="Sequence.insert_before" version="2.14">
|
|
<doc xml:space="preserve">Inserts a new item just before the item pointed to by @iter.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">an iterator pointing to the new item</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the data for the new item</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sequence_move" c:identifier="g_sequence_move" moved-to="Sequence.move" version="2.14">
|
|
<doc xml:space="preserve">Moves the item pointed to by @src to the position indicated by @dest.
|
|
After calling this function @dest will point to the position immediately
|
|
after @src. It is allowed for @src and @dest to point into different
|
|
sequences.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="src" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter pointing to the item to move</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="dest" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter pointing to the position to which
|
|
the item is moved</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sequence_move_range" c:identifier="g_sequence_move_range" moved-to="Sequence.move_range" version="2.14">
|
|
<doc xml:space="preserve">Inserts the (@begin, @end) range at the destination pointed to by @dest.
|
|
The @begin and @end iters must point into the same sequence. It is
|
|
allowed for @dest to point to a different sequence than the one pointed
|
|
into by @begin and @end.
|
|
|
|
If @dest is %NULL, the range indicated by @begin and @end is
|
|
removed from the sequence. If @dest points to a place within
|
|
the (@begin, @end) range, the range does not move.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dest" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="begin" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="end" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sequence_range_get_midpoint" c:identifier="g_sequence_range_get_midpoint" moved-to="Sequence.range_get_midpoint" version="2.14">
|
|
<doc xml:space="preserve">Finds an iterator somewhere in the range (@begin, @end). This
|
|
iterator will be close to the middle of the range, but is not
|
|
guaranteed to be exactly in the middle.
|
|
|
|
The @begin and @end iterators must both point to the same sequence
|
|
and @begin must come before or be equal to @end in the sequence.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter pointing somewhere in the
|
|
(@begin, @end) range</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="begin" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="end" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sequence_remove" c:identifier="g_sequence_remove" moved-to="Sequence.remove" version="2.14">
|
|
<doc xml:space="preserve">Removes the item pointed to by @iter. It is an error to pass the
|
|
end iterator to this function.
|
|
|
|
If the sequence has a data destroy function associated with it, this
|
|
function is called on the data for the removed item.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sequence_remove_range" c:identifier="g_sequence_remove_range" moved-to="Sequence.remove_range" version="2.14">
|
|
<doc xml:space="preserve">Removes all items in the (@begin, @end) range.
|
|
|
|
If the sequence has a data destroy function associated with it, this
|
|
function is called on the data for the removed items.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="begin" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="end" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sequence_set" c:identifier="g_sequence_set" moved-to="Sequence.set" version="2.14">
|
|
<doc xml:space="preserve">Changes the data for the item pointed to by @iter to be @data. If
|
|
the sequence has a data destroy function associated with it, that
|
|
function is called on the existing data that @iter pointed to.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="iter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">new data for the item</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sequence_swap" c:identifier="g_sequence_swap" moved-to="Sequence.swap" version="2.14">
|
|
<doc xml:space="preserve">Swaps the items pointed to by @a and @b. It is allowed for @a and @b
|
|
to point into difference sequences.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="a" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
<parameter name="b" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSequenceIter</doc>
|
|
<type name="SequenceIter" c:type="GSequenceIter*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="set_application_name" c:identifier="g_set_application_name" version="2.2">
|
|
<doc xml:space="preserve">Sets a human-readable name for the application. This name should be
|
|
localized if possible, and is intended for display to the user.
|
|
Contrast with g_set_prgname(), which sets a non-localized name.
|
|
g_set_prgname() will be called automatically by gtk_init(),
|
|
but g_set_application_name() will not.
|
|
|
|
Note that for thread safety reasons, this function can only
|
|
be called once.
|
|
|
|
The application name will be used in contexts such as error messages,
|
|
or when displaying an application's name in the task list.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="application_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">localized name of the application</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="set_error" c:identifier="g_set_error" introspectable="0">
|
|
<doc xml:space="preserve">Does nothing if @err is %NULL; if @err is non-%NULL, then *@err
|
|
must be %NULL. A new #GError is created and assigned to *@err.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="err" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">a return location for a #GError</doc>
|
|
<type name="Error" c:type="GError**"/>
|
|
</parameter>
|
|
<parameter name="domain" transfer-ownership="none">
|
|
<doc xml:space="preserve">error domain</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</parameter>
|
|
<parameter name="code" transfer-ownership="none">
|
|
<doc xml:space="preserve">error code</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">printf()-style format</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">args for @format</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="set_error_literal" c:identifier="g_set_error_literal" version="2.18">
|
|
<doc xml:space="preserve">Does nothing if @err is %NULL; if @err is non-%NULL, then *@err
|
|
must be %NULL. A new #GError is created and assigned to *@err.
|
|
Unlike g_set_error(), @message is not a printf()-style format string.
|
|
Use this function if @message contains text you don't have control over,
|
|
that could include printf() escape sequences.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="err" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">a return location for a #GError</doc>
|
|
<type name="Error" c:type="GError**"/>
|
|
</parameter>
|
|
<parameter name="domain" transfer-ownership="none">
|
|
<doc xml:space="preserve">error domain</doc>
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</parameter>
|
|
<parameter name="code" transfer-ownership="none">
|
|
<doc xml:space="preserve">error code</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="message" transfer-ownership="none">
|
|
<doc xml:space="preserve">error message</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="set_prgname" c:identifier="g_set_prgname">
|
|
<doc xml:space="preserve">Sets the name of the program. This name should not be localized,
|
|
in contrast to g_set_application_name().
|
|
|
|
If you are using #GApplication the program name is set in
|
|
g_application_run(). In case of GDK or GTK+ it is set in
|
|
gdk_init(), which is called by gtk_init() and the
|
|
#GtkApplication::startup handler. The program name is found by
|
|
taking the last component of @argv[0].
|
|
|
|
Note that for thread-safety reasons this function can only be called once.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="prgname" transfer-ownership="none">
|
|
<doc xml:space="preserve">the name of the program.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="set_print_handler" c:identifier="g_set_print_handler" introspectable="0">
|
|
<doc xml:space="preserve">Sets the print handler.
|
|
|
|
Any messages passed to g_print() will be output via
|
|
the new handler. The default handler simply outputs
|
|
the message to stdout. By providing your own handler
|
|
you can redirect the output, to a GTK+ widget or a
|
|
log file for example.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the old print handler</doc>
|
|
<type name="PrintFunc" c:type="GPrintFunc"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<doc xml:space="preserve">the new print handler</doc>
|
|
<type name="PrintFunc" c:type="GPrintFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="set_printerr_handler" c:identifier="g_set_printerr_handler" introspectable="0">
|
|
<doc xml:space="preserve">Sets the handler for printing error messages.
|
|
|
|
Any messages passed to g_printerr() will be output via
|
|
the new handler. The default handler simply outputs the
|
|
message to stderr. By providing your own handler you can
|
|
redirect the output, to a GTK+ widget or a log file for
|
|
example.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the old error message handler</doc>
|
|
<type name="PrintFunc" c:type="GPrintFunc"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<doc xml:space="preserve">the new error message handler</doc>
|
|
<type name="PrintFunc" c:type="GPrintFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="setenv" c:identifier="g_setenv" version="2.4">
|
|
<doc xml:space="preserve">Sets an environment variable. On UNIX, both the variable's name and
|
|
value can be arbitrary byte strings, except that the variable's name
|
|
cannot contain '='. On Windows, they should be in UTF-8.
|
|
|
|
Note that on some systems, when variables are overwritten, the memory
|
|
used for the previous variables and its value isn't reclaimed.
|
|
|
|
You should be mindful of the fact that environment variable handling
|
|
in UNIX is not thread-safe, and your program may crash if one thread
|
|
calls g_setenv() while another thread is calling getenv(). (And note
|
|
that many functions, such as gettext(), call getenv() internally.)
|
|
This function is only safe to use at the very start of your program,
|
|
before creating any other threads (or creating objects that create
|
|
worker threads of their own).
|
|
|
|
If you need to set up the environment for a child process, you can
|
|
use g_get_environ() to get an environment array, modify that with
|
|
g_environ_setenv() and g_environ_unsetenv(), and then pass that
|
|
array directly to execvpe(), g_spawn_async(), or the like.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%FALSE if the environment variable couldn't be set.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="variable" transfer-ownership="none">
|
|
<doc xml:space="preserve">the environment variable to set, must not
|
|
contain '='.</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<doc xml:space="preserve">the value for to set the variable to.</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="overwrite" transfer-ownership="none">
|
|
<doc xml:space="preserve">whether to change the variable if it already exists.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="shell">
|
|
<doc xml:space="preserve">GLib provides the functions g_shell_quote() and g_shell_unquote()
|
|
to handle shell-like quoting in strings. The function g_shell_parse_argv()
|
|
parses a string similar to the way a POSIX shell (/bin/sh) would.
|
|
|
|
Note that string handling in shells has many obscure and historical
|
|
corner-cases which these functions do not necessarily reproduce. They
|
|
are good enough in practice, though.</doc>
|
|
</docsection>
|
|
<function name="shell_error_quark" c:identifier="g_shell_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="shell_parse_argv" c:identifier="g_shell_parse_argv" throws="1">
|
|
<doc xml:space="preserve">Parses a command line into an argument vector, in much the same way
|
|
the shell would, but without many of the expansions the shell would
|
|
perform (variable expansion, globs, operators, filename expansion,
|
|
etc. are not supported). The results are defined to be the same as
|
|
those you would get from a UNIX98 /bin/sh, as long as the input
|
|
contains none of the unsupported shell expansions. If the input
|
|
does contain such expansions, they are passed through
|
|
literally. Possible errors are those from the #G_SHELL_ERROR
|
|
domain. Free the returned vector with g_strfreev().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on success, %FALSE if error set</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="command_line" transfer-ownership="none">
|
|
<doc xml:space="preserve">command line to parse</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="argcp" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for number of args</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="argvp" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">
|
|
return location for array of args</doc>
|
|
<array length="1" zero-terminated="1" c:type="gchar***">
|
|
<type name="filename"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="shell_quote" c:identifier="g_shell_quote">
|
|
<doc xml:space="preserve">Quotes a string so that the shell (/bin/sh) will interpret the
|
|
quoted string to mean @unquoted_string. If you pass a filename to
|
|
the shell, for example, you should first quote it with this
|
|
function. The return value must be freed with g_free(). The
|
|
quoting style used is undefined (single or double quotes may be
|
|
used).</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">quoted string</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="unquoted_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a literal string</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="shell_unquote" c:identifier="g_shell_unquote" throws="1">
|
|
<doc xml:space="preserve">Unquotes a string as the shell (/bin/sh) would. Only handles
|
|
quotes; if a string contains file globs, arithmetic operators,
|
|
variables, backticks, redirections, or other special-to-the-shell
|
|
features, the result will be different from the result a real shell
|
|
would produce (the variables, backticks, etc. will be passed
|
|
through literally instead of being expanded). This function is
|
|
guaranteed to succeed if applied to the result of
|
|
g_shell_quote(). If it fails, it returns %NULL and sets the
|
|
error. The @quoted_string need not actually contain quoted or
|
|
escaped text; g_shell_unquote() simply goes through the string and
|
|
unquotes/unescapes anything that the shell would. Both single and
|
|
double quotes are handled, as are escapes including escaped
|
|
newlines. The return value must be freed with g_free(). Possible
|
|
errors are in the #G_SHELL_ERROR domain.
|
|
|
|
Shell quoting rules are a bit strange. Single quotes preserve the
|
|
literal string exactly. escape sequences are not allowed; not even
|
|
\' - if you want a ' in the quoted text, you have to do something
|
|
like 'foo'\''bar'. Double quotes allow $, `, ", \, and newline to
|
|
be escaped with backslash. Otherwise double quotes preserve things
|
|
literally.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an unquoted string</doc>
|
|
<type name="filename" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="quoted_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">shell-quoted string</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="size_checked_add" c:identifier="g_size_checked_add" version="2.48" introspectable="0">
|
|
<doc xml:space="preserve">Performs a checked addition of @a and @b, storing the result in
|
|
@dest.
|
|
|
|
If the operation is successful, %TRUE is returned. If the operation
|
|
overflows then the state of @dest is undefined and %FALSE is
|
|
returned.</doc>
|
|
<parameters>
|
|
<parameter name="dest">
|
|
<doc xml:space="preserve">a pointer to the #gsize destination</doc>
|
|
</parameter>
|
|
<parameter name="a">
|
|
<doc xml:space="preserve">the #gsize left operand</doc>
|
|
</parameter>
|
|
<parameter name="b">
|
|
<doc xml:space="preserve">the #gsize right operand</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="size_checked_mul" c:identifier="g_size_checked_mul" version="2.48" introspectable="0">
|
|
<doc xml:space="preserve">Performs a checked multiplication of @a and @b, storing the result in
|
|
@dest.
|
|
|
|
If the operation is successful, %TRUE is returned. If the operation
|
|
overflows then the state of @dest is undefined and %FALSE is
|
|
returned.</doc>
|
|
<parameters>
|
|
<parameter name="dest">
|
|
<doc xml:space="preserve">a pointer to the #gsize destination</doc>
|
|
</parameter>
|
|
<parameter name="a">
|
|
<doc xml:space="preserve">the #gsize left operand</doc>
|
|
</parameter>
|
|
<parameter name="b">
|
|
<doc xml:space="preserve">the #gsize right operand</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="slice_alloc" c:identifier="g_slice_alloc" version="2.10">
|
|
<doc xml:space="preserve">Allocates a block of memory from the slice allocator.
|
|
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,
|
|
the alignment may be reduced in a libc dependent fashion.
|
|
Note that the underlying slice allocation mechanism can
|
|
be changed with the [`G_SLICE=always-malloc`][G_SLICE]
|
|
environment variable.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">a pointer to the allocated memory block, which will be %NULL if and
|
|
only if @mem_size is 0</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="block_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes to allocate</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="slice_alloc0" c:identifier="g_slice_alloc0" version="2.10">
|
|
<doc xml:space="preserve">Allocates a block of memory via g_slice_alloc() and initializes
|
|
the returned memory to 0. Note that the underlying slice allocation
|
|
mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE]
|
|
environment variable.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">a pointer to the allocated block, which will be %NULL if and only
|
|
if @mem_size is 0</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="block_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes to allocate</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="slice_copy" c:identifier="g_slice_copy" version="2.14">
|
|
<doc xml:space="preserve">Allocates a block of memory from the slice allocator
|
|
and copies @block_size bytes into it from @mem_block.
|
|
|
|
@mem_block must be non-%NULL if @block_size is non-zero.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">a pointer to the allocated memory block, which will be %NULL if and
|
|
only if @mem_size is 0</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="block_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes to allocate</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="mem_block" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the memory to copy</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="slice_dup" c:identifier="g_slice_dup" version="2.14" introspectable="0">
|
|
<doc xml:space="preserve">A convenience macro to duplicate a block of memory using
|
|
the slice allocator.
|
|
|
|
It calls g_slice_copy() with `sizeof (@type)`
|
|
and casts the returned pointer to a pointer of the given type,
|
|
avoiding a type cast in the source code.
|
|
Note that the underlying slice allocation mechanism can
|
|
be changed with the [`G_SLICE=always-malloc`][G_SLICE]
|
|
environment variable.
|
|
|
|
This can never return %NULL.</doc>
|
|
<parameters>
|
|
<parameter name="type">
|
|
<doc xml:space="preserve">the type to duplicate, typically a structure name</doc>
|
|
</parameter>
|
|
<parameter name="mem">
|
|
<doc xml:space="preserve">the memory to copy into the allocated block</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="slice_free" c:identifier="g_slice_free" version="2.10" introspectable="0">
|
|
<doc xml:space="preserve">A convenience macro to free a block of memory that has
|
|
been allocated from the slice allocator.
|
|
|
|
It calls g_slice_free1() using `sizeof (type)`
|
|
as the block size.
|
|
Note that the exact release behaviour can be changed with the
|
|
[`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see
|
|
[`G_SLICE`][G_SLICE] for related debugging options.
|
|
|
|
If @mem is %NULL, this macro does nothing.</doc>
|
|
<parameters>
|
|
<parameter name="type">
|
|
<doc xml:space="preserve">the type of the block to free, typically a structure name</doc>
|
|
</parameter>
|
|
<parameter name="mem">
|
|
<doc xml:space="preserve">a pointer to the block to free</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="slice_free1" c:identifier="g_slice_free1" version="2.10">
|
|
<doc xml:space="preserve">Frees a block of memory.
|
|
|
|
The memory must have been allocated via g_slice_alloc() or
|
|
g_slice_alloc0() and the @block_size has to match the size
|
|
specified upon allocation. Note that the exact release behaviour
|
|
can be changed with the [`G_DEBUG=gc-friendly`][G_DEBUG] environment
|
|
variable, also see [`G_SLICE`][G_SLICE] for related debugging options.
|
|
|
|
If @mem_block is %NULL, this function does nothing.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="block_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of the block</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="mem_block" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a pointer to the block to free</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="slice_free_chain" c:identifier="g_slice_free_chain" version="2.10" introspectable="0">
|
|
<doc xml:space="preserve">Frees a linked list of memory blocks of structure type @type.
|
|
The memory blocks must be equal-sized, allocated via
|
|
g_slice_alloc() or g_slice_alloc0() and linked together by
|
|
a @next pointer (similar to #GSList). The name of the
|
|
@next field in @type is passed as third argument.
|
|
Note that the exact release behaviour can be changed with the
|
|
[`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see
|
|
[`G_SLICE`][G_SLICE] for related debugging options.
|
|
|
|
If @mem_chain is %NULL, this function does nothing.</doc>
|
|
<parameters>
|
|
<parameter name="type">
|
|
<doc xml:space="preserve">the type of the @mem_chain blocks</doc>
|
|
</parameter>
|
|
<parameter name="mem_chain">
|
|
<doc xml:space="preserve">a pointer to the first block of the chain</doc>
|
|
</parameter>
|
|
<parameter name="next">
|
|
<doc xml:space="preserve">the field name of the next pointer in @type</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="slice_free_chain_with_offset" c:identifier="g_slice_free_chain_with_offset" version="2.10">
|
|
<doc xml:space="preserve">Frees a linked list of memory blocks of structure type @type.
|
|
|
|
The memory blocks must be equal-sized, allocated via
|
|
g_slice_alloc() or g_slice_alloc0() and linked together by a
|
|
@next pointer (similar to #GSList). The offset of the @next
|
|
field in each block is passed as third argument.
|
|
Note that the exact release behaviour can be changed with the
|
|
[`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see
|
|
[`G_SLICE`][G_SLICE] for related debugging options.
|
|
|
|
If @mem_chain is %NULL, this function does nothing.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="block_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of the blocks</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="mem_chain" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a pointer to the first block of the chain</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="next_offset" transfer-ownership="none">
|
|
<doc xml:space="preserve">the offset of the @next field in the blocks</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="slice_get_config" c:identifier="g_slice_get_config">
|
|
<return-value transfer-ownership="none">
|
|
<type name="gint64" c:type="gint64"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="ckey" transfer-ownership="none">
|
|
<type name="SliceConfig" c:type="GSliceConfig"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="slice_get_config_state" c:identifier="g_slice_get_config_state">
|
|
<return-value transfer-ownership="none">
|
|
<type name="gint64" c:type="gint64*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="ckey" transfer-ownership="none">
|
|
<type name="SliceConfig" c:type="GSliceConfig"/>
|
|
</parameter>
|
|
<parameter name="address" transfer-ownership="none">
|
|
<type name="gint64" c:type="gint64"/>
|
|
</parameter>
|
|
<parameter name="n_values" transfer-ownership="none">
|
|
<type name="guint" c:type="guint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="slice_new" c:identifier="g_slice_new" version="2.10" introspectable="0">
|
|
<doc xml:space="preserve">A convenience macro to allocate a block of memory from the
|
|
slice allocator.
|
|
|
|
It calls g_slice_alloc() with `sizeof (@type)` and casts the
|
|
returned pointer to a pointer of the given type, avoiding a type
|
|
cast in the source code. Note that the underlying slice allocation
|
|
mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE]
|
|
environment variable.
|
|
|
|
This can never return %NULL as the minimum allocation size from
|
|
`sizeof (@type)` is 1 byte.</doc>
|
|
<parameters>
|
|
<parameter name="type">
|
|
<doc xml:space="preserve">the type to allocate, typically a structure name</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="slice_new0" c:identifier="g_slice_new0" version="2.10" introspectable="0">
|
|
<doc xml:space="preserve">A convenience macro to allocate a block of memory from the
|
|
slice allocator and set the memory to 0.
|
|
|
|
It calls g_slice_alloc0() with `sizeof (@type)`
|
|
and casts the returned pointer to a pointer of the given type,
|
|
avoiding a type cast in the source code.
|
|
Note that the underlying slice allocation mechanism can
|
|
be changed with the [`G_SLICE=always-malloc`][G_SLICE]
|
|
environment variable.
|
|
|
|
This can never return %NULL as the minimum allocation size from
|
|
`sizeof (@type)` is 1 byte.</doc>
|
|
<parameters>
|
|
<parameter name="type">
|
|
<doc xml:space="preserve">the type to allocate, typically a structure name</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="slice_set_config" c:identifier="g_slice_set_config">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="ckey" transfer-ownership="none">
|
|
<type name="SliceConfig" c:type="GSliceConfig"/>
|
|
</parameter>
|
|
<parameter name="value" transfer-ownership="none">
|
|
<type name="gint64" c:type="gint64"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="slist_next" c:identifier="g_slist_next" introspectable="0">
|
|
<doc xml:space="preserve">A convenience macro to get the next element in a #GSList.
|
|
Note that it is considered perfectly acceptable to access
|
|
@slist->next directly.</doc>
|
|
<parameters>
|
|
<parameter name="slist">
|
|
<doc xml:space="preserve">an element in a #GSList.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="snprintf" c:identifier="g_snprintf" introspectable="0">
|
|
<doc xml:space="preserve">A safer form of the standard sprintf() function. The output is guaranteed
|
|
to not exceed @n characters (including the terminating nul character), so
|
|
it is easy to ensure that a buffer overflow cannot occur.
|
|
|
|
See also g_strdup_printf().
|
|
|
|
In versions of GLib prior to 1.2.3, this function may return -1 if the
|
|
output was truncated, and the truncated string may not be nul-terminated.
|
|
In versions prior to 1.3.12, this function returns the length of the output
|
|
string.
|
|
|
|
The return value of g_snprintf() conforms to the snprintf()
|
|
function as standardized in ISO C99. Note that this is different from
|
|
traditional snprintf(), which returns the length of the output string.
|
|
|
|
The format string may contain positional parameters, as specified in
|
|
the Single Unix Specification.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes which would be produced if the buffer
|
|
was large enough.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the buffer to hold the output.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum number of bytes to produce (including the
|
|
terminating nul character).</doc>
|
|
<type name="gulong" c:type="gulong"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">a standard printf() format string, but notice
|
|
[string precision pitfalls][string-precision]</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">the arguments to insert in the output.</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="source_remove" c:identifier="g_source_remove" moved-to="Source.remove">
|
|
<doc xml:space="preserve">Removes the source with the given ID from the default main context. You must
|
|
use g_source_destroy() for sources added to a non-default main context.
|
|
|
|
The ID of a #GSource is given by g_source_get_id(), or will be
|
|
returned by the functions g_source_attach(), g_idle_add(),
|
|
g_idle_add_full(), g_timeout_add(), g_timeout_add_full(),
|
|
g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and
|
|
g_io_add_watch_full().
|
|
|
|
It is a programmer error to attempt to remove a non-existent source.
|
|
|
|
More specifically: source IDs can be reissued after a source has been
|
|
destroyed and therefore it is never valid to use this function with a
|
|
source ID which may have already been removed. An example is when
|
|
scheduling an idle to run in another thread with g_idle_add(): the
|
|
idle may already have run and been removed by the time this function
|
|
is called on its (now invalid) source ID. This source ID may have
|
|
been reissued, leading to the operation being performed against the
|
|
wrong source.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">For historical reasons, this function always returns %TRUE</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="tag" transfer-ownership="none">
|
|
<doc xml:space="preserve">the ID of the source to remove.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="source_remove_by_funcs_user_data" c:identifier="g_source_remove_by_funcs_user_data" moved-to="Source.remove_by_funcs_user_data">
|
|
<doc xml:space="preserve">Removes a source from the default main loop context given the
|
|
source functions and user data. If multiple sources exist with the
|
|
same source functions and user data, only one will be destroyed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a source was found and removed.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="funcs" transfer-ownership="none">
|
|
<doc xml:space="preserve">The @source_funcs passed to g_source_new()</doc>
|
|
<type name="SourceFuncs" c:type="GSourceFuncs*"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the user data for the callback</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="source_remove_by_user_data" c:identifier="g_source_remove_by_user_data" moved-to="Source.remove_by_user_data">
|
|
<doc xml:space="preserve">Removes a source from the default main loop context given the user
|
|
data for the callback. If multiple sources exist with the same user
|
|
data, only one will be destroyed.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a source was found and removed.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the user_data for the callback.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="source_set_name_by_id" c:identifier="g_source_set_name_by_id" moved-to="Source.set_name_by_id" version="2.26">
|
|
<doc xml:space="preserve">Sets the name of a source using its ID.
|
|
|
|
This is a convenience utility to set source names from the return
|
|
value of g_idle_add(), g_timeout_add(), etc.
|
|
|
|
It is a programmer error to attempt to set the name of a non-existent
|
|
source.
|
|
|
|
More specifically: source IDs can be reissued after a source has been
|
|
destroyed and therefore it is never valid to use this function with a
|
|
source ID which may have already been removed. An example is when
|
|
scheduling an idle to run in another thread with g_idle_add(): the
|
|
idle may already have run and been removed by the time this function
|
|
is called on its (now invalid) source ID. This source ID may have
|
|
been reissued, leading to the operation being performed against the
|
|
wrong source.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="tag" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GSource ID</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="name" transfer-ownership="none">
|
|
<doc xml:space="preserve">debug name for the source</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="spaced_primes_closest" c:identifier="g_spaced_primes_closest">
|
|
<doc xml:space="preserve">Gets the smallest prime number from a built-in array of primes which
|
|
is larger than @num. This is used within GLib to calculate the optimum
|
|
size of a #GHashTable.
|
|
|
|
The built-in array of primes ranges from 11 to 13845163 such that
|
|
each prime is approximately 1.5-2 times the previous prime.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the smallest prime number from a built-in array of primes
|
|
which is larger than @num</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="num" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #guint</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="spawn">
|
|
<doc xml:space="preserve">GLib supports spawning of processes with an API that is more
|
|
convenient than the bare UNIX fork() and exec().
|
|
|
|
The g_spawn family of functions has synchronous (g_spawn_sync())
|
|
and asynchronous variants (g_spawn_async(), g_spawn_async_with_pipes()),
|
|
as well as convenience variants that take a complete shell-like
|
|
commandline (g_spawn_command_line_sync(), g_spawn_command_line_async()).
|
|
|
|
See #GSubprocess in GIO for a higher-level API that provides
|
|
stream interfaces for communication with child processes.
|
|
|
|
An example of using g_spawn_async_with_pipes():
|
|
|[<!-- language="C" -->
|
|
const gchar * const argv[] = { "my-favourite-program", "--args", NULL };
|
|
gint child_stdout, child_stderr;
|
|
GPid child_pid;
|
|
g_autoptr(GError) error = NULL;
|
|
|
|
// Spawn child process.
|
|
g_spawn_async_with_pipes (NULL, argv, NULL, G_SPAWN_DO_NOT_REAP_CHILD, NULL,
|
|
NULL, &child_pid, NULL, &child_stdout,
|
|
&child_stderr, &error);
|
|
if (error != NULL)
|
|
{
|
|
g_error ("Spawning child failed: %s", error->message);
|
|
return;
|
|
}
|
|
|
|
// Add a child watch function which will be called when the child process
|
|
// exits.
|
|
g_child_watch_add (child_pid, child_watch_cb, NULL);
|
|
|
|
// You could watch for output on @child_stdout and @child_stderr using
|
|
// #GUnixInputStream or #GIOChannel here.
|
|
|
|
static void
|
|
child_watch_cb (GPid pid,
|
|
gint status,
|
|
gpointer user_data)
|
|
{
|
|
g_message ("Child %" G_PID_FORMAT " exited %s", pid,
|
|
g_spawn_check_exit_status (status, NULL) ? "normally" : "abnormally");
|
|
|
|
// Free any resources associated with the child here, such as I/O channels
|
|
// on its stdout and stderr FDs. If you have no code to put in the
|
|
// child_watch_cb() callback, you can remove it and the g_child_watch_add()
|
|
// call, but you must also remove the G_SPAWN_DO_NOT_REAP_CHILD flag,
|
|
// otherwise the child process will stay around as a zombie until this
|
|
// process exits.
|
|
|
|
g_spawn_close_pid (pid);
|
|
}
|
|
]|</doc>
|
|
</docsection>
|
|
<function name="spawn_async" c:identifier="g_spawn_async" throws="1">
|
|
<doc xml:space="preserve">See g_spawn_async_with_pipes() for a full description; this function
|
|
simply calls the g_spawn_async_with_pipes() without any pipes.
|
|
|
|
You should call g_spawn_close_pid() on the returned child process
|
|
reference when you don't need it any more.
|
|
|
|
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.
|
|
|
|
Note that the returned @child_pid on Windows is a handle to the child
|
|
process and not its identifier. Process handles and process identifiers
|
|
are different concepts on Windows.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on success, %FALSE if error is set</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="working_directory" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">child's current working
|
|
directory, or %NULL to inherit parent's</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="argv" transfer-ownership="none">
|
|
<doc xml:space="preserve">
|
|
child's argument vector</doc>
|
|
<array c:type="gchar**">
|
|
<type name="filename"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="envp" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">
|
|
child's environment, or %NULL to inherit parent's</doc>
|
|
<array c:type="gchar**">
|
|
<type name="filename"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags from #GSpawnFlags</doc>
|
|
<type name="SpawnFlags" c:type="GSpawnFlags"/>
|
|
</parameter>
|
|
<parameter name="child_setup" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5">
|
|
<doc xml:space="preserve">function to run in the child just before exec()</doc>
|
|
<type name="SpawnChildSetupFunc" c:type="GSpawnChildSetupFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data for @child_setup</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="child_pid" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for child process reference, or %NULL</doc>
|
|
<type name="Pid" c:type="GPid*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="spawn_async_with_fds" c:identifier="g_spawn_async_with_fds" version="2.58" throws="1">
|
|
<doc xml:space="preserve">Identical to g_spawn_async_with_pipes() but instead of
|
|
creating pipes for the stdin/stdout/stderr, you can pass existing
|
|
file descriptors into this function through the @stdin_fd,
|
|
@stdout_fd and @stderr_fd parameters. The following @flags
|
|
also have their behaviour slightly tweaked as a result:
|
|
|
|
%G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output
|
|
will be discarded, instead of going to the same location as the parent's
|
|
standard output. If you use this flag, @standard_output must be -1.
|
|
%G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error
|
|
will be discarded, instead of going to the same location as the parent's
|
|
standard error. If you use this flag, @standard_error must be -1.
|
|
%G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's
|
|
standard input (by default, the child's standard input is attached to
|
|
/dev/null). If you use this flag, @standard_input must be -1.
|
|
|
|
It is valid to pass the same fd in multiple parameters (e.g. you can pass
|
|
a single fd for both stdout and stderr).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on success, %FALSE if an error was set</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="working_directory" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="argv" transfer-ownership="none">
|
|
<doc xml:space="preserve">child's argument vector, in the GLib file name encoding</doc>
|
|
<array c:type="gchar**">
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="envp" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">child's environment, or %NULL to inherit parent's, in the GLib file name encoding</doc>
|
|
<array c:type="gchar**">
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags from #GSpawnFlags</doc>
|
|
<type name="SpawnFlags" c:type="GSpawnFlags"/>
|
|
</parameter>
|
|
<parameter name="child_setup" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5">
|
|
<doc xml:space="preserve">function to run in the child just before exec()</doc>
|
|
<type name="SpawnChildSetupFunc" c:type="GSpawnChildSetupFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data for @child_setup</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="child_pid" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for child process ID, or %NULL</doc>
|
|
<type name="Pid" c:type="GPid*"/>
|
|
</parameter>
|
|
<parameter name="stdin_fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">file descriptor to use for child's stdin, or -1</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="stdout_fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">file descriptor to use for child's stdout, or -1</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="stderr_fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">file descriptor to use for child's stderr, or -1</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="spawn_async_with_pipes" c:identifier="g_spawn_async_with_pipes" throws="1">
|
|
<doc xml:space="preserve">Executes a child program asynchronously (your program will not
|
|
block waiting for the child to exit). The child program is
|
|
specified by the only argument that must be provided, @argv.
|
|
@argv should be a %NULL-terminated array of strings, to be passed
|
|
as the argument vector for the child. The first string in @argv
|
|
is of course the name of the program to execute. By default, the
|
|
name of the program must be a full path. If @flags contains the
|
|
%G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is
|
|
used to search for the executable. If @flags contains the
|
|
%G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from
|
|
@envp is used to search for the executable. If both the
|
|
%G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags
|
|
are set, the `PATH` variable from @envp takes precedence over
|
|
the environment variable.
|
|
|
|
If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not
|
|
used, then the program will be run from the current directory (or
|
|
@working_directory, if specified); this might be unexpected or even
|
|
dangerous in some cases when the current directory is world-writable.
|
|
|
|
On Windows, note that all the string or string vector arguments to
|
|
this function and the other g_spawn*() functions are in UTF-8, the
|
|
GLib file name encoding. Unicode characters that are not part of
|
|
the system codepage passed in these arguments will be correctly
|
|
available in the spawned program only if it uses wide character API
|
|
to retrieve its command line. For C programs built with Microsoft's
|
|
tools it is enough to make the program have a wmain() instead of
|
|
main(). wmain() has a wide character argument vector as parameter.
|
|
|
|
At least currently, mingw doesn't support wmain(), so if you use
|
|
mingw to develop the spawned program, it should call
|
|
g_win32_get_command_line() to get arguments in UTF-8.
|
|
|
|
On Windows the low-level child process creation API CreateProcess()
|
|
doesn't use argument vectors, but a command line. The C runtime
|
|
library's spawn*() family of functions (which g_spawn_async_with_pipes()
|
|
eventually calls) paste the argument vector elements together into
|
|
a command line, and the C runtime startup code does a corresponding
|
|
reconstruction of an argument vector from the command line, to be
|
|
passed to main(). Complications arise when you have argument vector
|
|
elements that contain spaces or double quotes. The `spawn*()` functions
|
|
don't do any quoting or escaping, but on the other hand the startup
|
|
code does do unquoting and unescaping in order to enable receiving
|
|
arguments with embedded spaces or double quotes. To work around this
|
|
asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on
|
|
argument vector elements that need it before calling the C runtime
|
|
spawn() function.
|
|
|
|
The returned @child_pid on Windows is a handle to the child
|
|
process, not its identifier. Process handles and process
|
|
identifiers are different concepts on Windows.
|
|
|
|
@envp is a %NULL-terminated array of strings, where each string
|
|
has the form `KEY=VALUE`. This will become the child's environment.
|
|
If @envp is %NULL, the child inherits its parent's environment.
|
|
|
|
@flags should be the bitwise OR of any flags you want to affect the
|
|
function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the
|
|
child will not automatically be reaped; you must use a child watch
|
|
(g_child_watch_add()) to be notified about the death of the child process,
|
|
otherwise it will stay around as a zombie process until this process exits.
|
|
Eventually you must call g_spawn_close_pid() on the @child_pid, in order to
|
|
free resources which may be associated with the child process. (On Unix,
|
|
using a child watch is equivalent to calling waitpid() or handling
|
|
the %SIGCHLD signal manually. On Windows, calling g_spawn_close_pid()
|
|
is equivalent to calling CloseHandle() on the process handle returned
|
|
in @child_pid). See g_child_watch_add().
|
|
|
|
Open UNIX file descriptors marked as `FD_CLOEXEC` will be automatically
|
|
closed in the child process. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that
|
|
other open file descriptors will be inherited by the child; otherwise all
|
|
descriptors except stdin/stdout/stderr will be closed before calling exec()
|
|
in the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an
|
|
absolute path, it will be looked for in the `PATH` environment
|
|
variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an
|
|
absolute path, it will be looked for in the `PATH` variable from
|
|
@envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP
|
|
are used, the value from @envp takes precedence over the environment.
|
|
%G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output
|
|
will be discarded, instead of going to the same location as the parent's
|
|
standard output. If you use this flag, @standard_output must be %NULL.
|
|
%G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error
|
|
will be discarded, instead of going to the same location as the parent's
|
|
standard error. If you use this flag, @standard_error must be %NULL.
|
|
%G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's
|
|
standard input (by default, the child's standard input is attached to
|
|
`/dev/null`). If you use this flag, @standard_input must be %NULL.
|
|
%G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is
|
|
the file to execute, while the remaining elements are the actual
|
|
argument vector to pass to the file. Normally g_spawn_async_with_pipes()
|
|
uses @argv[0] as the file to execute, and passes all of @argv to the child.
|
|
|
|
@child_setup and @user_data are a function and user data. On POSIX
|
|
platforms, the function is called in the child after GLib has
|
|
performed all the setup it plans to perform (including creating
|
|
pipes, closing file descriptors, etc.) but before calling exec().
|
|
That is, @child_setup is called just before calling exec() in the
|
|
child. Obviously actions taken in this function will only affect
|
|
the child, not the parent.
|
|
|
|
On Windows, there is no separate fork() and exec() functionality.
|
|
Child processes are created and run with a single API call,
|
|
CreateProcess(). There is no sensible thing @child_setup
|
|
could be used for on Windows so it is ignored and not called.
|
|
|
|
If non-%NULL, @child_pid will on Unix be filled with the child's
|
|
process ID. You can use the process ID to send signals to the child,
|
|
or to use g_child_watch_add() (or waitpid()) if you specified the
|
|
%G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be
|
|
filled with a handle to the child process only if you specified the
|
|
%G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child
|
|
process using the Win32 API, for example wait for its termination
|
|
with the WaitFor*() functions, or examine its exit code with
|
|
GetExitCodeProcess(). You should close the handle with CloseHandle()
|
|
or g_spawn_close_pid() when you no longer need it.
|
|
|
|
If non-%NULL, the @standard_input, @standard_output, @standard_error
|
|
locations will be filled with file descriptors for writing to the child's
|
|
standard input or reading from its standard output or standard error.
|
|
The caller of g_spawn_async_with_pipes() must close these file descriptors
|
|
when they are no longer in use. If these parameters are %NULL, the
|
|
corresponding pipe won't be created.
|
|
|
|
If @standard_input is %NULL, the child's standard input is attached to
|
|
`/dev/null` unless %G_SPAWN_CHILD_INHERITS_STDIN is set.
|
|
|
|
If @standard_error is NULL, the child's standard error goes to the same
|
|
location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL
|
|
is set.
|
|
|
|
If @standard_output is NULL, the child's standard output goes to the same
|
|
location as the parent's standard output unless %G_SPAWN_STDOUT_TO_DEV_NULL
|
|
is set.
|
|
|
|
@error can be %NULL to ignore errors, or non-%NULL to report errors.
|
|
If an error is set, the function returns %FALSE. Errors are reported
|
|
even if they occur in the child (for example if the executable in
|
|
@argv[0] is not found). Typically the `message` field of returned
|
|
errors should be displayed to users. Possible errors are those from
|
|
the #G_SPAWN_ERROR domain.
|
|
|
|
If an error occurs, @child_pid, @standard_input, @standard_output,
|
|
and @standard_error will not be filled with valid values.
|
|
|
|
If @child_pid is not %NULL and an error does not occur then the returned
|
|
process reference must be closed using g_spawn_close_pid().
|
|
|
|
On modern UNIX platforms, GLib can use an efficient process launching
|
|
codepath driven internally by posix_spawn(). This has the advantage of
|
|
avoiding the fork-time performance costs of cloning the parent process
|
|
address space, and avoiding associated memory overcommit checks that are
|
|
not relevant in the context of immediately executing a distinct process.
|
|
This optimized codepath will be used provided that the following conditions
|
|
are met:
|
|
|
|
1. %G_SPAWN_DO_NOT_REAP_CHILD is set
|
|
2. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN is set
|
|
3. %G_SPAWN_SEARCH_PATH_FROM_ENVP is not set
|
|
4. @working_directory is %NULL
|
|
5. @child_setup is %NULL
|
|
6. The program is of a recognised binary format, or has a shebang. Otherwise, GLib will have to execute the program through the shell, which is not done using the optimized codepath.
|
|
|
|
If you are writing a GTK+ application, and the program you are spawning is a
|
|
graphical application too, then to ensure that the spawned program opens its
|
|
windows on the right screen, you may want to use #GdkAppLaunchContext,
|
|
#GAppLaunchContext, or set the %DISPLAY environment variable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on success, %FALSE if an error was set</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="working_directory" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">child's current working
|
|
directory, or %NULL to inherit parent's, in the GLib file name encoding</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="argv" transfer-ownership="none">
|
|
<doc xml:space="preserve">child's argument
|
|
vector, in the GLib file name encoding</doc>
|
|
<array c:type="gchar**">
|
|
<type name="filename"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="envp" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">
|
|
child's environment, or %NULL to inherit parent's, in the GLib file
|
|
name encoding</doc>
|
|
<array c:type="gchar**">
|
|
<type name="filename"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags from #GSpawnFlags</doc>
|
|
<type name="SpawnFlags" c:type="GSpawnFlags"/>
|
|
</parameter>
|
|
<parameter name="child_setup" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5">
|
|
<doc xml:space="preserve">function to run in the child just before exec()</doc>
|
|
<type name="SpawnChildSetupFunc" c:type="GSpawnChildSetupFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data for @child_setup</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="child_pid" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for child process ID, or %NULL</doc>
|
|
<type name="Pid" c:type="GPid*"/>
|
|
</parameter>
|
|
<parameter name="standard_input" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for file descriptor to write to child's stdin, or %NULL</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="standard_output" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for file descriptor to read child's stdout, or %NULL</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="standard_error" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for file descriptor to read child's stderr, or %NULL</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="spawn_check_exit_status" c:identifier="g_spawn_check_exit_status" version="2.34" throws="1">
|
|
<doc xml:space="preserve">Set @error if @exit_status indicates the child exited abnormally
|
|
(e.g. with a nonzero exit code, or via a fatal signal).
|
|
|
|
The g_spawn_sync() and g_child_watch_add() family of APIs return an
|
|
exit status for subprocesses encoded in a platform-specific way.
|
|
On Unix, this is guaranteed to be in the same format waitpid() returns,
|
|
and on Windows it is guaranteed to be the result of GetExitCodeProcess().
|
|
|
|
Prior to the introduction of this function in GLib 2.34, interpreting
|
|
@exit_status required use of platform-specific APIs, which is problematic
|
|
for software using GLib as a cross-platform layer.
|
|
|
|
Additionally, many programs simply want to determine whether or not
|
|
the child exited successfully, and either propagate a #GError or
|
|
print a message to standard error. In that common case, this function
|
|
can be used. Note that the error message in @error will contain
|
|
human-readable information about the exit status.
|
|
|
|
The @domain and @code of @error have special semantics in the case
|
|
where the process has an "exit code", as opposed to being killed by
|
|
a signal. On Unix, this happens if WIFEXITED() would be true of
|
|
@exit_status. On Windows, it is always the case.
|
|
|
|
The special semantics are that the actual exit code will be the
|
|
code set in @error, and the domain will be %G_SPAWN_EXIT_ERROR.
|
|
This allows you to differentiate between different exit codes.
|
|
|
|
If the process was terminated by some means other than an exit
|
|
status, the domain will be %G_SPAWN_ERROR, and the code will be
|
|
%G_SPAWN_ERROR_FAILED.
|
|
|
|
This function just offers convenience; you can of course also check
|
|
the available platform via a macro such as %G_OS_UNIX, and use
|
|
WIFEXITED() and WEXITSTATUS() on @exit_status directly. Do not attempt
|
|
to scan or parse the error message string; it may be translated and/or
|
|
change in future versions of GLib.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if child exited successfully, %FALSE otherwise (and
|
|
@error will be set)</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="exit_status" transfer-ownership="none">
|
|
<doc xml:space="preserve">An exit code as returned from g_spawn_sync()</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="spawn_close_pid" c:identifier="g_spawn_close_pid">
|
|
<doc xml:space="preserve">On some platforms, notably Windows, the #GPid type represents a resource
|
|
which must be closed to prevent resource leaking. g_spawn_close_pid()
|
|
is provided for this purpose. It should be used on all platforms, even
|
|
though it doesn't do anything under UNIX.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="pid" transfer-ownership="none">
|
|
<doc xml:space="preserve">The process reference to close</doc>
|
|
<type name="Pid" c:type="GPid"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="spawn_command_line_async" c:identifier="g_spawn_command_line_async" throws="1">
|
|
<doc xml:space="preserve">A simple version of g_spawn_async() that parses a command line with
|
|
g_shell_parse_argv() and passes it to g_spawn_async(). Runs a
|
|
command line in the background. Unlike g_spawn_async(), the
|
|
%G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note
|
|
that %G_SPAWN_SEARCH_PATH can have security implications, so
|
|
consider using g_spawn_async() directly if appropriate. Possible
|
|
errors are those from g_shell_parse_argv() and g_spawn_async().
|
|
|
|
The same concerns on Windows apply as for g_spawn_command_line_sync().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on success, %FALSE if error is set</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="command_line" transfer-ownership="none">
|
|
<doc xml:space="preserve">a command line</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="spawn_command_line_sync" c:identifier="g_spawn_command_line_sync" throws="1">
|
|
<doc xml:space="preserve">A simple version of g_spawn_sync() with little-used parameters
|
|
removed, taking a command line instead of an argument vector. See
|
|
g_spawn_sync() for full details. @command_line will be parsed by
|
|
g_shell_parse_argv(). Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag
|
|
is enabled. Note that %G_SPAWN_SEARCH_PATH can have security
|
|
implications, so consider using g_spawn_sync() directly if
|
|
appropriate. Possible errors are those from g_spawn_sync() and those
|
|
from g_shell_parse_argv().
|
|
|
|
If @exit_status is non-%NULL, the platform-specific exit status of
|
|
the child is stored there; see the documentation of
|
|
g_spawn_check_exit_status() for how to use and interpret this.
|
|
|
|
On Windows, please note the implications of g_shell_parse_argv()
|
|
parsing @command_line. Parsing is done according to Unix shell rules, not
|
|
Windows command interpreter rules.
|
|
Space is a separator, and backslashes are
|
|
special. Thus you cannot simply pass a @command_line containing
|
|
canonical Windows paths, like "c:\\program files\\app\\app.exe", as
|
|
the backslashes will be eaten, and the space will act as a
|
|
separator. You need to enclose such paths with single quotes, like
|
|
"'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'".</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on success, %FALSE if an error was set</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="command_line" transfer-ownership="none">
|
|
<doc xml:space="preserve">a command line</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="standard_output" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for child output</doc>
|
|
<array c:type="gchar**">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="standard_error" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for child errors</doc>
|
|
<array c:type="gchar**">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="exit_status" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for child exit status, as returned by waitpid()</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="spawn_error_quark" c:identifier="g_spawn_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="spawn_exit_error_quark" c:identifier="g_spawn_exit_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="spawn_sync" c:identifier="g_spawn_sync" throws="1">
|
|
<doc xml:space="preserve">Executes a child synchronously (waits for the child to exit before returning).
|
|
All output from the child is stored in @standard_output and @standard_error,
|
|
if those parameters are non-%NULL. Note that you must set the
|
|
%G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when
|
|
passing %NULL for @standard_output and @standard_error.
|
|
|
|
If @exit_status is non-%NULL, the platform-specific exit status of
|
|
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, 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.
|
|
|
|
This function calls g_spawn_async_with_pipes() internally; see that
|
|
function for full details on the other parameters and details on
|
|
how these functions work on Windows.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on success, %FALSE if an error was set</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="working_directory" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">child's current working
|
|
directory, or %NULL to inherit parent's</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="argv" transfer-ownership="none">
|
|
<doc xml:space="preserve">
|
|
child's argument vector</doc>
|
|
<array c:type="gchar**">
|
|
<type name="filename"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="envp" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">
|
|
child's environment, or %NULL to inherit parent's</doc>
|
|
<array c:type="gchar**">
|
|
<type name="filename"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags from #GSpawnFlags</doc>
|
|
<type name="SpawnFlags" c:type="GSpawnFlags"/>
|
|
</parameter>
|
|
<parameter name="child_setup" transfer-ownership="none" nullable="1" allow-none="1" scope="async" closure="5">
|
|
<doc xml:space="preserve">function to run in the child just before exec()</doc>
|
|
<type name="SpawnChildSetupFunc" c:type="GSpawnChildSetupFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">user data for @child_setup</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="standard_output" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for child output, or %NULL</doc>
|
|
<array c:type="gchar**">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="standard_error" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for child error messages, or %NULL</doc>
|
|
<array c:type="gchar**">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="exit_status" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for child exit status, as returned by waitpid(), or %NULL</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="sprintf" c:identifier="g_sprintf" version="2.2" introspectable="0">
|
|
<doc xml:space="preserve">An implementation of the standard sprintf() function which supports
|
|
positional parameters, as specified in the Single Unix Specification.
|
|
|
|
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().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes printed.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">A pointer to a memory buffer to contain the resulting string. It
|
|
is up to the caller to ensure that the allocated buffer is large
|
|
enough to hold the formatted result</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">a standard printf() format string, but notice
|
|
[string precision pitfalls][string-precision]</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">the arguments to insert in the output.</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="steal_pointer" c:identifier="g_steal_pointer" version="2.44" introspectable="0">
|
|
<doc xml:space="preserve">Sets @pp to %NULL, returning the value that was there before.
|
|
|
|
Conceptually, this transfers the ownership of the pointer from the
|
|
referenced variable to the "caller" of the macro (ie: "steals" the
|
|
reference).
|
|
|
|
The return value will be properly typed, according to the type of
|
|
@pp.
|
|
|
|
This can be very useful when combined with g_autoptr() to prevent the
|
|
return value of a function from being automatically freed. Consider
|
|
the following example (which only works on GCC and clang):
|
|
|
|
|[
|
|
GObject *
|
|
create_object (void)
|
|
{
|
|
g_autoptr(GObject) obj = g_object_new (G_TYPE_OBJECT, NULL);
|
|
|
|
if (early_error_case)
|
|
return NULL;
|
|
|
|
return g_steal_pointer (&obj);
|
|
}
|
|
]|
|
|
|
|
It can also be used in similar ways for 'out' parameters and is
|
|
particularly useful for dealing with optional out parameters:
|
|
|
|
|[
|
|
gboolean
|
|
get_object (GObject **obj_out)
|
|
{
|
|
g_autoptr(GObject) obj = g_object_new (G_TYPE_OBJECT, NULL);
|
|
|
|
if (early_error_case)
|
|
return FALSE;
|
|
|
|
if (obj_out)
|
|
*obj_out = g_steal_pointer (&obj);
|
|
|
|
return TRUE;
|
|
}
|
|
]|
|
|
|
|
In the above example, the object will be automatically freed in the
|
|
early error case and also in the case that %NULL was given for
|
|
@obj_out.</doc>
|
|
<parameters>
|
|
<parameter name="pp">
|
|
<doc xml:space="preserve">a pointer to a pointer</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="stpcpy" c:identifier="g_stpcpy">
|
|
<doc xml:space="preserve">Copies a nul-terminated string into the dest buffer, include the
|
|
trailing nul, and return a pointer to the trailing nul byte.
|
|
This is useful for concatenating multiple strings together
|
|
without having to repeatedly scan for the end.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to trailing nul byte.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dest" transfer-ownership="none">
|
|
<doc xml:space="preserve">destination buffer.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="src" transfer-ownership="none">
|
|
<doc xml:space="preserve">source string.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="str_equal" c:identifier="g_str_equal">
|
|
<doc xml:space="preserve">Compares two strings for byte-by-byte equality and returns %TRUE
|
|
if they are equal. It can be passed to g_hash_table_new() as the
|
|
@key_equal_func parameter, when using non-%NULL strings as keys in a
|
|
#GHashTable.
|
|
|
|
This function is typically used for hash table comparisons, but can be used
|
|
for general purpose comparisons of non-%NULL strings. For a %NULL-safe string
|
|
comparison function, see g_strcmp0().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the two keys match</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="v1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="v2" transfer-ownership="none">
|
|
<doc xml:space="preserve">a key to compare with @v1</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="str_has_prefix" c:identifier="g_str_has_prefix" version="2.2">
|
|
<doc xml:space="preserve">Looks whether the string @str begins with @prefix.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @str begins with @prefix, %FALSE otherwise.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a nul-terminated string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="prefix" transfer-ownership="none">
|
|
<doc xml:space="preserve">the nul-terminated prefix to look for</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="str_has_suffix" c:identifier="g_str_has_suffix" version="2.2">
|
|
<doc xml:space="preserve">Looks whether the string @str ends with @suffix.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @str end with @suffix, %FALSE otherwise.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a nul-terminated string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="suffix" transfer-ownership="none">
|
|
<doc xml:space="preserve">the nul-terminated suffix to look for</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="str_hash" c:identifier="g_str_hash">
|
|
<doc xml:space="preserve">Converts a string to a hash value.
|
|
|
|
This function implements the widely used "djb" hash apparently
|
|
posted by Daniel Bernstein to comp.lang.c some time ago. The 32
|
|
bit unsigned hash value starts at 5381 and for each byte 'c' in
|
|
the string, is updated: `hash = hash * 33 + c`. This function
|
|
uses the signed value of each byte.
|
|
|
|
It can be passed to g_hash_table_new() as the @hash_func parameter,
|
|
when using non-%NULL strings as keys in a #GHashTable.
|
|
|
|
Note that this function may not be a perfect fit for all use cases.
|
|
For example, it produces some hash collisions with strings as short
|
|
as 2.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a hash value corresponding to the key</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="v" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string key</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="str_is_ascii" c:identifier="g_str_is_ascii" version="2.40">
|
|
<doc xml:space="preserve">Determines if a string is pure ASCII. A string is pure ASCII if it
|
|
contains no bytes with the high bit set.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @str is ASCII</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="str_match_string" c:identifier="g_str_match_string" version="2.40">
|
|
<doc xml:space="preserve">Checks if a search conducted for @search_term should match
|
|
@potential_hit.
|
|
|
|
This function calls g_str_tokenize_and_fold() on both
|
|
@search_term and @potential_hit. ASCII alternates are never taken
|
|
for @search_term but will be taken for @potential_hit according to
|
|
the value of @accept_alternates.
|
|
|
|
A hit occurs when each folded token in @search_term is a prefix of a
|
|
folded token from @potential_hit.
|
|
|
|
Depending on how you're performing the search, it will typically be
|
|
faster to call g_str_tokenize_and_fold() on each string in
|
|
your corpus and build an index on the returned folded tokens, then
|
|
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 has ‘fo’ as a prefix).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @potential_hit is a hit</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="search_term" transfer-ownership="none">
|
|
<doc xml:space="preserve">the search term from the user</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="potential_hit" transfer-ownership="none">
|
|
<doc xml:space="preserve">the text that may be a hit</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="accept_alternates" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE to accept ASCII alternates</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="str_to_ascii" c:identifier="g_str_to_ascii" version="2.40">
|
|
<doc xml:space="preserve">Transliterate @str to plain ASCII.
|
|
|
|
For best results, @str should be in composed normalised form.
|
|
|
|
This function performs a reasonably good set of character
|
|
replacements. The particular set of replacements that is done may
|
|
change by version or even by runtime environment.
|
|
|
|
If the source language of @str is known, it can used to improve the
|
|
accuracy of the translation by passing it as @from_locale. It should
|
|
be a valid POSIX locale string (of the form
|
|
`language[_territory][.codeset][@modifier]`).
|
|
|
|
If @from_locale is %NULL then the current locale is used.
|
|
|
|
If you want to do translation for no specific locale, and you want it
|
|
to be done independently of the currently locale, specify `"C"` for
|
|
@from_locale.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a string in plain ASCII</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string, in UTF-8</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="from_locale" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the source locale, if known</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="str_tokenize_and_fold" c:identifier="g_str_tokenize_and_fold" version="2.40">
|
|
<doc xml:space="preserve">Tokenises @string and performs folding on each token.
|
|
|
|
A token is a non-empty sequence of alphanumeric characters in the
|
|
source string, separated by non-alphanumeric characters. An
|
|
"alphanumeric" character for this purpose is one that matches
|
|
g_unichar_isalnum() or g_unichar_ismark().
|
|
|
|
Each token is then (Unicode) normalised and case-folded. If
|
|
@ascii_alternates is non-%NULL and some of the returned tokens
|
|
contain non-ASCII characters, ASCII alternatives will be generated.
|
|
|
|
The number of ASCII alternatives that are generated and the method
|
|
for doing so is unspecified, but @translit_locale (if specified) may
|
|
improve the transliteration if the language of the source string is
|
|
known.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the folded tokens</doc>
|
|
<array c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="translit_locale" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the language code (like 'de' or
|
|
'en_GB') from which @string originates</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="ascii_alternates" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">a
|
|
return location for ASCII alternates</doc>
|
|
<array c:type="gchar***">
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</array>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strcanon" c:identifier="g_strcanon">
|
|
<doc xml:space="preserve">For each character in @string, if the character is not in @valid_chars,
|
|
replaces the character with @substitutor. Modifies @string in place,
|
|
and return @string itself, not a copy. The return value is to allow
|
|
nesting such as
|
|
|[<!-- language="C" -->
|
|
g_ascii_strup (g_strcanon (str, "abc", '?'))
|
|
]|
|
|
|
|
In order to modify a copy, you may use `g_strdup()`:
|
|
|[<!-- language="C" -->
|
|
reformatted = g_strcanon (g_strdup (const_str), "abc", '?');
|
|
...
|
|
g_free (reformatted);
|
|
]|</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a nul-terminated array of bytes</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="valid_chars" transfer-ownership="none">
|
|
<doc xml:space="preserve">bytes permitted in @string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="substitutor" transfer-ownership="none">
|
|
<doc xml:space="preserve">replacement character for disallowed bytes</doc>
|
|
<type name="gchar" c:type="gchar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strcasecmp" c:identifier="g_strcasecmp" deprecated="1" deprecated-version="2.2">
|
|
<doc xml:space="preserve">A case-insensitive string comparison, corresponding to the standard
|
|
strcasecmp() function on platforms which support it.</doc>
|
|
<doc-deprecated xml:space="preserve">See g_strncasecmp() for a discussion of why this
|
|
function is deprecated and how to replace it.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">0 if the strings match, a negative value if @s1 < @s2,
|
|
or a positive value if @s1 > @s2.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="s1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="s2" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string to compare with @s1</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strchomp" c:identifier="g_strchomp">
|
|
<doc xml:space="preserve">Removes trailing whitespace from a string.
|
|
|
|
This function doesn't allocate or reallocate any memory;
|
|
it modifies @string in place. Therefore, it cannot be used
|
|
on statically allocated strings.
|
|
|
|
The pointer to @string is returned to allow the nesting of functions.
|
|
|
|
Also see g_strchug() and g_strstrip().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string to remove the trailing whitespace from</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strchug" c:identifier="g_strchug">
|
|
<doc xml:space="preserve">Removes leading whitespace from a string, by moving the rest
|
|
of the characters forward.
|
|
|
|
This function doesn't allocate or reallocate any memory;
|
|
it modifies @string in place. Therefore, it cannot be used on
|
|
statically allocated strings.
|
|
|
|
The pointer to @string is returned to allow the nesting of functions.
|
|
|
|
Also see g_strchomp() and g_strstrip().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string to remove the leading whitespace from</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strcmp0" c:identifier="g_strcmp0" version="2.16">
|
|
<doc xml:space="preserve">Compares @str1 and @str2 like strcmp(). Handles %NULL
|
|
gracefully by sorting it before non-%NULL strings.
|
|
Comparing two %NULL pointers returns 0.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">an integer less than, equal to, or greater than zero, if @str1 is <, == or > than @str2.</doc>
|
|
<type name="gint" c:type="int"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str1" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a C string or %NULL</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="str2" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">another C string or %NULL</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strcompress" c:identifier="g_strcompress">
|
|
<doc xml:space="preserve">Replaces all escaped characters with their one byte equivalent.
|
|
|
|
This function does the reverse conversion of g_strescape().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated copy of @source with all escaped
|
|
character compressed</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string to compress</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strconcat" c:identifier="g_strconcat" introspectable="0">
|
|
<doc xml:space="preserve">Concatenates all of the given strings into one long string. The
|
|
returned string should be freed with g_free() when no longer needed.
|
|
|
|
The variable argument list must end with %NULL. If you forget the %NULL,
|
|
g_strconcat() will start appending random memory junk to your string.
|
|
|
|
Note that this function is usually not the right function to use to
|
|
assemble a translated message from pieces, since proper translation
|
|
often requires the pieces to be reordered.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated string containing all the string arguments</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string1" transfer-ownership="none">
|
|
<doc xml:space="preserve">the first string to add, which must not be %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">a %NULL-terminated list of strings to append to the string</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strdelimit" c:identifier="g_strdelimit">
|
|
<doc xml:space="preserve">Converts any delimiter characters in @string to @new_delimiter.
|
|
Any characters in @string which are found in @delimiters are
|
|
changed to the @new_delimiter character. Modifies @string in place,
|
|
and returns @string itself, not a copy. The return value is to
|
|
allow nesting such as
|
|
|[<!-- language="C" -->
|
|
g_ascii_strup (g_strdelimit (str, "abc", '?'))
|
|
]|
|
|
|
|
In order to modify a copy, you may use `g_strdup()`:
|
|
|[<!-- language="C" -->
|
|
reformatted = g_strdelimit (g_strdup (const_str), "abc", '?');
|
|
...
|
|
g_free (reformatted);
|
|
]|</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">@string</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to convert</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="delimiters" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string containing the current delimiters,
|
|
or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="new_delimiter" transfer-ownership="none">
|
|
<doc xml:space="preserve">the new delimiter character</doc>
|
|
<type name="gchar" c:type="gchar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strdown" c:identifier="g_strdown" deprecated="1" deprecated-version="2.2">
|
|
<doc xml:space="preserve">Converts a string to lower case.</doc>
|
|
<doc-deprecated xml:space="preserve">This function is totally broken for the reasons discussed
|
|
in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown()
|
|
instead.</doc-deprecated>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the string</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to convert.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strdup" c:identifier="g_strdup">
|
|
<doc xml:space="preserve">Duplicates a string. If @str is %NULL it returns %NULL.
|
|
The returned string should be freed with g_free()
|
|
when no longer needed.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated copy of @str</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the string to duplicate</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strdup_printf" c:identifier="g_strdup_printf" introspectable="0">
|
|
<doc xml:space="preserve">Similar to the standard C sprintf() function but safer, since it
|
|
calculates the maximum space required and allocates memory to hold
|
|
the result. The returned string should be freed with g_free() when no
|
|
longer needed.
|
|
|
|
The returned string is guaranteed to be non-NULL, unless @format
|
|
contains `%lc` or `%ls` conversions, which can fail if no multibyte
|
|
representation is available for the given character.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated string holding the result</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">a standard printf() format string, but notice
|
|
[string precision pitfalls][string-precision]</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">the parameters to insert into the format string</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strdup_vprintf" c:identifier="g_strdup_vprintf" introspectable="0">
|
|
<doc xml:space="preserve">Similar to the standard C vsprintf() function but safer, since it
|
|
calculates the maximum space required and allocates memory to hold
|
|
the result. The returned string should be freed with g_free() when
|
|
no longer needed.
|
|
|
|
The returned string is guaranteed to be non-NULL, unless @format
|
|
contains `%lc` or `%ls` conversions, which can fail if no multibyte
|
|
representation is available for the given character.
|
|
|
|
See also g_vasprintf(), which offers the same functionality, but
|
|
additionally returns the length of the allocated string.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated string holding the result</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">a standard printf() format string, but notice
|
|
[string precision pitfalls][string-precision]</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="args" transfer-ownership="none">
|
|
<doc xml:space="preserve">the list of parameters to insert into the format string</doc>
|
|
<type name="va_list" c:type="va_list"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strdupv" c:identifier="g_strdupv" introspectable="0">
|
|
<doc xml:space="preserve">Copies %NULL-terminated array of strings. The copy is a deep copy;
|
|
the new array should be freed by first freeing each string, then
|
|
the array itself. g_strfreev() does this for you. If called
|
|
on a %NULL value, g_strdupv() simply returns %NULL.</doc>
|
|
<return-value nullable="1">
|
|
<doc xml:space="preserve">a new %NULL-terminated array of strings.</doc>
|
|
<array c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str_array" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a %NULL-terminated array of strings</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strerror" c:identifier="g_strerror">
|
|
<doc xml:space="preserve">Returns a string corresponding to the given error code, e.g. "no
|
|
such process". Unlike strerror(), this always returns a string in
|
|
UTF-8 encoding, and the pointer is guaranteed to remain valid for
|
|
the lifetime of the process.
|
|
|
|
Note that the string may be translated according to the current locale.
|
|
|
|
The value of %errno will not be changed by this function. However, it may
|
|
be changed by intermediate function calls, so you should save its value
|
|
as soon as the call returns:
|
|
|[
|
|
int saved_errno;
|
|
|
|
ret = read (blah);
|
|
saved_errno = errno;
|
|
|
|
g_strerror (saved_errno);
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 string describing the error code. If the error code
|
|
is unknown, it returns a string like "unknown error (<code>)".</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="errnum" transfer-ownership="none">
|
|
<doc xml:space="preserve">the system error number. See the standard C %errno
|
|
documentation</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strescape" c:identifier="g_strescape">
|
|
<doc xml:space="preserve">Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\'
|
|
and '"' in the string @source by inserting a '\' before
|
|
them. Additionally all characters in the range 0x01-0x1F (everything
|
|
below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
|
|
replaced with a '\' followed by their octal representation.
|
|
Characters supplied in @exceptions are not escaped.
|
|
|
|
g_strcompress() does the reverse conversion.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated copy of @source with certain
|
|
characters escaped. See above.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="source" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string to escape</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="exceptions" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string of characters not to escape in @source</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strfreev" c:identifier="g_strfreev">
|
|
<doc xml:space="preserve">Frees a %NULL-terminated array of strings, as well as each
|
|
string it contains.
|
|
|
|
If @str_array is %NULL, this function simply returns.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str_array" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a %NULL-terminated array of strings to free</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="string_chunks">
|
|
<doc xml:space="preserve">String chunks are used to store groups of strings. Memory is
|
|
allocated in blocks, and as strings are added to the #GStringChunk
|
|
they are copied into the next free position in a block. When a block
|
|
is full a new block is allocated.
|
|
|
|
When storing a large number of strings, string chunks are more
|
|
efficient than using g_strdup() since fewer calls to malloc() are
|
|
needed, and less memory is wasted in memory allocation overheads.
|
|
|
|
By adding strings with g_string_chunk_insert_const() it is also
|
|
possible to remove duplicates.
|
|
|
|
To create a new #GStringChunk use g_string_chunk_new().
|
|
|
|
To add strings to a #GStringChunk use g_string_chunk_insert().
|
|
|
|
To add strings to a #GStringChunk, but without duplicating strings
|
|
which are already in the #GStringChunk, use
|
|
g_string_chunk_insert_const().
|
|
|
|
To free the entire #GStringChunk use g_string_chunk_free(). It is
|
|
not possible to free individual strings.</doc>
|
|
</docsection>
|
|
<function name="string_new" c:identifier="g_string_new">
|
|
<doc xml:space="preserve">Creates a new #GString, initialized with the given string.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the new #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="init" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the initial text to copy into the string, or %NULL to
|
|
start with an empty string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="string_new_len" c:identifier="g_string_new_len">
|
|
<doc xml:space="preserve">Creates a new #GString with @len bytes of the @init buffer.
|
|
Because a length is provided, @init need not be nul-terminated,
|
|
and can contain embedded nul bytes.
|
|
|
|
Since this function does not stop at nul bytes, it is the caller's
|
|
responsibility to ensure that @init has at least @len addressable
|
|
bytes.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="init" transfer-ownership="none">
|
|
<doc xml:space="preserve">initial contents of the string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @init to use</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="string_sized_new" c:identifier="g_string_sized_new">
|
|
<doc xml:space="preserve">Creates a new #GString, with enough space for @dfl_size
|
|
bytes. This is useful if you are going to add a lot of
|
|
text to the string and don't want it to be reallocated
|
|
too often.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the new #GString</doc>
|
|
<type name="String" c:type="GString*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dfl_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the default size of the space allocated to
|
|
hold the string</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="string_utils">
|
|
<doc xml:space="preserve">This section describes a number of utility functions for creating,
|
|
duplicating, and manipulating strings.
|
|
|
|
Note that the functions g_printf(), g_fprintf(), g_sprintf(),
|
|
g_vprintf(), g_vfprintf(), g_vsprintf() and g_vasprintf()
|
|
are declared in the header `gprintf.h` which is not included in `glib.h`
|
|
(otherwise using `glib.h` would drag in `stdio.h`), so you'll have to
|
|
explicitly include `<glib/gprintf.h>` in order to use the GLib
|
|
printf() functions.
|
|
|
|
## String precision pitfalls # {#string-precision}
|
|
|
|
While you may use the printf() functions to format UTF-8 strings,
|
|
notice that the precision of a \%Ns parameter is interpreted
|
|
as the number of bytes, not characters to print. On top of that,
|
|
the GNU libc implementation of the printf() functions has the
|
|
"feature" that it checks that the string given for the \%Ns
|
|
parameter consists of a whole number of characters in the current
|
|
encoding. So, unless you are sure you are always going to be in an
|
|
UTF-8 locale or your know your text is restricted to ASCII, avoid
|
|
using \%Ns. If your intention is to format strings for a
|
|
certain number of columns, then \%Ns is not a correct solution
|
|
anyway, since it fails to take wide characters (see g_unichar_iswide())
|
|
into account.
|
|
|
|
Note also that there are various printf() parameters which are platform
|
|
dependent. GLib provides platform independent macros for these parameters
|
|
which should be used instead. A common example is %G_GUINT64_FORMAT, which
|
|
should be used instead of `%llu` or similar parameters for formatting
|
|
64-bit integers. These macros are all named `G_*_FORMAT`; see
|
|
[Basic Types][glib-Basic-Types].</doc>
|
|
</docsection>
|
|
<docsection name="strings">
|
|
<doc xml:space="preserve">A #GString is an object that handles the memory management of a C
|
|
string for you. The emphasis of #GString is on text, typically
|
|
UTF-8. Crucially, the "str" member of a #GString is guaranteed to
|
|
have a trailing nul character, and it is therefore always safe to
|
|
call functions such as strchr() or g_strdup() on it.
|
|
|
|
However, a #GString can also hold arbitrary binary data, because it
|
|
has a "len" member, which includes any possible embedded nul
|
|
characters in the data. Conceptually then, #GString is like a
|
|
#GByteArray with the addition of many convenience methods for text,
|
|
and a guaranteed nul terminator.</doc>
|
|
</docsection>
|
|
<function name="strip_context" c:identifier="g_strip_context" version="2.4">
|
|
<doc xml:space="preserve">An auxiliary function for gettext() support (see Q_()).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@msgval, unless @msgval is identical to @msgid
|
|
and contains a '|' character, in which case a pointer to
|
|
the substring of msgid after the first '|' character is returned.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="msgid" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="msgval" transfer-ownership="none">
|
|
<doc xml:space="preserve">another string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strjoin" c:identifier="g_strjoin" introspectable="0">
|
|
<doc xml:space="preserve">Joins a number of strings together to form one long string, with the
|
|
optional @separator inserted between each of them. The returned string
|
|
should be freed with g_free().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated string containing all of the strings joined
|
|
together, with @separator between them</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="separator" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string to insert between each of the
|
|
strings, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">a %NULL-terminated list of strings to join</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strjoinv" c:identifier="g_strjoinv">
|
|
<doc xml:space="preserve">Joins a number of strings together to form one long string, with the
|
|
optional @separator inserted between each of them. The returned string
|
|
should be freed with g_free().
|
|
|
|
If @str_array has no items, the return value will be an
|
|
empty string. If @str_array contains a single item, @separator will not
|
|
appear in the resulting string.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated string containing all of the strings joined
|
|
together, with @separator between them</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="separator" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string to insert between each of the
|
|
strings, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="str_array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a %NULL-terminated array of strings to join</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strlcat" c:identifier="g_strlcat">
|
|
<doc xml:space="preserve">Portability wrapper that calls strlcat() on systems which have it,
|
|
and emulates it otherwise. Appends nul-terminated @src string to @dest,
|
|
guaranteeing nul-termination for @dest. The total size of @dest won't
|
|
exceed @dest_size.
|
|
|
|
At most @dest_size - 1 characters will be copied. Unlike strncat(),
|
|
@dest_size is the full size of dest, not the space left over. This
|
|
function does not allocate memory. It always nul-terminates (unless
|
|
@dest_size == 0 or there were no nul characters in the @dest_size
|
|
characters of dest to start with).
|
|
|
|
Caveat: this is supposedly a more secure alternative to strcat() or
|
|
strncat(), but for real security g_strconcat() is harder to mess up.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">size of attempted result, which is MIN (dest_size, strlen
|
|
(original dest)) + strlen (src), so if retval >= dest_size,
|
|
truncation occurred.</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dest" transfer-ownership="none">
|
|
<doc xml:space="preserve">destination buffer, already containing one nul-terminated string</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="src" transfer-ownership="none">
|
|
<doc xml:space="preserve">source buffer</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="dest_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @dest buffer in bytes (not length of existing string
|
|
inside @dest)</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strlcpy" c:identifier="g_strlcpy">
|
|
<doc xml:space="preserve">Portability wrapper that calls strlcpy() on systems which have it,
|
|
and emulates strlcpy() otherwise. Copies @src to @dest; @dest is
|
|
guaranteed to be nul-terminated; @src must be nul-terminated;
|
|
@dest_size is the buffer size, not the number of bytes to copy.
|
|
|
|
At most @dest_size - 1 characters will be copied. Always nul-terminates
|
|
(unless @dest_size is 0). This function does not allocate memory. Unlike
|
|
strncpy(), this function doesn't pad @dest (so it's often faster). It
|
|
returns the size of the attempted result, strlen (src), so if
|
|
@retval >= @dest_size, truncation occurred.
|
|
|
|
Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(),
|
|
but if you really want to avoid screwups, g_strdup() is an even better
|
|
idea.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @src</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dest" transfer-ownership="none">
|
|
<doc xml:space="preserve">destination buffer</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="src" transfer-ownership="none">
|
|
<doc xml:space="preserve">source buffer</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="dest_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @dest in bytes</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strncasecmp" c:identifier="g_strncasecmp" deprecated="1" deprecated-version="2.2">
|
|
<doc xml:space="preserve">A case-insensitive string comparison, corresponding to the standard
|
|
strncasecmp() function on platforms which support it. It is similar
|
|
to g_strcasecmp() except it only compares the first @n characters of
|
|
the strings.</doc>
|
|
<doc-deprecated xml:space="preserve">The problem with g_strncasecmp() is that it does
|
|
the comparison by calling toupper()/tolower(). These functions
|
|
are locale-specific and operate on single bytes. However, it is
|
|
impossible to handle things correctly from an internationalization
|
|
standpoint by operating on bytes, since characters may be multibyte.
|
|
Thus g_strncasecmp() is broken if your string is guaranteed to be
|
|
ASCII, since it is locale-sensitive, and it's broken if your string
|
|
is localized, since it doesn't work on many encodings at all,
|
|
including UTF-8, EUC-JP, etc.
|
|
|
|
There are therefore two replacement techniques: g_ascii_strncasecmp(),
|
|
which only works on ASCII and is not locale-sensitive, and
|
|
g_utf8_casefold() followed by strcmp() on the resulting strings,
|
|
which is good for case-insensitive sorting of UTF-8.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">0 if the strings match, a negative value if @s1 < @s2,
|
|
or a positive value if @s1 > @s2.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="s1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="s2" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string to compare with @s1</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum number of characters to compare</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strndup" c:identifier="g_strndup">
|
|
<doc xml:space="preserve">Duplicates the first @n bytes of a string, returning a newly-allocated
|
|
buffer @n + 1 bytes long which will always be nul-terminated. If @str
|
|
is less than @n bytes long the buffer is padded with nuls. If @str is
|
|
%NULL it returns %NULL. The returned value should be freed when no longer
|
|
needed.
|
|
|
|
To copy a number of characters from a UTF-8 encoded string,
|
|
use g_utf8_strncpy() instead.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated buffer containing the first @n bytes
|
|
of @str, nul-terminated</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to duplicate</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum number of bytes to copy from @str</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strnfill" c:identifier="g_strnfill">
|
|
<doc xml:space="preserve">Creates a new string @length bytes long filled with @fill_char.
|
|
The returned string should be freed when no longer needed.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated string filled the @fill_char</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the new string</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="fill_char" transfer-ownership="none">
|
|
<doc xml:space="preserve">the byte to fill the string with</doc>
|
|
<type name="gchar" c:type="gchar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strreverse" c:identifier="g_strreverse">
|
|
<doc xml:space="preserve">Reverses all of the bytes in a string. For example,
|
|
`g_strreverse ("abcdef")` will result in "fedcba".
|
|
|
|
Note that g_strreverse() doesn't work on UTF-8 strings
|
|
containing multibyte characters. For that purpose, use
|
|
g_utf8_strreverse().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the same pointer passed in as @string</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to reverse</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strrstr" c:identifier="g_strrstr">
|
|
<doc xml:space="preserve">Searches the string @haystack for the last occurrence
|
|
of the string @needle.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to the found occurrence, or
|
|
%NULL if not found.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="haystack" transfer-ownership="none">
|
|
<doc xml:space="preserve">a nul-terminated string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="needle" transfer-ownership="none">
|
|
<doc xml:space="preserve">the nul-terminated string to search for</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strrstr_len" c:identifier="g_strrstr_len">
|
|
<doc xml:space="preserve">Searches the string @haystack for the last occurrence
|
|
of the string @needle, limiting the length of the search
|
|
to @haystack_len.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to the found occurrence, or
|
|
%NULL if not found.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="haystack" transfer-ownership="none">
|
|
<doc xml:space="preserve">a nul-terminated string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="haystack_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum length of @haystack</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="needle" transfer-ownership="none">
|
|
<doc xml:space="preserve">the nul-terminated string to search for</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strsignal" c:identifier="g_strsignal">
|
|
<doc xml:space="preserve">Returns a string describing the given signal, e.g. "Segmentation fault".
|
|
You should use this function in preference to strsignal(), because it
|
|
returns a string in UTF-8 encoding, and since not all platforms support
|
|
the strsignal() function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 string describing the signal. If the signal is unknown,
|
|
it returns "unknown signal (<signum>)".</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="signum" transfer-ownership="none">
|
|
<doc xml:space="preserve">the signal number. See the `signal` documentation</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strsplit" c:identifier="g_strsplit" introspectable="0">
|
|
<doc xml:space="preserve">Splits a string into a maximum of @max_tokens pieces, using the given
|
|
@delimiter. If @max_tokens is reached, the remainder of @string is
|
|
appended to the last token.
|
|
|
|
As an example, the result of g_strsplit (":a:bc::d:", ":", -1) is a
|
|
%NULL-terminated vector containing the six strings "", "a", "bc", "", "d"
|
|
and "".
|
|
|
|
As a special case, the result of splitting the empty string "" is an empty
|
|
vector, not a vector containing a single string. The reason for this
|
|
special case is that being able to represent an empty vector is typically
|
|
more useful than consistent handling of empty elements. If you do need
|
|
to represent empty elements, you'll need to check for the empty string
|
|
before calling g_strsplit().</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a newly-allocated %NULL-terminated array of strings. Use
|
|
g_strfreev() to free it.</doc>
|
|
<array c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string to split</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="delimiter" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string which specifies the places at which to split
|
|
the string. The delimiter is not included in any of the resulting
|
|
strings, unless @max_tokens is reached.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="max_tokens" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum number of pieces to split @string into.
|
|
If this is less than 1, the string is split completely.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strsplit_set" c:identifier="g_strsplit_set" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">Splits @string into a number of tokens not containing any of the characters
|
|
in @delimiter. A token is the (possibly empty) longest string that does not
|
|
contain any of the characters in @delimiters. If @max_tokens is reached, the
|
|
remainder is appended to the last token.
|
|
|
|
For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a
|
|
%NULL-terminated vector containing the three strings "abc", "def",
|
|
and "ghi".
|
|
|
|
The result of g_strsplit_set (":def/ghi:", ":/", -1) is a %NULL-terminated
|
|
vector containing the four strings "", "def", "ghi", and "".
|
|
|
|
As a special case, the result of splitting the empty string "" is an empty
|
|
vector, not a vector containing a single string. The reason for this
|
|
special case is that being able to represent an empty vector is typically
|
|
more useful than consistent handling of empty elements. If you do need
|
|
to represent empty elements, you'll need to check for the empty string
|
|
before calling g_strsplit_set().
|
|
|
|
Note that this function works on bytes not characters, so it can't be used
|
|
to delimit UTF-8 strings for anything but ASCII characters.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a newly-allocated %NULL-terminated array of strings. Use
|
|
g_strfreev() to free it.</doc>
|
|
<array c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">The string to be tokenized</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="delimiters" transfer-ownership="none">
|
|
<doc xml:space="preserve">A nul-terminated string containing bytes that are used
|
|
to split the string (it can accept an empty string, which will result
|
|
in no string splitting).</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="max_tokens" transfer-ownership="none">
|
|
<doc xml:space="preserve">The maximum number of tokens to split @string into.
|
|
If this is less than 1, the string is split completely</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strstr_len" c:identifier="g_strstr_len">
|
|
<doc xml:space="preserve">Searches the string @haystack for the first occurrence
|
|
of the string @needle, limiting the length of the search
|
|
to @haystack_len.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to the found occurrence, or
|
|
%NULL if not found.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="haystack" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="haystack_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum length of @haystack. Note that -1 is
|
|
a valid length, if @haystack is nul-terminated, meaning it will
|
|
search through the whole string.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="needle" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to search for</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="strstrip" c:identifier="g_strstrip" introspectable="0">
|
|
<doc xml:space="preserve">Removes leading and trailing whitespace from a string.
|
|
See g_strchomp() and g_strchug().</doc>
|
|
<parameters>
|
|
<parameter name="string">
|
|
<doc xml:space="preserve">a string to remove the leading and trailing whitespace from</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="strtod" c:identifier="g_strtod">
|
|
<doc xml:space="preserve">Converts a string to a #gdouble value.
|
|
It calls the standard strtod() function to handle the conversion, but
|
|
if the string is not completely converted it attempts the conversion
|
|
again with g_ascii_strtod(), and returns the best match.
|
|
|
|
This function should seldom be used. The normal situation when reading
|
|
numbers not for human consumption is to use g_ascii_strtod(). Only when
|
|
you know that you must expect both locale formatted and C formatted numbers
|
|
should you use this. Make sure that you don't pass strings such as comma
|
|
separated lists of values, since the commas may be interpreted as a decimal
|
|
point in some locales, causing unexpected results.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the #gdouble value.</doc>
|
|
<type name="gdouble" c:type="gdouble"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="nptr" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to convert to a numeric value.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="endptr" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">if non-%NULL, it returns the
|
|
character after the last character used in the conversion.</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strup" c:identifier="g_strup" deprecated="1" deprecated-version="2.2">
|
|
<doc xml:space="preserve">Converts a string to upper case.</doc>
|
|
<doc-deprecated xml:space="preserve">This function is totally broken for the reasons
|
|
discussed in the g_strncasecmp() docs - use g_ascii_strup()
|
|
or g_utf8_strup() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the string</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string to convert</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strv_contains" c:identifier="g_strv_contains" version="2.44">
|
|
<doc xml:space="preserve">Checks if @strv contains @str. @strv must not be %NULL.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @str is an element of @strv, according to g_str_equal().</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="strv" transfer-ownership="none">
|
|
<doc xml:space="preserve">a %NULL-terminated array of strings</doc>
|
|
<type name="utf8" c:type="const gchar* const*"/>
|
|
</parameter>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strv_equal" c:identifier="g_strv_equal" version="2.60">
|
|
<doc xml:space="preserve">Checks if @strv1 and @strv2 contain exactly the same elements in exactly the
|
|
same order. Elements are compared using g_str_equal(). To match independently
|
|
of order, sort the arrays first (using g_qsort_with_data() or similar).
|
|
|
|
Two empty arrays are considered equal. Neither @strv1 not @strv2 may be
|
|
%NULL.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @strv1 and @strv2 are equal</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="strv1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a %NULL-terminated array of strings</doc>
|
|
<type name="utf8" c:type="const gchar* const*"/>
|
|
</parameter>
|
|
<parameter name="strv2" transfer-ownership="none">
|
|
<doc xml:space="preserve">another %NULL-terminated array of strings</doc>
|
|
<type name="utf8" c:type="const gchar* const*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="strv_get_type" c:identifier="g_strv_get_type">
|
|
<return-value transfer-ownership="none">
|
|
<type name="GType" c:type="GType"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="strv_length" c:identifier="g_strv_length" version="2.6">
|
|
<doc xml:space="preserve">Returns the length of the given %NULL-terminated
|
|
string array @str_array. @str_array must not be %NULL.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @str_array.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str_array" transfer-ownership="none">
|
|
<doc xml:space="preserve">a %NULL-terminated array of strings</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="test_add" c:identifier="g_test_add" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Hook up a new test case at @testpath, similar to g_test_add_func().
|
|
A fixture data structure with setup and teardown functions may be provided,
|
|
similar to g_test_create_case().
|
|
|
|
g_test_add() is implemented as a macro, so that the fsetup(), ftest() and
|
|
fteardown() callbacks can expect a @Fixture pointer as their first argument
|
|
in a type safe manner. They otherwise have type #GTestFixtureFunc.</doc>
|
|
<parameters>
|
|
<parameter name="testpath">
|
|
<doc xml:space="preserve">The test path for a new test case.</doc>
|
|
</parameter>
|
|
<parameter name="Fixture">
|
|
<doc xml:space="preserve">The type of a fixture data structure.</doc>
|
|
</parameter>
|
|
<parameter name="tdata">
|
|
<doc xml:space="preserve">Data argument for the test functions.</doc>
|
|
</parameter>
|
|
<parameter name="fsetup">
|
|
<doc xml:space="preserve">The function to set up the fixture data.</doc>
|
|
</parameter>
|
|
<parameter name="ftest">
|
|
<doc xml:space="preserve">The actual test function.</doc>
|
|
</parameter>
|
|
<parameter name="fteardown">
|
|
<doc xml:space="preserve">The function to tear down the fixture data.</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="test_add_data_func" c:identifier="g_test_add_data_func" version="2.16">
|
|
<doc xml:space="preserve">Create a new test case, similar to g_test_create_case(). However
|
|
the test is assumed to use no fixture, and test suites are automatically
|
|
created on the fly and added to the root fixture, based on the
|
|
slash-separated portions of @testpath. The @test_data argument
|
|
will be passed as first argument to @test_func.
|
|
|
|
If @testpath includes the component "subprocess" anywhere in it,
|
|
the test will be skipped by default, and only run if explicitly
|
|
required via the `-p` command-line option or g_test_trap_subprocess().
|
|
|
|
No component of @testpath may start with a dot (`.`) if the
|
|
%G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to
|
|
do so even if it isn’t.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="testpath" transfer-ownership="none">
|
|
<doc xml:space="preserve">/-separated test case path name for the test.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="test_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">Test data argument for the test function.</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="test_func" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">The test function to invoke for this test.</doc>
|
|
<type name="TestDataFunc" c:type="GTestDataFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_add_data_func_full" c:identifier="g_test_add_data_func_full" version="2.34">
|
|
<doc xml:space="preserve">Create a new test case, as with g_test_add_data_func(), but freeing
|
|
@test_data after the test run is complete.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="testpath" transfer-ownership="none">
|
|
<doc xml:space="preserve">/-separated test case path name for the test.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="test_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">Test data argument for the test function.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="test_func" transfer-ownership="none" scope="notified" destroy="3">
|
|
<doc xml:space="preserve">The test function to invoke for this test.</doc>
|
|
<type name="TestDataFunc" c:type="GTestDataFunc"/>
|
|
</parameter>
|
|
<parameter name="data_free_func" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">#GDestroyNotify for @test_data.</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_add_func" c:identifier="g_test_add_func" version="2.16">
|
|
<doc xml:space="preserve">Create a new test case, similar to g_test_create_case(). However
|
|
the test is assumed to use no fixture, and test suites are automatically
|
|
created on the fly and added to the root fixture, based on the
|
|
slash-separated portions of @testpath.
|
|
|
|
If @testpath includes the component "subprocess" anywhere in it,
|
|
the test will be skipped by default, and only run if explicitly
|
|
required via the `-p` command-line option or g_test_trap_subprocess().
|
|
|
|
No component of @testpath may start with a dot (`.`) if the
|
|
%G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to
|
|
do so even if it isn’t.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="testpath" transfer-ownership="none">
|
|
<doc xml:space="preserve">/-separated test case path name for the test.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="test_func" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">The test function to invoke for this test.</doc>
|
|
<type name="TestFunc" c:type="GTestFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_add_vtable" c:identifier="g_test_add_vtable" introspectable="0">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="testpath" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="data_size" transfer-ownership="none">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="test_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="data_setup" transfer-ownership="none">
|
|
<type name="TestFixtureFunc" c:type="GTestFixtureFunc"/>
|
|
</parameter>
|
|
<parameter name="data_test" transfer-ownership="none">
|
|
<type name="TestFixtureFunc" c:type="GTestFixtureFunc"/>
|
|
</parameter>
|
|
<parameter name="data_teardown" transfer-ownership="none">
|
|
<type name="TestFixtureFunc" c:type="GTestFixtureFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_assert_expected_messages_internal" c:identifier="g_test_assert_expected_messages_internal">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="domain" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="file" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="line" transfer-ownership="none">
|
|
<type name="gint" c:type="int"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_bug" c:identifier="g_test_bug" version="2.16">
|
|
<doc xml:space="preserve">This function adds a message to test reports that
|
|
associates a bug URI with a test case.
|
|
Bug URIs are constructed from a base URI set with g_test_bug_base()
|
|
and @bug_uri_snippet. If g_test_bug_base() has not been called, it is
|
|
assumed to be the empty string, so a full URI can be provided to
|
|
g_test_bug() instead.</doc>
|
|
<doc-version xml:space="preserve">
|
|
See also: g_test_summary()</doc-version>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="bug_uri_snippet" transfer-ownership="none">
|
|
<doc xml:space="preserve">Bug specific bug tracker URI portion.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_bug_base" c:identifier="g_test_bug_base" version="2.16">
|
|
<doc xml:space="preserve">Specify the base URI for bug reports.
|
|
|
|
The base URI is used to construct bug report messages for
|
|
g_test_message() when g_test_bug() is called.
|
|
Calling this function outside of a test case sets the
|
|
default base URI for all test cases. Calling it from within
|
|
a test case changes the base URI for the scope of the test
|
|
case only.
|
|
Bug URIs are constructed by appending a bug specific URI
|
|
portion to @uri_pattern, or by replacing the special string
|
|
'\%s' within @uri_pattern if that is present.
|
|
|
|
If g_test_bug_base() is not called, bug URIs are formed solely
|
|
from the value provided by g_test_bug().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri_pattern" transfer-ownership="none">
|
|
<doc xml:space="preserve">the base pattern for bug URIs</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_build_filename" c:identifier="g_test_build_filename" version="2.38" introspectable="0">
|
|
<doc xml:space="preserve">Creates the pathname to a data file that is required for a test.
|
|
|
|
This function is conceptually similar to g_build_filename() except
|
|
that the first argument has been replaced with a #GTestFileType
|
|
argument.
|
|
|
|
The data file should either have been distributed with the module
|
|
containing the test (%G_TEST_DIST) or built as part of the build
|
|
system of that module (%G_TEST_BUILT).
|
|
|
|
In order for this function to work in srcdir != builddir situations,
|
|
the G_TEST_SRCDIR and G_TEST_BUILDDIR environment variables need to
|
|
have been defined. As of 2.38, this is done by the glib.mk
|
|
included in GLib. Please ensure that your copy is up to date before
|
|
using this function.
|
|
|
|
In case neither variable is set, this function will fall back to
|
|
using the dirname portion of argv[0], possibly removing ".libs".
|
|
This allows for casual running of tests directly from the commandline
|
|
in the srcdir == builddir case and should also support running of
|
|
installed tests, assuming the data files have been installed in the
|
|
same relative path as the test binary.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the path of the file, to be freed using g_free()</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="file_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">the type of file (built vs. distributed)</doc>
|
|
<type name="TestFileType" c:type="GTestFileType"/>
|
|
</parameter>
|
|
<parameter name="first_path" transfer-ownership="none">
|
|
<doc xml:space="preserve">the first segment of the pathname</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">%NULL-terminated additional path segments</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_create_case" c:identifier="g_test_create_case" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Create a new #GTestCase, named @test_name.
|
|
|
|
This API is fairly low level, and calling g_test_add() or g_test_add_func()
|
|
is preferable.
|
|
|
|
When this test is executed, a fixture structure of size @data_size
|
|
will be automatically allocated and filled with zeros. Then @data_setup is
|
|
called to initialize the fixture. After fixture setup, the actual test
|
|
function @data_test is called. Once the test run completes, the
|
|
fixture structure is torn down by calling @data_teardown and
|
|
after that the memory is automatically released by the test framework.
|
|
|
|
Splitting up a test run into fixture setup, test function and
|
|
fixture teardown is most useful if the same fixture type is used for
|
|
multiple tests. In this cases, g_test_create_case() will be
|
|
called with the same type of fixture (the @data_size argument), but varying
|
|
@test_name and @data_test arguments.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">a newly allocated #GTestCase.</doc>
|
|
<type name="TestCase" c:type="GTestCase*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="test_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">the name for the test case</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="data_size" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of the fixture data structure</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="test_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">test data argument for the test functions</doc>
|
|
<type name="gpointer" c:type="gconstpointer"/>
|
|
</parameter>
|
|
<parameter name="data_setup" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">the function to set up the fixture data</doc>
|
|
<type name="TestFixtureFunc" c:type="GTestFixtureFunc"/>
|
|
</parameter>
|
|
<parameter name="data_test" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">the actual test function</doc>
|
|
<type name="TestFixtureFunc" c:type="GTestFixtureFunc"/>
|
|
</parameter>
|
|
<parameter name="data_teardown" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">the function to teardown the fixture data</doc>
|
|
<type name="TestFixtureFunc" c:type="GTestFixtureFunc"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_create_suite" c:identifier="g_test_create_suite" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Create a new test suite with the name @suite_name.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">A newly allocated #GTestSuite instance.</doc>
|
|
<type name="TestSuite" c:type="GTestSuite*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="suite_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">a name for the suite</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_expect_message" c:identifier="g_test_expect_message" version="2.34">
|
|
<doc xml:space="preserve">Indicates that a message with the given @log_domain and @log_level,
|
|
with text matching @pattern, is expected to be logged. When this
|
|
message is logged, it will not be printed, and the test case will
|
|
not abort.
|
|
|
|
This API may only be used with the old logging API (g_log() without
|
|
%G_LOG_USE_STRUCTURED defined). It will not work with the structured logging
|
|
API. See [Testing for Messages][testing-for-messages].
|
|
|
|
Use g_test_assert_expected_messages() to assert that all
|
|
previously-expected messages have been seen and suppressed.
|
|
|
|
You can call this multiple times in a row, if multiple messages are
|
|
expected as a result of a single call. (The messages must appear in
|
|
the same order as the calls to g_test_expect_message().)
|
|
|
|
For example:
|
|
|
|
|[<!-- language="C" -->
|
|
// g_main_context_push_thread_default() should fail if the
|
|
// context is already owned by another thread.
|
|
g_test_expect_message (G_LOG_DOMAIN,
|
|
G_LOG_LEVEL_CRITICAL,
|
|
"assertion*acquired_context*failed");
|
|
g_main_context_push_thread_default (bad_context);
|
|
g_test_assert_expected_messages ();
|
|
]|
|
|
|
|
Note that you cannot use this to test g_error() messages, since
|
|
g_error() intentionally never returns even if the program doesn't
|
|
abort; use g_test_trap_subprocess() in this case.
|
|
|
|
If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly
|
|
expected via g_test_expect_message() then they will be ignored.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_domain" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the log domain of the message</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="log_level" transfer-ownership="none">
|
|
<doc xml:space="preserve">the log level of the message</doc>
|
|
<type name="LogLevelFlags" c:type="GLogLevelFlags"/>
|
|
</parameter>
|
|
<parameter name="pattern" transfer-ownership="none">
|
|
<doc xml:space="preserve">a glob-style [pattern][glib-Glob-style-pattern-matching]</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_fail" c:identifier="g_test_fail" version="2.30">
|
|
<doc xml:space="preserve">Indicates that a test failed. This function can be called
|
|
multiple times from the same test. You can use this function
|
|
if your test failed in a recoverable way.
|
|
|
|
Do not use this function if the failure of a test could cause
|
|
other tests to malfunction.
|
|
|
|
Calling this function will not stop the test from running, you
|
|
need to return from the test function yourself. So you can
|
|
produce additional diagnostic messages or even continue running
|
|
the test.
|
|
|
|
If not called from inside a test, this function does nothing.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="test_failed" c:identifier="g_test_failed" version="2.38">
|
|
<doc xml:space="preserve">Returns whether a test has already failed. This will
|
|
be the case when g_test_fail(), g_test_incomplete()
|
|
or g_test_skip() have been called, but also if an
|
|
assertion has failed.
|
|
|
|
This can be useful to return early from a test if
|
|
continuing after a failed assertion might be harmful.
|
|
|
|
The return value of this function is only meaningful
|
|
if it is called from inside a test function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the test has failed</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="test_get_dir" c:identifier="g_test_get_dir" version="2.38">
|
|
<doc xml:space="preserve">Gets the pathname of the directory containing test files of the type
|
|
specified by @file_type.
|
|
|
|
This is approximately the same as calling g_test_build_filename("."),
|
|
but you don't need to free the return value.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the path of the directory, owned by GLib</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="file_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">the type of file (built vs. distributed)</doc>
|
|
<type name="TestFileType" c:type="GTestFileType"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_get_filename" c:identifier="g_test_get_filename" version="2.38" introspectable="0">
|
|
<doc xml:space="preserve">Gets the pathname to a data file that is required for a test.
|
|
|
|
This is the same as g_test_build_filename() with two differences.
|
|
The first difference is that must only use this function from within
|
|
a testcase function. The second difference is that you need not free
|
|
the return value -- it will be automatically freed when the testcase
|
|
finishes running.
|
|
|
|
It is safe to use this function from a thread inside of a testcase
|
|
but you must ensure that all such uses occur before the main testcase
|
|
function returns (ie: it is best to ensure that all threads have been
|
|
joined).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the path, automatically freed at the end of the testcase</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="file_type" transfer-ownership="none">
|
|
<doc xml:space="preserve">the type of file (built vs. distributed)</doc>
|
|
<type name="TestFileType" c:type="GTestFileType"/>
|
|
</parameter>
|
|
<parameter name="first_path" transfer-ownership="none">
|
|
<doc xml:space="preserve">the first segment of the pathname</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">%NULL-terminated additional path segments</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_get_root" c:identifier="g_test_get_root" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Get the toplevel test suite for the test path API.</doc>
|
|
<return-value>
|
|
<doc xml:space="preserve">the toplevel #GTestSuite</doc>
|
|
<type name="TestSuite" c:type="GTestSuite*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="test_incomplete" c:identifier="g_test_incomplete" version="2.38">
|
|
<doc xml:space="preserve">Indicates that a test failed because of some incomplete
|
|
functionality. This function can be called multiple times
|
|
from the same test.
|
|
|
|
Calling this function will not stop the test from running, you
|
|
need to return from the test function yourself. So you can
|
|
produce additional diagnostic messages or even continue running
|
|
the test.
|
|
|
|
If not called from inside a test, this function does nothing.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="msg" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">explanation</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_init" c:identifier="g_test_init" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Initialize the GLib testing framework, e.g. by seeding the
|
|
test random number generator, the name for g_get_prgname()
|
|
and parsing test related command line args.
|
|
|
|
So far, the following arguments are understood:
|
|
|
|
- `-l`: List test cases available in a test executable.
|
|
- `--seed=SEED`: Provide a random seed to reproduce test
|
|
runs using random numbers.
|
|
- `--verbose`: Run tests verbosely.
|
|
- `-q`, `--quiet`: Run tests quietly.
|
|
- `-p PATH`: Execute all tests matching the given path.
|
|
- `-s PATH`: Skip all tests matching the given path.
|
|
This can also be used to force a test to run that would otherwise
|
|
be skipped (ie, a test whose name contains "/subprocess").
|
|
- `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according to these test modes:
|
|
|
|
`perf`: Performance tests, may take long and report results (off by default).
|
|
|
|
`slow`, `thorough`: Slow and thorough tests, may take quite long and maximize coverage
|
|
(off by default).
|
|
|
|
`quick`: Quick tests, should run really quickly and give good coverage (the default).
|
|
|
|
`undefined`: Tests for undefined behaviour, may provoke programming errors
|
|
under g_test_trap_subprocess() or g_test_expect_message() to check
|
|
that appropriate assertions or warnings are given (the default).
|
|
|
|
`no-undefined`: Avoid tests for undefined behaviour
|
|
|
|
- `--debug-log`: Debug test logging output.
|
|
|
|
Options which can be passed to @... are:
|
|
|
|
- `"no_g_set_prgname"`: Causes g_test_init() to not call g_set_prgname().
|
|
- %G_TEST_OPTION_ISOLATE_DIRS: Creates a unique temporary directory for each
|
|
unit test and uses g_set_user_dirs() to set XDG directories to point into
|
|
that temporary directory for the duration of the unit test. See the
|
|
documentation for %G_TEST_OPTION_ISOLATE_DIRS.
|
|
|
|
Since 2.58, if tests are compiled with `G_DISABLE_ASSERT` defined,
|
|
g_test_init() will print an error and exit. This is to prevent no-op tests
|
|
from being executed, as g_assert() is commonly (erroneously) used in unit
|
|
tests, and is a no-op when compiled with `G_DISABLE_ASSERT`. Ensure your
|
|
tests are compiled without `G_DISABLE_ASSERT` defined.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="argc" transfer-ownership="none">
|
|
<doc xml:space="preserve">Address of the @argc parameter of the main() function.
|
|
Changed if any arguments were handled.</doc>
|
|
<type name="gint" c:type="int*"/>
|
|
</parameter>
|
|
<parameter name="argv" transfer-ownership="none">
|
|
<doc xml:space="preserve">Address of the @argv parameter of main().
|
|
Any parameters understood by g_test_init() stripped before return.</doc>
|
|
<type name="utf8" c:type="char***"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">%NULL-terminated list of special options, documented below.</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_log_set_fatal_handler" c:identifier="g_test_log_set_fatal_handler" version="2.22" introspectable="0">
|
|
<doc xml:space="preserve">Installs a non-error fatal log handler which can be
|
|
used to decide whether log messages which are counted
|
|
as fatal abort the program.
|
|
|
|
The use case here is that you are running a test case
|
|
that depends on particular libraries or circumstances
|
|
and cannot prevent certain known critical or warning
|
|
messages. So you install a handler that compares the
|
|
domain and message to precisely not abort in such a case.
|
|
|
|
Note that the handler is reset at the beginning of
|
|
any test case, so you have to set it inside each test
|
|
function which needs the special behavior.
|
|
|
|
This handler has no effect on g_error messages.
|
|
|
|
This handler also has no effect on structured log messages (using
|
|
g_log_structured() or g_log_structured_array()). To change the fatal
|
|
behaviour for specific log messages, programs must install a custom log
|
|
writer function using g_log_set_writer_func().See
|
|
[Using Structured Logging][using-structured-logging].</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_func" transfer-ownership="none" closure="1">
|
|
<doc xml:space="preserve">the log handler function.</doc>
|
|
<type name="TestLogFatalFunc" c:type="GTestLogFatalFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data passed to the log handler.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_log_type_name" c:identifier="g_test_log_type_name">
|
|
<return-value transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="log_type" transfer-ownership="none">
|
|
<type name="TestLogType" c:type="GTestLogType"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_maximized_result" c:identifier="g_test_maximized_result" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Report the result of a performance or measurement test.
|
|
The test should generally strive to maximize the reported
|
|
quantities (larger values are better than smaller ones),
|
|
this and @maximized_quantity can determine sorting
|
|
order for test result reports.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="maximized_quantity" transfer-ownership="none">
|
|
<doc xml:space="preserve">the reported value</doc>
|
|
<type name="gdouble" c:type="double"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">the format string of the report message</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">arguments to pass to the printf() function</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_message" c:identifier="g_test_message" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Add a message to the test report.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">the format string</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">printf-like arguments to @format</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_minimized_result" c:identifier="g_test_minimized_result" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Report the result of a performance or measurement test.
|
|
The test should generally strive to minimize the reported
|
|
quantities (smaller values are better than larger ones),
|
|
this and @minimized_quantity can determine sorting
|
|
order for test result reports.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="minimized_quantity" transfer-ownership="none">
|
|
<doc xml:space="preserve">the reported value</doc>
|
|
<type name="gdouble" c:type="double"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">the format string of the report message</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="..." transfer-ownership="none">
|
|
<doc xml:space="preserve">arguments to pass to the printf() function</doc>
|
|
<varargs/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_queue_destroy" c:identifier="g_test_queue_destroy" version="2.16">
|
|
<doc xml:space="preserve">This function enqueus a callback @destroy_func to be executed
|
|
during the next test case teardown phase. This is most useful
|
|
to auto destruct allocated test resources at the end of a test run.
|
|
Resources are released in reverse queue order, that means enqueueing
|
|
callback A before callback B will cause B() to be called before
|
|
A() during teardown.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="destroy_func" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">Destroy callback for teardown phase.</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
<parameter name="destroy_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">Destroy callback data.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_queue_free" c:identifier="g_test_queue_free" version="2.16">
|
|
<doc xml:space="preserve">Enqueue a pointer to be released with g_free() during the next
|
|
teardown phase. This is equivalent to calling g_test_queue_destroy()
|
|
with a destroy callback of g_free().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="gfree_pointer" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the pointer to be stored.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="test_queue_unref" c:identifier="g_test_queue_unref" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Enqueue an object to be released with g_object_unref() during
|
|
the next teardown phase. This is equivalent to calling
|
|
g_test_queue_destroy() with a destroy callback of g_object_unref().</doc>
|
|
<parameters>
|
|
<parameter name="gobject">
|
|
<doc xml:space="preserve">the object to unref</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="test_rand_double" c:identifier="g_test_rand_double" version="2.16">
|
|
<doc xml:space="preserve">Get a reproducible random floating point number,
|
|
see g_test_rand_int() for details on test case random numbers.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a random number from the seeded random number generator.</doc>
|
|
<type name="gdouble" c:type="double"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="test_rand_double_range" c:identifier="g_test_rand_double_range" version="2.16">
|
|
<doc xml:space="preserve">Get a reproducible random floating pointer number out of a specified range,
|
|
see g_test_rand_int() for details on test case random numbers.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a number with @range_start <= number < @range_end.</doc>
|
|
<type name="gdouble" c:type="double"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="range_start" transfer-ownership="none">
|
|
<doc xml:space="preserve">the minimum value returned by this function</doc>
|
|
<type name="gdouble" c:type="double"/>
|
|
</parameter>
|
|
<parameter name="range_end" transfer-ownership="none">
|
|
<doc xml:space="preserve">the minimum value not returned by this function</doc>
|
|
<type name="gdouble" c:type="double"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_rand_int" c:identifier="g_test_rand_int" version="2.16">
|
|
<doc xml:space="preserve">Get a reproducible random integer number.
|
|
|
|
The random numbers generated by the g_test_rand_*() family of functions
|
|
change with every new test program start, unless the --seed option is
|
|
given when starting test programs.
|
|
|
|
For individual test cases however, the random number generator is
|
|
reseeded, to avoid dependencies between tests and to make --seed
|
|
effective for all test cases.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a random number from the seeded random number generator.</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="test_rand_int_range" c:identifier="g_test_rand_int_range" version="2.16">
|
|
<doc xml:space="preserve">Get a reproducible random integer number out of a specified range,
|
|
see g_test_rand_int() for details on test case random numbers.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a number with @begin <= number < @end.</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="begin" transfer-ownership="none">
|
|
<doc xml:space="preserve">the minimum value returned by this function</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</parameter>
|
|
<parameter name="end" transfer-ownership="none">
|
|
<doc xml:space="preserve">the smallest value not to be returned by this function</doc>
|
|
<type name="gint32" c:type="gint32"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_run" c:identifier="g_test_run" version="2.16">
|
|
<doc xml:space="preserve">Runs all tests under the toplevel suite which can be retrieved
|
|
with g_test_get_root(). Similar to g_test_run_suite(), the test
|
|
cases to be run are filtered according to test path arguments
|
|
(`-p testpath` and `-s testpath`) as parsed by g_test_init().
|
|
g_test_run_suite() or g_test_run() may only be called once in a
|
|
program.
|
|
|
|
In general, the tests and sub-suites within each suite are run in
|
|
the order in which they are defined. However, note that prior to
|
|
GLib 2.36, there was a bug in the `g_test_add_*`
|
|
functions which caused them to create multiple suites with the same
|
|
name, meaning that if you created tests "/foo/simple",
|
|
"/bar/simple", and "/foo/using-bar" in that order, they would get
|
|
run in that order (since g_test_run() would run the first "/foo"
|
|
suite, then the "/bar" suite, then the second "/foo" suite). As of
|
|
2.36, this bug is fixed, and adding the tests in that order would
|
|
result in a running order of "/foo/simple", "/foo/using-bar",
|
|
"/bar/simple". If this new ordering is sub-optimal (because it puts
|
|
more-complicated tests before simpler ones, making it harder to
|
|
figure out exactly what has failed), you can fix it by changing the
|
|
test paths to group tests by suite in a way that will result in the
|
|
desired running order. Eg, "/simple/foo", "/simple/bar",
|
|
"/complex/foo-using-bar".
|
|
|
|
However, you should never make the actual result of a test depend
|
|
on the order that tests are run in. If you need to ensure that some
|
|
particular code runs before or after a given test case, use
|
|
g_test_add(), which lets you specify setup and teardown functions.
|
|
|
|
If all tests are skipped or marked as incomplete (expected failures),
|
|
this function will return 0 if producing TAP output, or 77 (treated
|
|
as "skip test" by Automake) otherwise.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">0 on success, 1 on failure (assuming it returns at all),
|
|
0 or 77 if all tests were skipped with g_test_skip() and/or
|
|
g_test_incomplete()</doc>
|
|
<type name="gint" c:type="int"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="test_run_suite" c:identifier="g_test_run_suite" version="2.16">
|
|
<doc xml:space="preserve">Execute the tests within @suite and all nested #GTestSuites.
|
|
The test suites to be executed are filtered according to
|
|
test path arguments (`-p testpath` and `-s testpath`) as parsed by
|
|
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.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">0 on success</doc>
|
|
<type name="gint" c:type="int"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="suite" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTestSuite</doc>
|
|
<type name="TestSuite" c:type="GTestSuite*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_set_nonfatal_assertions" c:identifier="g_test_set_nonfatal_assertions" version="2.38">
|
|
<doc xml:space="preserve">Changes the behaviour of the various `g_assert_*()` macros,
|
|
g_test_assert_expected_messages() and the various
|
|
`g_test_trap_assert_*()` macros to not abort to program, but instead
|
|
call g_test_fail() and continue. (This also changes the behavior of
|
|
g_test_fail() so that it will not cause the test program to abort
|
|
after completing the failed test.)
|
|
|
|
Note that the g_assert_not_reached() and g_assert() macros are not
|
|
affected by this.
|
|
|
|
This function can only be called after g_test_init().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="test_skip" c:identifier="g_test_skip" version="2.38">
|
|
<doc xml:space="preserve">Indicates that a test was skipped.
|
|
|
|
Calling this function will not stop the test from running, you
|
|
need to return from the test function yourself. So you can
|
|
produce additional diagnostic messages or even continue running
|
|
the test.
|
|
|
|
If not called from inside a test, this function does nothing.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="msg" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">explanation</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_subprocess" c:identifier="g_test_subprocess" version="2.38">
|
|
<doc xml:space="preserve">Returns %TRUE (after g_test_init() has been called) if the test
|
|
program is running under g_test_trap_subprocess().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the test program is running under
|
|
g_test_trap_subprocess().</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="test_summary" c:identifier="g_test_summary" version="2.62">
|
|
<doc xml:space="preserve">Set the summary for a test, which describes what the test checks, and how it
|
|
goes about checking it. This may be included in test report output, and is
|
|
useful documentation for anyone reading the source code or modifying a test
|
|
in future. It must be a single line.
|
|
|
|
This should be called at the top of a test function.
|
|
|
|
For example:
|
|
|[<!-- language="C" -->
|
|
static void
|
|
test_array_sort (void)
|
|
{
|
|
g_test_summary ("Test my_array_sort() sorts the array correctly and stably, "
|
|
"including testing zero length and one-element arrays.");
|
|
|
|
…
|
|
}
|
|
]|</doc>
|
|
<doc-version xml:space="preserve">
|
|
See also: g_test_bug()</doc-version>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="summary" transfer-ownership="none">
|
|
<doc xml:space="preserve">One or two sentences summarising what the test checks, and how it
|
|
checks it.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_timer_elapsed" c:identifier="g_test_timer_elapsed" version="2.16">
|
|
<doc xml:space="preserve">Get the time since the last start of the timer with g_test_timer_start().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the time since the last start of the timer, as a double</doc>
|
|
<type name="gdouble" c:type="double"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="test_timer_last" c:identifier="g_test_timer_last" version="2.16">
|
|
<doc xml:space="preserve">Report the last result of g_test_timer_elapsed().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the last result of g_test_timer_elapsed(), as a double</doc>
|
|
<type name="gdouble" c:type="double"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="test_timer_start" c:identifier="g_test_timer_start" version="2.16">
|
|
<doc xml:space="preserve">Start a timing test. Call g_test_timer_elapsed() when the task is supposed
|
|
to be done. Call this function again to restart the timer.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
</function>
|
|
<function-macro name="test_trap_assert_stderr" c:identifier="g_test_trap_assert_stderr" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Assert that the stderr output of the last test subprocess
|
|
matches @serrpattern. See g_test_trap_subprocess().
|
|
|
|
This is sometimes used to test situations that are formally
|
|
considered to be undefined behaviour, like code that hits a
|
|
g_assert() or g_error(). In these situations you should skip the
|
|
entire test, including the call to g_test_trap_subprocess(), unless
|
|
g_test_undefined() returns %TRUE to indicate that undefined
|
|
behaviour may be tested.</doc>
|
|
<parameters>
|
|
<parameter name="serrpattern">
|
|
<doc xml:space="preserve">a glob-style [pattern][glib-Glob-style-pattern-matching]</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="test_trap_assert_stderr_unmatched" c:identifier="g_test_trap_assert_stderr_unmatched" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Assert that the stderr output of the last test subprocess
|
|
does not match @serrpattern. See g_test_trap_subprocess().</doc>
|
|
<parameters>
|
|
<parameter name="serrpattern">
|
|
<doc xml:space="preserve">a glob-style [pattern][glib-Glob-style-pattern-matching]</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="test_trap_assert_stdout" c:identifier="g_test_trap_assert_stdout" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Assert that the stdout output of the last test subprocess matches
|
|
@soutpattern. See g_test_trap_subprocess().</doc>
|
|
<parameters>
|
|
<parameter name="soutpattern">
|
|
<doc xml:space="preserve">a glob-style [pattern][glib-Glob-style-pattern-matching]</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="test_trap_assert_stdout_unmatched" c:identifier="g_test_trap_assert_stdout_unmatched" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Assert that the stdout output of the last test subprocess
|
|
does not match @soutpattern. See g_test_trap_subprocess().</doc>
|
|
<parameters>
|
|
<parameter name="soutpattern">
|
|
<doc xml:space="preserve">a glob-style [pattern][glib-Glob-style-pattern-matching]</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="test_trap_assertions" c:identifier="g_test_trap_assertions">
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="domain" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="file" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="line" transfer-ownership="none">
|
|
<type name="gint" c:type="int"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="assertion_flags" transfer-ownership="none">
|
|
<type name="guint64" c:type="guint64"/>
|
|
</parameter>
|
|
<parameter name="pattern" transfer-ownership="none">
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_trap_fork" c:identifier="g_test_trap_fork" version="2.16" deprecated="1">
|
|
<doc xml:space="preserve">Fork the current test program to execute a test case that might
|
|
not return or that might abort.
|
|
|
|
If @usec_timeout is non-0, the forked test case is aborted and
|
|
considered failing if its run time exceeds it.
|
|
|
|
The forking behavior can be configured with the #GTestTrapFlags flags.
|
|
|
|
In the following example, the test code forks, the forked child
|
|
process produces some sample output and exits successfully.
|
|
The forking parent process then asserts successful child program
|
|
termination and validates child program outputs.
|
|
|
|
|[<!-- language="C" -->
|
|
static void
|
|
test_fork_patterns (void)
|
|
{
|
|
if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR))
|
|
{
|
|
g_print ("some stdout text: somagic17\n");
|
|
g_printerr ("some stderr text: semagic43\n");
|
|
exit (0); // successful test run
|
|
}
|
|
g_test_trap_assert_passed ();
|
|
g_test_trap_assert_stdout ("*somagic17*");
|
|
g_test_trap_assert_stderr ("*semagic43*");
|
|
}
|
|
]|</doc>
|
|
<doc-deprecated xml:space="preserve">This function is implemented only on Unix platforms,
|
|
and is not always reliable due to problems inherent in
|
|
fork-without-exec. Use g_test_trap_subprocess() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE for the forked child and %FALSE for the executing parent process.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="usec_timeout" transfer-ownership="none">
|
|
<doc xml:space="preserve">Timeout for the forked test in micro seconds.</doc>
|
|
<type name="guint64" c:type="guint64"/>
|
|
</parameter>
|
|
<parameter name="test_trap_flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">Flags to modify forking behaviour.</doc>
|
|
<type name="TestTrapFlags" c:type="GTestTrapFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="test_trap_has_passed" c:identifier="g_test_trap_has_passed" version="2.16">
|
|
<doc xml:space="preserve">Check the result of the last g_test_trap_subprocess() call.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the last test subprocess terminated successfully.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="test_trap_reached_timeout" c:identifier="g_test_trap_reached_timeout" version="2.16">
|
|
<doc xml:space="preserve">Check the result of the last g_test_trap_subprocess() call.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the last test subprocess got killed due to a timeout.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="test_trap_subprocess" c:identifier="g_test_trap_subprocess" version="2.38">
|
|
<doc xml:space="preserve">Respawns the test program to run only @test_path in a subprocess.
|
|
This can be used for a test case that might not return, or that
|
|
might abort.
|
|
|
|
If @test_path is %NULL then the same test is re-run in a subprocess.
|
|
You can use g_test_subprocess() to determine whether the test is in
|
|
a subprocess or not.
|
|
|
|
@test_path can also be the name of the parent test, followed by
|
|
"`/subprocess/`" and then a name for the specific subtest (or just
|
|
ending with "`/subprocess`" if the test only has one child test);
|
|
tests with names of this form will automatically be skipped in the
|
|
parent process.
|
|
|
|
If @usec_timeout is non-0, the test subprocess is aborted and
|
|
considered failing if its run time exceeds it.
|
|
|
|
The subprocess behavior can be configured with the
|
|
#GTestSubprocessFlags flags.
|
|
|
|
You can use methods such as g_test_trap_assert_passed(),
|
|
g_test_trap_assert_failed(), and g_test_trap_assert_stderr() to
|
|
check the results of the subprocess. (But note that
|
|
g_test_trap_assert_stdout() and g_test_trap_assert_stderr()
|
|
cannot be used if @test_flags specifies that the child should
|
|
inherit the parent stdout/stderr.)
|
|
|
|
If your `main ()` needs to behave differently in
|
|
the subprocess, you can call g_test_subprocess() (after calling
|
|
g_test_init()) to see whether you are in a subprocess.
|
|
|
|
The following example tests that calling
|
|
`my_object_new(1000000)` will abort with an error
|
|
message.
|
|
|
|
|[<!-- language="C" -->
|
|
static void
|
|
test_create_large_object (void)
|
|
{
|
|
if (g_test_subprocess ())
|
|
{
|
|
my_object_new (1000000);
|
|
return;
|
|
}
|
|
|
|
// Reruns this same test in a subprocess
|
|
g_test_trap_subprocess (NULL, 0, 0);
|
|
g_test_trap_assert_failed ();
|
|
g_test_trap_assert_stderr ("*ERROR*too large*");
|
|
}
|
|
|
|
int
|
|
main (int argc, char **argv)
|
|
{
|
|
g_test_init (&argc, &argv, NULL);
|
|
|
|
g_test_add_func ("/myobject/create_large_object",
|
|
test_create_large_object);
|
|
return g_test_run ();
|
|
}
|
|
]|</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="test_path" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">Test to run in a subprocess</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="usec_timeout" transfer-ownership="none">
|
|
<doc xml:space="preserve">Timeout for the subprocess test in micro seconds.</doc>
|
|
<type name="guint64" c:type="guint64"/>
|
|
</parameter>
|
|
<parameter name="test_flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">Flags to modify subprocess behaviour.</doc>
|
|
<type name="TestSubprocessFlags" c:type="GTestSubprocessFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="testing">
|
|
<doc xml:space="preserve">GLib provides a framework for writing and maintaining unit tests
|
|
in parallel to the code they are testing. The API is designed according
|
|
to established concepts found in the other test frameworks (JUnit, NUnit,
|
|
RUnit), which in turn is based on smalltalk unit testing concepts.
|
|
|
|
- Test case: Tests (test methods) are grouped together with their
|
|
fixture into test cases.
|
|
|
|
- Fixture: A test fixture consists of fixture data and setup and
|
|
teardown methods to establish the environment for the test
|
|
functions. We use fresh fixtures, i.e. fixtures are newly set
|
|
up and torn down around each test invocation to avoid dependencies
|
|
between tests.
|
|
|
|
- Test suite: Test cases can be grouped into test suites, to allow
|
|
subsets of the available tests to be run. Test suites can be
|
|
grouped into other test suites as well.
|
|
|
|
The API is designed to handle creation and registration of test suites
|
|
and test cases implicitly. A simple call like
|
|
|[<!-- language="C" -->
|
|
g_test_add_func ("/misc/assertions", test_assertions);
|
|
]|
|
|
creates a test suite called "misc" with a single test case named
|
|
"assertions", which consists of running the test_assertions function.
|
|
|
|
In addition to the traditional g_assert_true(), the test framework provides
|
|
an extended set of assertions for comparisons: g_assert_cmpfloat(),
|
|
g_assert_cmpfloat_with_epsilon(), g_assert_cmpint(), g_assert_cmpuint(),
|
|
g_assert_cmphex(), g_assert_cmpstr(), g_assert_cmpmem() and
|
|
g_assert_cmpvariant(). The
|
|
advantage of these variants over plain g_assert_true() is that the assertion
|
|
messages can be more elaborate, and include the values of the compared
|
|
entities.
|
|
|
|
Note that g_assert() should not be used in unit tests, since it is a no-op
|
|
when compiling with `G_DISABLE_ASSERT`. Use g_assert() in production code,
|
|
and g_assert_true() in unit tests.
|
|
|
|
A full example of creating a test suite with two tests using fixtures:
|
|
|[<!-- language="C" -->
|
|
#include <glib.h>
|
|
#include <locale.h>
|
|
|
|
typedef struct {
|
|
MyObject *obj;
|
|
OtherObject *helper;
|
|
} MyObjectFixture;
|
|
|
|
static void
|
|
my_object_fixture_set_up (MyObjectFixture *fixture,
|
|
gconstpointer user_data)
|
|
{
|
|
fixture->obj = my_object_new ();
|
|
my_object_set_prop1 (fixture->obj, "some-value");
|
|
my_object_do_some_complex_setup (fixture->obj, user_data);
|
|
|
|
fixture->helper = other_object_new ();
|
|
}
|
|
|
|
static void
|
|
my_object_fixture_tear_down (MyObjectFixture *fixture,
|
|
gconstpointer user_data)
|
|
{
|
|
g_clear_object (&fixture->helper);
|
|
g_clear_object (&fixture->obj);
|
|
}
|
|
|
|
static void
|
|
test_my_object_test1 (MyObjectFixture *fixture,
|
|
gconstpointer user_data)
|
|
{
|
|
g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "initial-value");
|
|
}
|
|
|
|
static void
|
|
test_my_object_test2 (MyObjectFixture *fixture,
|
|
gconstpointer user_data)
|
|
{
|
|
my_object_do_some_work_using_helper (fixture->obj, fixture->helper);
|
|
g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "updated-value");
|
|
}
|
|
|
|
int
|
|
main (int argc, char *argv[])
|
|
{
|
|
setlocale (LC_ALL, "");
|
|
|
|
g_test_init (&argc, &argv, NULL);
|
|
|
|
// Define the tests.
|
|
g_test_add ("/my-object/test1", MyObjectFixture, "some-user-data",
|
|
my_object_fixture_set_up, test_my_object_test1,
|
|
my_object_fixture_tear_down);
|
|
g_test_add ("/my-object/test2", MyObjectFixture, "some-user-data",
|
|
my_object_fixture_set_up, test_my_object_test2,
|
|
my_object_fixture_tear_down);
|
|
|
|
return g_test_run ();
|
|
}
|
|
]|
|
|
|
|
### Integrating GTest in your project
|
|
|
|
If you are using the [Meson](http://mesonbuild.com) build system, you will
|
|
typically use the provided `test()` primitive to call the test binaries,
|
|
e.g.:
|
|
|
|
|[<!-- language="plain" -->
|
|
test(
|
|
'foo',
|
|
executable('foo', 'foo.c', dependencies: deps),
|
|
env: [
|
|
'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()),
|
|
'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()),
|
|
],
|
|
)
|
|
|
|
test(
|
|
'bar',
|
|
executable('bar', 'bar.c', dependencies: deps),
|
|
env: [
|
|
'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()),
|
|
'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()),
|
|
],
|
|
)
|
|
]|
|
|
|
|
If you are using Autotools, you're strongly encouraged to use the Automake
|
|
[TAP](https://testanything.org/) harness; GLib provides template files for
|
|
easily integrating with it:
|
|
|
|
- [glib-tap.mk](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/glib-tap.mk)
|
|
- [tap-test](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/tap-test)
|
|
- [tap-driver.sh](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/tap-driver.sh)
|
|
|
|
You can copy these files in your own project's root directory, and then
|
|
set up your `Makefile.am` file to reference them, for instance:
|
|
|
|
|[<!-- language="plain" -->
|
|
include $(top_srcdir)/glib-tap.mk
|
|
|
|
# test binaries
|
|
test_programs = \
|
|
foo \
|
|
bar
|
|
|
|
# data distributed in the tarball
|
|
dist_test_data = \
|
|
foo.data.txt \
|
|
bar.data.txt
|
|
|
|
# data not distributed in the tarball
|
|
test_data = \
|
|
blah.data.txt
|
|
]|
|
|
|
|
Make sure to distribute the TAP files, using something like the following
|
|
in your top-level `Makefile.am`:
|
|
|
|
|[<!-- language="plain" -->
|
|
EXTRA_DIST += \
|
|
tap-driver.sh \
|
|
tap-test
|
|
]|
|
|
|
|
`glib-tap.mk` will be distributed implicitly due to being included in a
|
|
`Makefile.am`. All three files should be added to version control.
|
|
|
|
If you don't have access to the Autotools TAP harness, you can use the
|
|
[gtester][gtester] and [gtester-report][gtester-report] tools, and use
|
|
the [glib.mk](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/glib.mk)
|
|
Automake template provided by GLib. Note, however, that since GLib 2.62,
|
|
[gtester][gtester] and [gtester-report][gtester-report] have been deprecated
|
|
in favour of using TAP. The `--tap` argument to tests is enabled by default
|
|
as of GLib 2.62.</doc>
|
|
</docsection>
|
|
<function name="thread_error_quark" c:identifier="g_thread_error_quark" moved-to="Thread.error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="thread_exit" c:identifier="g_thread_exit" moved-to="Thread.exit">
|
|
<doc xml:space="preserve">Terminates the current thread.
|
|
|
|
If another thread is waiting for us using g_thread_join() then the
|
|
waiting thread will be woken up and get @retval as the return value
|
|
of g_thread_join().
|
|
|
|
Calling g_thread_exit() with a parameter @retval is equivalent to
|
|
returning @retval from the function @func, as given to g_thread_new().
|
|
|
|
You must only call g_thread_exit() from a thread that you created
|
|
yourself with g_thread_new() or related APIs. You must not call
|
|
this function from a thread created with another threading library
|
|
or or from within a #GThreadPool.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="retval" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the return value of this thread</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="thread_pool_get_max_idle_time" c:identifier="g_thread_pool_get_max_idle_time" moved-to="ThreadPool.get_max_idle_time" version="2.10">
|
|
<doc xml:space="preserve">This function will return the maximum @interval that a
|
|
thread will wait in the thread pool for new tasks before
|
|
being stopped.
|
|
|
|
If this function returns 0, threads waiting in the thread
|
|
pool for new work are not stopped.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum @interval (milliseconds) to wait
|
|
for new tasks in the thread pool before stopping the
|
|
thread</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="thread_pool_get_max_unused_threads" c:identifier="g_thread_pool_get_max_unused_threads" moved-to="ThreadPool.get_max_unused_threads">
|
|
<doc xml:space="preserve">Returns the maximal allowed number of unused threads.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximal number of unused threads</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="thread_pool_get_num_unused_threads" c:identifier="g_thread_pool_get_num_unused_threads" moved-to="ThreadPool.get_num_unused_threads">
|
|
<doc xml:space="preserve">Returns the number of currently unused threads.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of currently unused threads</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="thread_pool_set_max_idle_time" c:identifier="g_thread_pool_set_max_idle_time" moved-to="ThreadPool.set_max_idle_time" version="2.10">
|
|
<doc xml:space="preserve">This function will set the maximum @interval that a thread
|
|
waiting in the pool for new tasks can be idle for before
|
|
being stopped. This function is similar to calling
|
|
g_thread_pool_stop_unused_threads() on a regular timeout,
|
|
except this is done on a per thread basis.
|
|
|
|
By setting @interval to 0, idle threads will not be stopped.
|
|
|
|
The default value is 15000 (15 seconds).</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="interval" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum @interval (in milliseconds)
|
|
a thread can be idle</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="thread_pool_set_max_unused_threads" c:identifier="g_thread_pool_set_max_unused_threads" moved-to="ThreadPool.set_max_unused_threads">
|
|
<doc xml:space="preserve">Sets the maximal number of unused threads to @max_threads.
|
|
If @max_threads is -1, no limit is imposed on the number
|
|
of unused threads.
|
|
|
|
The default value is 2.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="max_threads" transfer-ownership="none">
|
|
<doc xml:space="preserve">maximal number of unused threads</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="thread_pool_stop_unused_threads" c:identifier="g_thread_pool_stop_unused_threads" moved-to="ThreadPool.stop_unused_threads">
|
|
<doc xml:space="preserve">Stops all currently unused threads. This does not change the
|
|
maximal number of unused threads. This function can be used to
|
|
regularly stop all unused threads e.g. from g_timeout_add().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
</function>
|
|
<docsection name="thread_pools">
|
|
<doc xml:space="preserve">Sometimes you wish to asynchronously fork out the execution of work
|
|
and continue working in your own thread. If that will happen often,
|
|
the overhead of starting and destroying a thread each time might be
|
|
too high. In such cases reusing already started threads seems like a
|
|
good idea. And it indeed is, but implementing this can be tedious
|
|
and error-prone.
|
|
|
|
Therefore GLib provides thread pools for your convenience. An added
|
|
advantage is, that the threads can be shared between the different
|
|
subsystems of your program, when they are using GLib.
|
|
|
|
To create a new thread pool, you use g_thread_pool_new().
|
|
It is destroyed by g_thread_pool_free().
|
|
|
|
If you want to execute a certain task within a thread pool,
|
|
you call g_thread_pool_push().
|
|
|
|
To get the current number of running threads you call
|
|
g_thread_pool_get_num_threads(). To get the number of still
|
|
unprocessed tasks you call g_thread_pool_unprocessed(). To control
|
|
the maximal number of threads for a thread pool, you use
|
|
g_thread_pool_get_max_threads() and g_thread_pool_set_max_threads().
|
|
|
|
Finally you can control the number of unused threads, that are kept
|
|
alive by GLib for future use. The current number can be fetched with
|
|
g_thread_pool_get_num_unused_threads(). The maximal number can be
|
|
controlled by g_thread_pool_get_max_unused_threads() and
|
|
g_thread_pool_set_max_unused_threads(). All currently unused threads
|
|
can be stopped by calling g_thread_pool_stop_unused_threads().</doc>
|
|
</docsection>
|
|
<function name="thread_self" c:identifier="g_thread_self" moved-to="Thread.self">
|
|
<doc xml:space="preserve">This function returns the #GThread corresponding to the
|
|
current thread. Note that this function does not increase
|
|
the reference count of the returned struct.
|
|
|
|
This function will return a #GThread even for threads that
|
|
were not created by GLib (i.e. those created by other threading
|
|
APIs). This may be useful for thread identification purposes
|
|
(i.e. comparisons) but you must not use GLib functions (such
|
|
as g_thread_join()) on these threads.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GThread representing the current thread</doc>
|
|
<type name="Thread" c:type="GThread*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="thread_yield" c:identifier="g_thread_yield" moved-to="Thread.yield">
|
|
<doc xml:space="preserve">Causes the calling thread to voluntarily relinquish the CPU, so
|
|
that other threads can run.
|
|
|
|
This function is often used as a method to make busy wait less evil.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
</function>
|
|
<docsection name="threads">
|
|
<doc xml:space="preserve">Threads act almost like processes, but unlike processes all threads
|
|
of one process share the same memory. This is good, as it provides
|
|
easy communication between the involved threads via this shared
|
|
memory, and it is bad, because strange things (so called
|
|
"Heisenbugs") might happen if the program is not carefully designed.
|
|
In particular, due to the concurrent nature of threads, no
|
|
assumptions on the order of execution of code running in different
|
|
threads can be made, unless order is explicitly forced by the
|
|
programmer through synchronization primitives.
|
|
|
|
The aim of the thread-related functions in GLib is to provide a
|
|
portable means for writing multi-threaded software. There are
|
|
primitives for mutexes to protect the access to portions of memory
|
|
(#GMutex, #GRecMutex and #GRWLock). There is a facility to use
|
|
individual bits for locks (g_bit_lock()). There are primitives
|
|
for condition variables to allow synchronization of threads (#GCond).
|
|
There are primitives for thread-private data - data that every
|
|
thread has a private instance of (#GPrivate). There are facilities
|
|
for one-time initialization (#GOnce, g_once_init_enter()). Finally,
|
|
there are primitives to create and manage threads (#GThread).
|
|
|
|
The GLib threading system used to be initialized with g_thread_init().
|
|
This is no longer necessary. Since version 2.32, the GLib threading
|
|
system is automatically initialized at the start of your program,
|
|
and all thread-creation functions and synchronization primitives
|
|
are available right away.
|
|
|
|
Note that it is not safe to assume that your program has no threads
|
|
even if you don't call g_thread_new() yourself. GLib and GIO can
|
|
and will create threads for their own purposes in some cases, such
|
|
as when using g_unix_signal_source_new() or when using GDBus.
|
|
|
|
Originally, UNIX did not have threads, and therefore some traditional
|
|
UNIX APIs are problematic in threaded programs. Some notable examples
|
|
are
|
|
|
|
- C library functions that return data in statically allocated
|
|
buffers, such as strtok() or strerror(). For many of these,
|
|
there are thread-safe variants with a _r suffix, or you can
|
|
look at corresponding GLib APIs (like g_strsplit() or g_strerror()).
|
|
|
|
- The functions setenv() and unsetenv() manipulate the process
|
|
environment in a not thread-safe way, and may interfere with getenv()
|
|
calls in other threads. Note that getenv() calls may be hidden behind
|
|
other APIs. For example, GNU gettext() calls getenv() under the
|
|
covers. In general, it is best to treat the environment as readonly.
|
|
If you absolutely have to modify the environment, do it early in
|
|
main(), when no other threads are around yet.
|
|
|
|
- The setlocale() function changes the locale for the entire process,
|
|
affecting all threads. Temporary changes to the locale are often made
|
|
to change the behavior of string scanning or formatting functions
|
|
like scanf() or printf(). GLib offers a number of string APIs
|
|
(like g_ascii_formatd() or g_ascii_strtod()) that can often be
|
|
used as an alternative. Or you can use the uselocale() function
|
|
to change the locale only for the current thread.
|
|
|
|
- The fork() function only takes the calling thread into the child's
|
|
copy of the process image. If other threads were executing in critical
|
|
sections they could have left mutexes locked which could easily
|
|
cause deadlocks in the new child. For this reason, you should
|
|
call exit() or exec() as soon as possible in the child and only
|
|
make signal-safe library calls before that.
|
|
|
|
- The daemon() function uses fork() in a way contrary to what is
|
|
described above. It should not be used with GLib programs.
|
|
|
|
GLib itself is internally completely thread-safe (all global data is
|
|
automatically locked), but individual data structure instances are
|
|
not automatically locked for performance reasons. For example,
|
|
you must coordinate accesses to the same #GHashTable from multiple
|
|
threads. The two notable exceptions from this rule are #GMainLoop
|
|
and #GAsyncQueue, which are thread-safe and need no further
|
|
application-level locking to be accessed from multiple threads.
|
|
Most refcounting functions such as g_object_ref() are also thread-safe.
|
|
|
|
A common use for #GThreads is to move a long-running blocking operation out
|
|
of the main thread and into a worker thread. For GLib functions, such as
|
|
single GIO operations, this is not necessary, and complicates the code.
|
|
Instead, the `…_async()` version of the function should be used from the main
|
|
thread, eliminating the need for locking and synchronisation between multiple
|
|
threads. If an operation does need to be moved to a worker thread, consider
|
|
using g_task_run_in_thread(), or a #GThreadPool. #GThreadPool is often a
|
|
better choice than #GThread, as it handles thread reuse and task queueing;
|
|
#GTask uses this internally.
|
|
|
|
However, if multiple blocking operations need to be performed in sequence,
|
|
and it is not possible to use #GTask for them, moving them to a worker thread
|
|
can clarify the code.</doc>
|
|
</docsection>
|
|
<function name="time_val_from_iso8601" c:identifier="g_time_val_from_iso8601" moved-to="TimeVal.from_iso8601" version="2.12" deprecated="1" deprecated-version="2.62">
|
|
<doc xml:space="preserve">Converts a string containing an ISO 8601 encoded date and time
|
|
to a #GTimeVal and puts it into @time_.
|
|
|
|
@iso_date must include year, month, day, hours, minutes, and
|
|
seconds. It can optionally include fractions of a second and a time
|
|
zone indicator. (In the absence of any time zone indication, the
|
|
timestamp is assumed to be in local time.)
|
|
|
|
Any leading or trailing space in @iso_date is ignored.
|
|
|
|
This function was deprecated, along with #GTimeVal itself, in GLib 2.62.
|
|
Equivalent functionality is available using code like:
|
|
|[
|
|
GDateTime *dt = g_date_time_new_from_iso8601 (iso8601_string, NULL);
|
|
gint64 time_val = g_date_time_to_unix (dt);
|
|
g_date_time_unref (dt);
|
|
]|</doc>
|
|
<doc-deprecated xml:space="preserve">#GTimeVal is not year-2038-safe. Use
|
|
g_date_time_new_from_iso8601() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the conversion was successful.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="iso_date" transfer-ownership="none">
|
|
<doc xml:space="preserve">an ISO 8601 encoded date string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="time_" direction="out" caller-allocates="1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTimeVal</doc>
|
|
<type name="TimeVal" c:type="GTimeVal*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="timeout_add" c:identifier="g_timeout_add" shadowed-by="timeout_add_full" introspectable="0">
|
|
<doc xml:space="preserve">Sets a function to be called at regular intervals, with the default
|
|
priority, #G_PRIORITY_DEFAULT. The function is called repeatedly
|
|
until it returns %FALSE, at which point the timeout is automatically
|
|
destroyed and the function will not be called again. The first call
|
|
to the function will be at the end of the first @interval.
|
|
|
|
Note that timeout functions may be delayed, due to the processing of other
|
|
event sources. Thus they should not be relied on for precise timing.
|
|
After each call to the timeout function, the time of the next
|
|
timeout is recalculated based on the current time and the given interval
|
|
(it does not try to 'catch up' time lost in delays).
|
|
|
|
See [memory management of sources][mainloop-memory-management] for details
|
|
on how to handle the return value and memory management of @data.
|
|
|
|
If you want to have a timer in the "seconds" range and do not care
|
|
about the exact time of the first call of the timer, use the
|
|
g_timeout_add_seconds() function; this function allows for more
|
|
optimizations and more efficient system power usage.
|
|
|
|
This internally creates a main loop source using g_timeout_source_new()
|
|
and attaches it to the global #GMainContext using g_source_attach(), so
|
|
the callback will be invoked in whichever thread is running that main
|
|
context. You can do these steps manually if you need greater control or to
|
|
use a custom main context.
|
|
|
|
It is safe to call this function from any thread.
|
|
|
|
The interval given is in terms of monotonic time, not wall clock
|
|
time. See g_get_monotonic_time().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the ID (greater than 0) of the event source.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="interval" transfer-ownership="none">
|
|
<doc xml:space="preserve">the time between calls to the function, in milliseconds
|
|
(1/1000ths of a second)</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="function" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">function to call</doc>
|
|
<type name="SourceFunc" c:type="GSourceFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="timeout_add_full" c:identifier="g_timeout_add_full" shadows="timeout_add">
|
|
<doc xml:space="preserve">Sets a function to be called at regular intervals, with the given
|
|
priority. The function is called repeatedly until it returns
|
|
%FALSE, at which point the timeout is automatically destroyed and
|
|
the function will not be called again. The @notify function is
|
|
called when the timeout is destroyed. The first call to the
|
|
function will be at the end of the first @interval.
|
|
|
|
Note that timeout functions may be delayed, due to the processing of other
|
|
event sources. Thus they should not be relied on for precise timing.
|
|
After each call to the timeout function, the time of the next
|
|
timeout is recalculated based on the current time and the given interval
|
|
(it does not try to 'catch up' time lost in delays).
|
|
|
|
See [memory management of sources][mainloop-memory-management] for details
|
|
on how to handle the return value and memory management of @data.
|
|
|
|
This internally creates a main loop source using g_timeout_source_new()
|
|
and attaches it to the global #GMainContext using g_source_attach(), so
|
|
the callback will be invoked in whichever thread is running that main
|
|
context. You can do these steps manually if you need greater control or to
|
|
use a custom main context.
|
|
|
|
The interval given is in terms of monotonic time, not wall clock time.
|
|
See g_get_monotonic_time().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the ID (greater than 0) of the event source.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="priority" transfer-ownership="none">
|
|
<doc xml:space="preserve">the priority of the timeout source. Typically this will be in
|
|
the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="interval" transfer-ownership="none">
|
|
<doc xml:space="preserve">the time between calls to the function, in milliseconds
|
|
(1/1000ths of a second)</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="function" transfer-ownership="none" scope="notified" closure="3" destroy="4">
|
|
<doc xml:space="preserve">function to call</doc>
|
|
<type name="SourceFunc" c:type="GSourceFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">function to call when the timeout is removed, or %NULL</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="timeout_add_seconds" c:identifier="g_timeout_add_seconds" shadowed-by="timeout_add_seconds_full" version="2.14" introspectable="0">
|
|
<doc xml:space="preserve">Sets a function to be called at regular intervals with the default
|
|
priority, #G_PRIORITY_DEFAULT. The function is called repeatedly until
|
|
it returns %FALSE, at which point the timeout is automatically destroyed
|
|
and the function will not be called again.
|
|
|
|
This internally creates a main loop source using
|
|
g_timeout_source_new_seconds() and attaches it to the main loop context
|
|
using g_source_attach(). You can do these steps manually if you need
|
|
greater control. Also see g_timeout_add_seconds_full().
|
|
|
|
It is safe to call this function from any thread.
|
|
|
|
Note that the first call of the timer may not be precise for timeouts
|
|
of one second. If you need finer precision and have such a timeout,
|
|
you may want to use g_timeout_add() instead.
|
|
|
|
See [memory management of sources][mainloop-memory-management] for details
|
|
on how to handle the return value and memory management of @data.
|
|
|
|
The interval given is in terms of monotonic time, not wall clock
|
|
time. See g_get_monotonic_time().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the ID (greater than 0) of the event source.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="interval" transfer-ownership="none">
|
|
<doc xml:space="preserve">the time between calls to the function, in seconds</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="function" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">function to call</doc>
|
|
<type name="SourceFunc" c:type="GSourceFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="timeout_add_seconds_full" c:identifier="g_timeout_add_seconds_full" shadows="timeout_add_seconds" version="2.14">
|
|
<doc xml:space="preserve">Sets a function to be called at regular intervals, with @priority.
|
|
The function is called repeatedly until it returns %FALSE, at which
|
|
point the timeout is automatically destroyed and the function will
|
|
not be called again.
|
|
|
|
Unlike g_timeout_add(), this function operates at whole second granularity.
|
|
The initial starting point of the timer is determined by the implementation
|
|
and the implementation is expected to group multiple timers together so that
|
|
they fire all at the same time.
|
|
To allow this grouping, the @interval to the first timer is rounded
|
|
and can deviate up to one second from the specified interval.
|
|
Subsequent timer iterations will generally run at the specified interval.
|
|
|
|
Note that timeout functions may be delayed, due to the processing of other
|
|
event sources. Thus they should not be relied on for precise timing.
|
|
After each call to the timeout function, the time of the next
|
|
timeout is recalculated based on the current time and the given @interval
|
|
|
|
See [memory management of sources][mainloop-memory-management] for details
|
|
on how to handle the return value and memory management of @data.
|
|
|
|
If you want timing more precise than whole seconds, use g_timeout_add()
|
|
instead.
|
|
|
|
The grouping of timers to fire at the same time results in a more power
|
|
and CPU efficient behavior so if your timer is in multiples of seconds
|
|
and you don't require the first timer exactly one second from now, the
|
|
use of g_timeout_add_seconds() is preferred over g_timeout_add().
|
|
|
|
This internally creates a main loop source using
|
|
g_timeout_source_new_seconds() and attaches it to the main loop context
|
|
using g_source_attach(). You can do these steps manually if you need
|
|
greater control.
|
|
|
|
It is safe to call this function from any thread.
|
|
|
|
The interval given is in terms of monotonic time, not wall clock
|
|
time. See g_get_monotonic_time().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the ID (greater than 0) of the event source.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="priority" transfer-ownership="none">
|
|
<doc xml:space="preserve">the priority of the timeout source. Typically this will be in
|
|
the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="interval" transfer-ownership="none">
|
|
<doc xml:space="preserve">the time between calls to the function, in seconds</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
<parameter name="function" transfer-ownership="none" scope="notified" closure="3" destroy="4">
|
|
<doc xml:space="preserve">function to call</doc>
|
|
<type name="SourceFunc" c:type="GSourceFunc"/>
|
|
</parameter>
|
|
<parameter name="data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="notify" transfer-ownership="none" nullable="1" allow-none="1" scope="async">
|
|
<doc xml:space="preserve">function to call when the timeout is removed, or %NULL</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="timeout_source_new" c:identifier="g_timeout_source_new">
|
|
<doc xml:space="preserve">Creates a new timeout source.
|
|
|
|
The source will not initially be associated with any #GMainContext
|
|
and must be added to one with g_source_attach() before it will be
|
|
executed.
|
|
|
|
The interval given is in terms of monotonic time, not wall clock
|
|
time. See g_get_monotonic_time().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the newly-created timeout source</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="interval" transfer-ownership="none">
|
|
<doc xml:space="preserve">the timeout interval in milliseconds.</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="timeout_source_new_seconds" c:identifier="g_timeout_source_new_seconds" version="2.14">
|
|
<doc xml:space="preserve">Creates a new timeout source.
|
|
|
|
The source will not initially be associated with any #GMainContext
|
|
and must be added to one with g_source_attach() before it will be
|
|
executed.
|
|
|
|
The scheduling granularity/accuracy of this timeout source will be
|
|
in seconds.
|
|
|
|
The interval given is in terms of monotonic time, not wall clock time.
|
|
See g_get_monotonic_time().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the newly-created timeout source</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="interval" transfer-ownership="none">
|
|
<doc xml:space="preserve">the timeout interval in seconds</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="timers">
|
|
<doc xml:space="preserve">#GTimer records a start time, and counts microseconds elapsed since
|
|
that time. This is done somewhat differently on different platforms,
|
|
and can be tricky to get exactly right, so #GTimer provides a
|
|
portable/convenient interface.</doc>
|
|
</docsection>
|
|
<docsection name="timezone">
|
|
<doc xml:space="preserve">#GTimeZone is a structure that represents a time zone, at no
|
|
particular point in time. It is refcounted and immutable.
|
|
|
|
Each time zone has an identifier (for example, ‘Europe/London’) which is
|
|
platform dependent. See g_time_zone_new() for information on the identifier
|
|
formats. The identifier of a time zone can be retrieved using
|
|
g_time_zone_get_identifier().
|
|
|
|
A time zone contains a number of intervals. Each interval has
|
|
an abbreviation to describe it (for example, ‘PDT’), an offset to UTC and a
|
|
flag indicating if the daylight savings time is in effect during that
|
|
interval. A time zone always has at least one interval — interval 0. Note
|
|
that interval abbreviations are not the same as time zone identifiers
|
|
(apart from ‘UTC’), and cannot be passed to g_time_zone_new().
|
|
|
|
Every UTC time is contained within exactly one interval, but a given
|
|
local time may be contained within zero, one or two intervals (due to
|
|
incontinuities associated with daylight savings time).
|
|
|
|
An interval may refer to a specific period of time (eg: the duration
|
|
of daylight savings time during 2010) or it may refer to many periods
|
|
of time that share the same properties (eg: all periods of daylight
|
|
savings time). It is also possible (usually for political reasons)
|
|
that some properties (like the abbreviation) change between intervals
|
|
without other properties changing.
|
|
|
|
#GTimeZone is available since GLib 2.26.</doc>
|
|
</docsection>
|
|
<docsection name="trash_stack">
|
|
<doc xml:space="preserve">A #GTrashStack is an efficient way to keep a stack of unused allocated
|
|
memory chunks. Each memory chunk is required to be large enough to hold
|
|
a #gpointer. This allows the stack to be maintained without any space
|
|
overhead, since the stack pointers can be stored inside the memory chunks.
|
|
|
|
There is no function to create a #GTrashStack. A %NULL #GTrashStack*
|
|
is a perfectly valid empty stack.
|
|
|
|
There is no longer any good reason to use #GTrashStack. If you have
|
|
extra pieces of memory, free() them and allocate them again later.</doc>
|
|
</docsection>
|
|
<function name="trash_stack_height" c:identifier="g_trash_stack_height" moved-to="TrashStack.height" deprecated="1" deprecated-version="2.48">
|
|
<doc xml:space="preserve">Returns the height of a #GTrashStack.
|
|
|
|
Note that execution of this function is of O(N) complexity
|
|
where N denotes the number of items on the stack.</doc>
|
|
<doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the height of the stack</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="stack_p" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTrashStack</doc>
|
|
<type name="TrashStack" c:type="GTrashStack**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="trash_stack_peek" c:identifier="g_trash_stack_peek" moved-to="TrashStack.peek" deprecated="1" deprecated-version="2.48">
|
|
<doc xml:space="preserve">Returns the element at the top of a #GTrashStack
|
|
which may be %NULL.</doc>
|
|
<doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the element at the top of the stack</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="stack_p" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTrashStack</doc>
|
|
<type name="TrashStack" c:type="GTrashStack**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="trash_stack_pop" c:identifier="g_trash_stack_pop" moved-to="TrashStack.pop" deprecated="1" deprecated-version="2.48">
|
|
<doc xml:space="preserve">Pops a piece of memory off a #GTrashStack.</doc>
|
|
<doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the element at the top of the stack</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="stack_p" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTrashStack</doc>
|
|
<type name="TrashStack" c:type="GTrashStack**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="trash_stack_push" c:identifier="g_trash_stack_push" moved-to="TrashStack.push" deprecated="1" deprecated-version="2.48">
|
|
<doc xml:space="preserve">Pushes a piece of memory onto a #GTrashStack.</doc>
|
|
<doc-deprecated xml:space="preserve">#GTrashStack is deprecated without replacement</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="stack_p" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GTrashStack</doc>
|
|
<type name="TrashStack" c:type="GTrashStack**"/>
|
|
</parameter>
|
|
<parameter name="data_p" transfer-ownership="none">
|
|
<doc xml:space="preserve">the piece of memory to push on the stack</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="treesbinary">
|
|
<doc xml:space="preserve">The #GTree structure and its associated functions provide a sorted
|
|
collection of key/value pairs optimized for searching and traversing
|
|
in order. This means that most of the operations (access, search,
|
|
insertion, deletion, ...) on #GTree are O(log(n)) in average and O(n)
|
|
in worst case for time complexity. But, note that maintaining a
|
|
balanced sorted #GTree of n elements is done in time O(n log(n)).
|
|
|
|
To create a new #GTree use g_tree_new().
|
|
|
|
To insert a key/value pair into a #GTree use g_tree_insert()
|
|
(O(n log(n))).
|
|
|
|
To remove a key/value pair use g_tree_remove() (O(n log(n))).
|
|
|
|
To look up the value corresponding to a given key, use
|
|
g_tree_lookup() and g_tree_lookup_extended().
|
|
|
|
To find out the number of nodes in a #GTree, use g_tree_nnodes(). To
|
|
get the height of a #GTree, use g_tree_height().
|
|
|
|
To traverse a #GTree, calling a function for each node visited in
|
|
the traversal, use g_tree_foreach().
|
|
|
|
To destroy a #GTree, use g_tree_destroy().</doc>
|
|
</docsection>
|
|
<docsection name="treesnary">
|
|
<doc xml:space="preserve">The #GNode struct and its associated functions provide a N-ary tree
|
|
data structure, where nodes in the tree can contain arbitrary data.
|
|
|
|
To create a new tree use g_node_new().
|
|
|
|
To insert a node into a tree use g_node_insert(),
|
|
g_node_insert_before(), g_node_append() and g_node_prepend().
|
|
|
|
To create a new node and insert it into a tree use
|
|
g_node_insert_data(), g_node_insert_data_after(),
|
|
g_node_insert_data_before(), g_node_append_data()
|
|
and g_node_prepend_data().
|
|
|
|
To reverse the children of a node use g_node_reverse_children().
|
|
|
|
To find a node use g_node_get_root(), g_node_find(),
|
|
g_node_find_child(), g_node_child_index(), g_node_child_position(),
|
|
g_node_first_child(), g_node_last_child(), g_node_nth_child(),
|
|
g_node_first_sibling(), g_node_prev_sibling(), g_node_next_sibling()
|
|
or g_node_last_sibling().
|
|
|
|
To get information about a node or tree use G_NODE_IS_LEAF(),
|
|
G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(),
|
|
g_node_n_children(), g_node_is_ancestor() or g_node_max_height().
|
|
|
|
To traverse a tree, calling a function for each node visited in the
|
|
traversal, use g_node_traverse() or g_node_children_foreach().
|
|
|
|
To remove a node or subtree from a tree use g_node_unlink() or
|
|
g_node_destroy().</doc>
|
|
</docsection>
|
|
<function name="try_malloc" c:identifier="g_try_malloc">
|
|
<doc xml:space="preserve">Attempts to allocate @n_bytes, and returns %NULL on failure.
|
|
Contrast with g_malloc(), which aborts the program on failure.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the allocated memory, or %NULL.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="n_bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of bytes to allocate.</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="try_malloc0" c:identifier="g_try_malloc0" version="2.8">
|
|
<doc xml:space="preserve">Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on
|
|
failure. Contrast with g_malloc0(), which aborts the program on failure.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the allocated memory, or %NULL</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="n_bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of bytes to allocate</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="try_malloc0_n" c:identifier="g_try_malloc0_n" version="2.24">
|
|
<doc xml:space="preserve">This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes,
|
|
but care is taken to detect possible overflow during multiplication.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the allocated memory, or %NULL</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="n_blocks" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of blocks to allocate</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="n_block_bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of each block in bytes</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="try_malloc_n" c:identifier="g_try_malloc_n" version="2.24">
|
|
<doc xml:space="preserve">This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes,
|
|
but care is taken to detect possible overflow during multiplication.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the allocated memory, or %NULL.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="n_blocks" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of blocks to allocate</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="n_block_bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of each block in bytes</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="try_new" c:identifier="g_try_new" version="2.8" introspectable="0">
|
|
<doc xml:space="preserve">Attempts to allocate @n_structs elements of type @struct_type, and returns
|
|
%NULL on failure. Contrast with g_new(), which aborts the program on failure.
|
|
The returned pointer is cast to a pointer to the given type.
|
|
The function returns %NULL when @n_structs is 0 of if an overflow occurs.</doc>
|
|
<parameters>
|
|
<parameter name="struct_type">
|
|
<doc xml:space="preserve">the type of the elements to allocate</doc>
|
|
</parameter>
|
|
<parameter name="n_structs">
|
|
<doc xml:space="preserve">the number of elements to allocate</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="try_new0" c:identifier="g_try_new0" version="2.8" introspectable="0">
|
|
<doc xml:space="preserve">Attempts to allocate @n_structs elements of type @struct_type, initialized
|
|
to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts
|
|
the program on failure.
|
|
The returned pointer is cast to a pointer to the given type.
|
|
The function returns %NULL when @n_structs is 0 or if an overflow occurs.</doc>
|
|
<parameters>
|
|
<parameter name="struct_type">
|
|
<doc xml:space="preserve">the type of the elements to allocate</doc>
|
|
</parameter>
|
|
<parameter name="n_structs">
|
|
<doc xml:space="preserve">the number of elements to allocate</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="try_realloc" c:identifier="g_try_realloc">
|
|
<doc xml:space="preserve">Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL
|
|
on failure. Contrast with g_realloc(), which aborts the program
|
|
on failure.
|
|
|
|
If @mem is %NULL, behaves the same as g_try_malloc().</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the allocated memory, or %NULL.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mem" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">previously-allocated memory, or %NULL.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="n_bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of bytes to allocate.</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="try_realloc_n" c:identifier="g_try_realloc_n" version="2.24">
|
|
<doc xml:space="preserve">This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes,
|
|
but care is taken to detect possible overflow during multiplication.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">the allocated memory, or %NULL.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="mem" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">previously-allocated memory, or %NULL.</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="n_blocks" transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of blocks to allocate</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="n_block_bytes" transfer-ownership="none">
|
|
<doc xml:space="preserve">the size of each block in bytes</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="try_renew" c:identifier="g_try_renew" version="2.8" introspectable="0">
|
|
<doc xml:space="preserve">Attempts to reallocate the memory pointed to by @mem, so that it now has
|
|
space for @n_structs elements of type @struct_type, and returns %NULL on
|
|
failure. Contrast with g_renew(), which aborts the program on failure.
|
|
It returns the new address of the memory, which may have been moved.
|
|
The function returns %NULL if an overflow occurs.</doc>
|
|
<parameters>
|
|
<parameter name="struct_type">
|
|
<doc xml:space="preserve">the type of the elements to allocate</doc>
|
|
</parameter>
|
|
<parameter name="mem">
|
|
<doc xml:space="preserve">the currently allocated memory</doc>
|
|
</parameter>
|
|
<parameter name="n_structs">
|
|
<doc xml:space="preserve">the number of elements to allocate</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<docsection name="type_conversion">
|
|
<doc xml:space="preserve">Many times GLib, GTK+, and other libraries allow you to pass "user
|
|
data" to a callback, in the form of a void pointer. From time to time
|
|
you want to pass an integer instead of a pointer. You could allocate
|
|
an integer, with something like:
|
|
|[<!-- language="C" -->
|
|
int *ip = g_new (int, 1);
|
|
*ip = 42;
|
|
]|
|
|
But this is inconvenient, and it's annoying to have to free the
|
|
memory at some later time.
|
|
|
|
Pointers are always at least 32 bits in size (on all platforms GLib
|
|
intends to support). Thus you can store at least 32-bit integer values
|
|
in a pointer value. Naively, you might try this, but it's incorrect:
|
|
|[<!-- language="C" -->
|
|
gpointer p;
|
|
int i;
|
|
p = (void*) 42;
|
|
i = (int) p;
|
|
]|
|
|
Again, that example was not correct, don't copy it.
|
|
The problem is that on some systems you need to do this:
|
|
|[<!-- language="C" -->
|
|
gpointer p;
|
|
int i;
|
|
p = (void*) (long) 42;
|
|
i = (int) (long) p;
|
|
]|
|
|
The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care
|
|
to do the right thing on every platform.
|
|
|
|
Warning: You may not store pointers in integers. This is not
|
|
portable in any way, shape or form. These macros only allow storing
|
|
integers in pointers, and only preserve 32 bits of the integer; values
|
|
outside the range of a 32-bit integer will be mangled.</doc>
|
|
</docsection>
|
|
<docsection name="types">
|
|
<doc xml:space="preserve">GLib defines a number of commonly used types, which can be divided
|
|
into several groups:
|
|
- New types which are not part of standard C (but are defined in
|
|
various C standard library header files) — #gboolean, #gssize.
|
|
- Integer types which are guaranteed to be the same size across
|
|
all platforms — #gint8, #guint8, #gint16, #guint16, #gint32,
|
|
#guint32, #gint64, #guint64.
|
|
- Types which are easier to use than their standard C counterparts -
|
|
#gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong.
|
|
- Types which correspond exactly to standard C types, but are
|
|
included for completeness — #gchar, #gint, #gshort, #glong,
|
|
#gfloat, #gdouble.
|
|
- Types which correspond exactly to standard C99 types, but are available
|
|
to use even if your compiler does not support C99 — #gsize, #goffset,
|
|
#gintptr, #guintptr.
|
|
|
|
GLib also defines macros for the limits of some of the standard
|
|
integer and floating point types, as well as macros for suitable
|
|
printf() formats for these types.
|
|
|
|
Note that depending on the platform and build configuration, the format
|
|
macros might not be compatible with the system provided printf() function,
|
|
because GLib might use a different printf() implementation internally.
|
|
The format macros will always work with GLib API (like g_print()), and with
|
|
any C99 compatible printf() implementation.</doc>
|
|
</docsection>
|
|
<function name="ucs4_to_utf16" c:identifier="g_ucs4_to_utf16" throws="1">
|
|
<doc xml:space="preserve">Convert a string from UCS-4 to UTF-16. A 0 character will be
|
|
added to the result after the converted text.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to a newly allocated UTF-16 string.
|
|
This value must be freed with g_free(). If an error occurs,
|
|
%NULL will be returned and @error set.</doc>
|
|
<type name="guint16" c:type="gunichar2*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UCS-4 encoded string</doc>
|
|
<type name="gunichar" c:type="const gunichar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum length (number of characters) of @str to use.
|
|
If @len < 0, then the string is nul-terminated.</doc>
|
|
<type name="glong" c:type="glong"/>
|
|
</parameter>
|
|
<parameter name="items_read" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store number of
|
|
bytes read, or %NULL. If an error occurs then the index of the invalid
|
|
input is stored here.</doc>
|
|
<type name="glong" c:type="glong*"/>
|
|
</parameter>
|
|
<parameter name="items_written" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store number
|
|
of #gunichar2 written, or %NULL. The value stored here does not include
|
|
the trailing 0.</doc>
|
|
<type name="glong" c:type="glong*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="ucs4_to_utf8" c:identifier="g_ucs4_to_utf8" throws="1">
|
|
<doc xml:space="preserve">Convert a string from a 32-bit fixed width representation as UCS-4.
|
|
to UTF-8. The result will be terminated with a 0 byte.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to a newly allocated UTF-8 string.
|
|
This value must be freed with g_free(). If an error occurs,
|
|
%NULL will be returned and @error set. In that case, @items_read
|
|
will be set to the position of the first invalid input character.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UCS-4 encoded string</doc>
|
|
<type name="gunichar" c:type="const gunichar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum length (number of characters) of @str to use.
|
|
If @len < 0, then the string is nul-terminated.</doc>
|
|
<type name="glong" c:type="glong"/>
|
|
</parameter>
|
|
<parameter name="items_read" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store number of
|
|
characters read, or %NULL.</doc>
|
|
<type name="glong" c:type="glong*"/>
|
|
</parameter>
|
|
<parameter name="items_written" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store number
|
|
of bytes written or %NULL. The value here stored does not include the
|
|
trailing 0 byte.</doc>
|
|
<type name="glong" c:type="glong*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="uint64_checked_add" c:identifier="g_uint64_checked_add" version="2.48" introspectable="0">
|
|
<doc xml:space="preserve">Performs a checked addition of @a and @b, storing the result in
|
|
@dest.
|
|
|
|
If the operation is successful, %TRUE is returned. If the operation
|
|
overflows then the state of @dest is undefined and %FALSE is
|
|
returned.</doc>
|
|
<parameters>
|
|
<parameter name="dest">
|
|
<doc xml:space="preserve">a pointer to the #guint64 destination</doc>
|
|
</parameter>
|
|
<parameter name="a">
|
|
<doc xml:space="preserve">the #guint64 left operand</doc>
|
|
</parameter>
|
|
<parameter name="b">
|
|
<doc xml:space="preserve">the #guint64 right operand</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="uint64_checked_mul" c:identifier="g_uint64_checked_mul" version="2.48" introspectable="0">
|
|
<doc xml:space="preserve">Performs a checked multiplication of @a and @b, storing the result in
|
|
@dest.
|
|
|
|
If the operation is successful, %TRUE is returned. If the operation
|
|
overflows then the state of @dest is undefined and %FALSE is
|
|
returned.</doc>
|
|
<parameters>
|
|
<parameter name="dest">
|
|
<doc xml:space="preserve">a pointer to the #guint64 destination</doc>
|
|
</parameter>
|
|
<parameter name="a">
|
|
<doc xml:space="preserve">the #guint64 left operand</doc>
|
|
</parameter>
|
|
<parameter name="b">
|
|
<doc xml:space="preserve">the #guint64 right operand</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="uint_checked_add" c:identifier="g_uint_checked_add" version="2.48" introspectable="0">
|
|
<doc xml:space="preserve">Performs a checked addition of @a and @b, storing the result in
|
|
@dest.
|
|
|
|
If the operation is successful, %TRUE is returned. If the operation
|
|
overflows then the state of @dest is undefined and %FALSE is
|
|
returned.</doc>
|
|
<parameters>
|
|
<parameter name="dest">
|
|
<doc xml:space="preserve">a pointer to the #guint destination</doc>
|
|
</parameter>
|
|
<parameter name="a">
|
|
<doc xml:space="preserve">the #guint left operand</doc>
|
|
</parameter>
|
|
<parameter name="b">
|
|
<doc xml:space="preserve">the #guint right operand</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function-macro name="uint_checked_mul" c:identifier="g_uint_checked_mul" version="2.48" introspectable="0">
|
|
<doc xml:space="preserve">Performs a checked multiplication of @a and @b, storing the result in
|
|
@dest.
|
|
|
|
If the operation is successful, %TRUE is returned. If the operation
|
|
overflows then the state of @dest is undefined and %FALSE is
|
|
returned.</doc>
|
|
<parameters>
|
|
<parameter name="dest">
|
|
<doc xml:space="preserve">a pointer to the #guint destination</doc>
|
|
</parameter>
|
|
<parameter name="a">
|
|
<doc xml:space="preserve">the #guint left operand</doc>
|
|
</parameter>
|
|
<parameter name="b">
|
|
<doc xml:space="preserve">the #guint right operand</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="unichar_break_type" c:identifier="g_unichar_break_type">
|
|
<doc xml:space="preserve">Determines the break type of @c. @c should be a Unicode character
|
|
(to derive a character from UTF-8 encoded text, use
|
|
g_utf8_get_char()). The break type is used to find word and line
|
|
breaks ("text boundaries"), Pango implements the Unicode boundary
|
|
resolution algorithms and normally you would use a function such
|
|
as pango_break() instead of caring about break types yourself.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the break type of @c</doc>
|
|
<type name="UnicodeBreakType" c:type="GUnicodeBreakType"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_combining_class" c:identifier="g_unichar_combining_class" version="2.14">
|
|
<doc xml:space="preserve">Determines the canonical combining class of a Unicode character.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the combining class of the character</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uc" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_compose" c:identifier="g_unichar_compose" version="2.30">
|
|
<doc xml:space="preserve">Performs a single composition step of the
|
|
Unicode canonical composition algorithm.
|
|
|
|
This function includes algorithmic Hangul Jamo composition,
|
|
but it is not exactly the inverse of g_unichar_decompose().
|
|
No composition can have either of @a or @b equal to zero.
|
|
To be precise, this function composes if and only if
|
|
there exists a Primary Composite P which is canonically
|
|
equivalent to the sequence <@a,@b>. See the Unicode
|
|
Standard for the definition of Primary Composite.
|
|
|
|
If @a and @b do not compose a new character, @ch is set to zero.
|
|
|
|
See
|
|
[UAX#15](http://unicode.org/reports/tr15/)
|
|
for details.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the characters could be composed</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="a" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
<parameter name="b" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
<parameter name="ch" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">return location for the composed character</doc>
|
|
<type name="gunichar" c:type="gunichar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_decompose" c:identifier="g_unichar_decompose" version="2.30">
|
|
<doc xml:space="preserve">Performs a single decomposition step of the
|
|
Unicode canonical decomposition algorithm.
|
|
|
|
This function does not include compatibility
|
|
decompositions. It does, however, include algorithmic
|
|
Hangul Jamo decomposition, as well as 'singleton'
|
|
decompositions which replace a character by a single
|
|
other character. In the case of singletons *@b will
|
|
be set to zero.
|
|
|
|
If @ch is not decomposable, *@a is set to @ch and *@b
|
|
is set to zero.
|
|
|
|
Note that the way Unicode decomposition pairs are
|
|
defined, it is guaranteed that @b would not decompose
|
|
further, but @a may itself decompose. To get the full
|
|
canonical decomposition for @ch, one would need to
|
|
recursively call this function on @a. Or use
|
|
g_unichar_fully_decompose().
|
|
|
|
See
|
|
[UAX#15](http://unicode.org/reports/tr15/)
|
|
for details.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the character could be decomposed</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="ch" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
<parameter name="a" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">return location for the first component of @ch</doc>
|
|
<type name="gunichar" c:type="gunichar*"/>
|
|
</parameter>
|
|
<parameter name="b" direction="out" caller-allocates="0" transfer-ownership="full">
|
|
<doc xml:space="preserve">return location for the second component of @ch</doc>
|
|
<type name="gunichar" c:type="gunichar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_digit_value" c:identifier="g_unichar_digit_value">
|
|
<doc xml:space="preserve">Determines the numeric value of a character as a decimal
|
|
digit.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">If @c is a decimal digit (according to
|
|
g_unichar_isdigit()), its numeric value. Otherwise, -1.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_fully_decompose" c:identifier="g_unichar_fully_decompose" version="2.30">
|
|
<doc xml:space="preserve">Computes the canonical or compatibility decomposition of a
|
|
Unicode character. For compatibility decomposition,
|
|
pass %TRUE for @compat; for canonical decomposition
|
|
pass %FALSE for @compat.
|
|
|
|
The decomposed sequence is placed in @result. Only up to
|
|
@result_len characters are written into @result. The length
|
|
of the full decomposition (irrespective of @result_len) is
|
|
returned by the function. For canonical decomposition,
|
|
currently all decompositions are of length at most 4, but
|
|
this may change in the future (very unlikely though).
|
|
At any rate, Unicode does guarantee that a buffer of length
|
|
18 is always enough for both compatibility and canonical
|
|
decompositions, so that is the size recommended. This is provided
|
|
as %G_UNICHAR_MAX_DECOMPOSITION_LENGTH.
|
|
|
|
See
|
|
[UAX#15](http://unicode.org/reports/tr15/)
|
|
for details.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the full decomposition.</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="ch" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character.</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
<parameter name="compat" transfer-ownership="none">
|
|
<doc xml:space="preserve">whether perform canonical or compatibility decomposition</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
<parameter name="result" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store decomposed result, or %NULL</doc>
|
|
<type name="gunichar" c:type="gunichar*"/>
|
|
</parameter>
|
|
<parameter name="result_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @result</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_get_mirror_char" c:identifier="g_unichar_get_mirror_char" version="2.4">
|
|
<doc xml:space="preserve">In Unicode, some characters are "mirrored". This means that their
|
|
images are mirrored horizontally in text that is laid out from right
|
|
to left. For instance, "(" would become its mirror image, ")", in
|
|
right-to-left text.
|
|
|
|
If @ch has the Unicode mirrored property and there is another unicode
|
|
character that typically has a glyph that is the mirror image of @ch's
|
|
glyph and @mirrored_ch is set, it puts that character in the address
|
|
pointed to by @mirrored_ch. Otherwise the original character is put.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @ch has a mirrored character, %FALSE otherwise</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="ch" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
<parameter name="mirrored_ch" transfer-ownership="none">
|
|
<doc xml:space="preserve">location to store the mirrored character</doc>
|
|
<type name="gunichar" c:type="gunichar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_get_script" c:identifier="g_unichar_get_script" version="2.14">
|
|
<doc xml:space="preserve">Looks up the #GUnicodeScript for a particular character (as defined
|
|
by Unicode Standard Annex \#24). No check is made for @ch being a
|
|
valid Unicode character; if you pass in invalid character, the
|
|
result is undefined.
|
|
|
|
This function is equivalent to pango_script_for_unichar() and the
|
|
two are interchangeable.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the #GUnicodeScript for the character.</doc>
|
|
<type name="UnicodeScript" c:type="GUnicodeScript"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="ch" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_isalnum" c:identifier="g_unichar_isalnum">
|
|
<doc xml:space="preserve">Determines whether a character is alphanumeric.
|
|
Given some UTF-8 text, obtain a character value
|
|
with g_utf8_get_char().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @c is an alphanumeric character</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_isalpha" c:identifier="g_unichar_isalpha">
|
|
<doc xml:space="preserve">Determines whether a character is alphabetic (i.e. a letter).
|
|
Given some UTF-8 text, obtain a character value with
|
|
g_utf8_get_char().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @c is an alphabetic character</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_iscntrl" c:identifier="g_unichar_iscntrl">
|
|
<doc xml:space="preserve">Determines whether a character is a control character.
|
|
Given some UTF-8 text, obtain a character value with
|
|
g_utf8_get_char().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @c is a control character</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_isdefined" c:identifier="g_unichar_isdefined">
|
|
<doc xml:space="preserve">Determines if a given character is assigned in the Unicode
|
|
standard.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the character has an assigned value</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_isdigit" c:identifier="g_unichar_isdigit">
|
|
<doc xml:space="preserve">Determines whether a character is numeric (i.e. a digit). This
|
|
covers ASCII 0-9 and also digits in other languages/scripts. Given
|
|
some UTF-8 text, obtain a character value with g_utf8_get_char().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @c is a digit</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_isgraph" c:identifier="g_unichar_isgraph">
|
|
<doc xml:space="preserve">Determines whether a character is printable and not a space
|
|
(returns %FALSE for control characters, format characters, and
|
|
spaces). g_unichar_isprint() is similar, but returns %TRUE for
|
|
spaces. Given some UTF-8 text, obtain a character value with
|
|
g_utf8_get_char().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @c is printable unless it's a space</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_islower" c:identifier="g_unichar_islower">
|
|
<doc xml:space="preserve">Determines whether a character is a lowercase letter.
|
|
Given some UTF-8 text, obtain a character value with
|
|
g_utf8_get_char().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @c is a lowercase letter</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_ismark" c:identifier="g_unichar_ismark" version="2.14">
|
|
<doc xml:space="preserve">Determines whether a character is a mark (non-spacing mark,
|
|
combining mark, or enclosing mark in Unicode speak).
|
|
Given some UTF-8 text, obtain a character value
|
|
with g_utf8_get_char().
|
|
|
|
Note: in most cases where isalpha characters are allowed,
|
|
ismark characters should be allowed to as they are essential
|
|
for writing most European languages as well as many non-Latin
|
|
scripts.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @c is a mark character</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_isprint" c:identifier="g_unichar_isprint">
|
|
<doc xml:space="preserve">Determines whether a character is printable.
|
|
Unlike g_unichar_isgraph(), returns %TRUE for spaces.
|
|
Given some UTF-8 text, obtain a character value with
|
|
g_utf8_get_char().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @c is printable</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_ispunct" c:identifier="g_unichar_ispunct">
|
|
<doc xml:space="preserve">Determines whether a character is punctuation or a symbol.
|
|
Given some UTF-8 text, obtain a character value with
|
|
g_utf8_get_char().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @c is a punctuation or symbol character</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_isspace" c:identifier="g_unichar_isspace">
|
|
<doc xml:space="preserve">Determines whether a character is a space, tab, or line separator
|
|
(newline, carriage return, etc.). Given some UTF-8 text, obtain a
|
|
character value with g_utf8_get_char().
|
|
|
|
(Note: don't use this to do word breaking; you have to use
|
|
Pango or equivalent to get word breaking right, the algorithm
|
|
is fairly complex.)</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @c is a space character</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_istitle" c:identifier="g_unichar_istitle">
|
|
<doc xml:space="preserve">Determines if a character is titlecase. Some characters in
|
|
Unicode which are composites, such as the DZ digraph
|
|
have three case variants instead of just two. The titlecase
|
|
form is used at the beginning of a word where only the
|
|
first letter is capitalized. The titlecase form of the DZ
|
|
digraph is U+01F2 LATIN CAPITAL LETTTER D WITH SMALL LETTER Z.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the character is titlecase</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_isupper" c:identifier="g_unichar_isupper">
|
|
<doc xml:space="preserve">Determines if a character is uppercase.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @c is an uppercase character</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_iswide" c:identifier="g_unichar_iswide">
|
|
<doc xml:space="preserve">Determines if a character is typically rendered in a double-width
|
|
cell.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the character is wide</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_iswide_cjk" c:identifier="g_unichar_iswide_cjk" version="2.12">
|
|
<doc xml:space="preserve">Determines if a character is typically rendered in a double-width
|
|
cell under legacy East Asian locales. If a character is wide according to
|
|
g_unichar_iswide(), then it is also reported wide with this function, but
|
|
the converse is not necessarily true. See the
|
|
[Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/)
|
|
for details.
|
|
|
|
If a character passes the g_unichar_iswide() test then it will also pass
|
|
this test, but not the other way around. Note that some characters may
|
|
pass both this test and g_unichar_iszerowidth().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the character is wide in legacy East Asian locales</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_isxdigit" c:identifier="g_unichar_isxdigit">
|
|
<doc xml:space="preserve">Determines if a character is a hexadecimal digit.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the character is a hexadecimal digit</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character.</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_iszerowidth" c:identifier="g_unichar_iszerowidth" version="2.14">
|
|
<doc xml:space="preserve">Determines if a given character typically takes zero width when rendered.
|
|
The return value is %TRUE for all non-spacing and enclosing marks
|
|
(e.g., combining accents), format characters, zero-width
|
|
space, but not U+00AD SOFT HYPHEN.
|
|
|
|
A typical use of this function is with one of g_unichar_iswide() or
|
|
g_unichar_iswide_cjk() to determine the number of cells a string occupies
|
|
when displayed on a grid display (terminals). However, note that not all
|
|
terminals support zero-width rendering of zero-width marks.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the character has zero width</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_to_utf8" c:identifier="g_unichar_to_utf8">
|
|
<doc xml:space="preserve">Converts a single character to UTF-8.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">number of bytes written</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character code</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
<parameter name="outbuf" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">output buffer, must have at
|
|
least 6 bytes of space. If %NULL, the length will be computed and
|
|
returned and nothing will be written to @outbuf.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_tolower" c:identifier="g_unichar_tolower">
|
|
<doc xml:space="preserve">Converts a character to lower case.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the result of converting @c to lower case.
|
|
If @c is not an upperlower or titlecase character,
|
|
or has no lowercase equivalent @c is returned unchanged.</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character.</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_totitle" c:identifier="g_unichar_totitle">
|
|
<doc xml:space="preserve">Converts a character to the titlecase.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the result of converting @c to titlecase.
|
|
If @c is not an uppercase or lowercase character,
|
|
@c is returned unchanged.</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_toupper" c:identifier="g_unichar_toupper">
|
|
<doc xml:space="preserve">Converts a character to uppercase.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the result of converting @c to uppercase.
|
|
If @c is not a lowercase or titlecase character,
|
|
or has no upper case equivalent @c is returned unchanged.</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_type" c:identifier="g_unichar_type">
|
|
<doc xml:space="preserve">Classifies a Unicode character by type.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the type of the character.</doc>
|
|
<type name="UnicodeType" c:type="GUnicodeType"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_validate" c:identifier="g_unichar_validate">
|
|
<doc xml:space="preserve">Checks whether @ch is a valid Unicode character. Some possible
|
|
integer values of @ch will not be valid. 0 is considered a valid
|
|
character, though it's normally a string terminator.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @ch is a valid Unicode character</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="ch" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unichar_xdigit_value" c:identifier="g_unichar_xdigit_value">
|
|
<doc xml:space="preserve">Determines the numeric value of a character as a hexadecimal
|
|
digit.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">If @c is a hex digit (according to
|
|
g_unichar_isxdigit()), its numeric value. Otherwise, -1.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="unicode">
|
|
<doc xml:space="preserve">This section describes a number of functions for dealing with
|
|
Unicode characters and strings. There are analogues of the
|
|
traditional `ctype.h` character classification and case conversion
|
|
functions, UTF-8 analogues of some string utility functions,
|
|
functions to perform normalization, case conversion and collation
|
|
on UTF-8 strings and finally functions to convert between the UTF-8,
|
|
UTF-16 and UCS-4 encodings of Unicode.
|
|
|
|
The implementations of the Unicode functions in GLib are based
|
|
on the Unicode Character Data tables, which are available from
|
|
[www.unicode.org](http://www.unicode.org/).
|
|
|
|
* Unicode 4.0 was added in GLib 2.8
|
|
* Unicode 4.1 was added in GLib 2.10
|
|
* Unicode 5.0 was added in GLib 2.12
|
|
* Unicode 5.1 was added in GLib 2.16.3
|
|
* Unicode 6.0 was added in GLib 2.30
|
|
* Unicode 6.1 was added in GLib 2.32
|
|
* Unicode 6.2 was added in GLib 2.36
|
|
* Unicode 6.3 was added in GLib 2.40
|
|
* Unicode 7.0 was added in GLib 2.42
|
|
* Unicode 8.0 was added in GLib 2.48
|
|
* Unicode 9.0 was added in GLib 2.50.1
|
|
* Unicode 10.0 was added in GLib 2.54
|
|
* Unicode 11.10 was added in GLib 2.58
|
|
* Unicode 12.0 was added in GLib 2.62
|
|
* Unicode 12.1 was added in GLib 2.62
|
|
* Unicode 13.0 was added in GLib 2.66</doc>
|
|
</docsection>
|
|
<function name="unicode_canonical_decomposition" c:identifier="g_unicode_canonical_decomposition" deprecated="1" deprecated-version="2.30">
|
|
<doc xml:space="preserve">Computes the canonical decomposition of a Unicode character.</doc>
|
|
<doc-deprecated xml:space="preserve">Use the more flexible g_unichar_fully_decompose()
|
|
instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a newly allocated string of Unicode characters.
|
|
@result_len is set to the resulting length of the string.</doc>
|
|
<type name="gunichar" c:type="gunichar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="ch" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character.</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
<parameter name="result_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">location to store the length of the return value.</doc>
|
|
<type name="gsize" c:type="gsize*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unicode_canonical_ordering" c:identifier="g_unicode_canonical_ordering">
|
|
<doc xml:space="preserve">Computes the canonical ordering of a string in-place.
|
|
This rearranges decomposed characters in the string
|
|
according to their combining classes. See the Unicode
|
|
manual for more information.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UCS-4 encoded string.</doc>
|
|
<type name="gunichar" c:type="gunichar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum length of @string to use.</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unicode_script_from_iso15924" c:identifier="g_unicode_script_from_iso15924" version="2.30">
|
|
<doc xml:space="preserve">Looks up the Unicode script for @iso15924. ISO 15924 assigns four-letter
|
|
codes to scripts. For example, the code for Arabic is 'Arab'.
|
|
This function accepts four letter codes encoded as a @guint32 in a
|
|
big-endian fashion. That is, the code expected for Arabic is
|
|
0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
|
|
|
|
See
|
|
[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
|
|
for details.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the Unicode script for @iso15924, or
|
|
of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and
|
|
%G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown.</doc>
|
|
<type name="UnicodeScript" c:type="GUnicodeScript"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="iso15924" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode script</doc>
|
|
<type name="guint32" c:type="guint32"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unicode_script_to_iso15924" c:identifier="g_unicode_script_to_iso15924" version="2.30">
|
|
<doc xml:space="preserve">Looks up the ISO 15924 code for @script. ISO 15924 assigns four-letter
|
|
codes to scripts. For example, the code for Arabic is 'Arab'. The
|
|
four letter codes are encoded as a @guint32 by this function in a
|
|
big-endian fashion. That is, the code returned for Arabic is
|
|
0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
|
|
|
|
See
|
|
[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
|
|
for details.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the ISO 15924 code for @script, encoded as an integer,
|
|
of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or
|
|
ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood.</doc>
|
|
<type name="guint32" c:type="guint32"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="script" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode script</doc>
|
|
<type name="UnicodeScript" c:type="GUnicodeScript"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unix_error_quark" c:identifier="g_unix_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="unix_fd_add" c:identifier="g_unix_fd_add" version="2.36" introspectable="0">
|
|
<doc xml:space="preserve">Sets a function to be called when the IO condition, as specified by
|
|
@condition becomes true for @fd.
|
|
|
|
@function will be called when the specified IO condition becomes
|
|
%TRUE. The function is expected to clear whatever event caused the
|
|
IO condition to become true and return %TRUE in order to be notified
|
|
when it happens again. If @function returns %FALSE then the watch
|
|
will be cancelled.
|
|
|
|
The return value of this function can be passed to g_source_remove()
|
|
to cancel the watch at any time that it exists.
|
|
|
|
The source will never close the fd -- you must do it yourself.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the ID (greater than 0) of the event source</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">a file descriptor</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="condition" transfer-ownership="none">
|
|
<doc xml:space="preserve">IO conditions to watch for on @fd</doc>
|
|
<type name="IOCondition" c:type="GIOCondition"/>
|
|
</parameter>
|
|
<parameter name="function" transfer-ownership="none" closure="3">
|
|
<doc xml:space="preserve">a #GUnixFDSourceFunc</doc>
|
|
<type name="UnixFDSourceFunc" c:type="GUnixFDSourceFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unix_fd_add_full" c:identifier="g_unix_fd_add_full" version="2.36">
|
|
<doc xml:space="preserve">Sets a function to be called when the IO condition, as specified by
|
|
@condition becomes true for @fd.
|
|
|
|
This is the same as g_unix_fd_add(), except that it allows you to
|
|
specify a non-default priority and a provide a #GDestroyNotify for
|
|
@user_data.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the ID (greater than 0) of the event source</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="priority" transfer-ownership="none">
|
|
<doc xml:space="preserve">the priority of the source</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">a file descriptor</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="condition" transfer-ownership="none">
|
|
<doc xml:space="preserve">IO conditions to watch for on @fd</doc>
|
|
<type name="IOCondition" c:type="GIOCondition"/>
|
|
</parameter>
|
|
<parameter name="function" transfer-ownership="none" scope="notified" closure="4" destroy="5">
|
|
<doc xml:space="preserve">a #GUnixFDSourceFunc</doc>
|
|
<type name="UnixFDSourceFunc" c:type="GUnixFDSourceFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">data to pass to @function</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="notify" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">function to call when the idle is removed, or %NULL</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unix_fd_source_new" c:identifier="g_unix_fd_source_new" version="2.36">
|
|
<doc xml:space="preserve">Creates a #GSource to watch for a particular IO condition on a file
|
|
descriptor.
|
|
|
|
The source will never close the fd -- you must do it yourself.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the newly created #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">a file descriptor</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="condition" transfer-ownership="none">
|
|
<doc xml:space="preserve">IO conditions to watch for on @fd</doc>
|
|
<type name="IOCondition" c:type="GIOCondition"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unix_get_passwd_entry" c:identifier="g_unix_get_passwd_entry" version="2.64" throws="1">
|
|
<doc xml:space="preserve">Get the `passwd` file entry for the given @user_name using `getpwnam_r()`.
|
|
This can fail if the given @user_name doesn’t exist.
|
|
|
|
The returned `struct passwd` has been allocated using g_malloc() and should
|
|
be freed using g_free(). The strings referenced by the returned struct are
|
|
included in the same allocation, so are valid until the `struct passwd` is
|
|
freed.
|
|
|
|
This function is safe to call from multiple threads concurrently.
|
|
|
|
You will need to include `pwd.h` to get the definition of `struct passwd`.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">passwd entry, or %NULL on error; free the returned
|
|
value with g_free()</doc>
|
|
<type name="gpointer" c:type="passwd*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="user_name" transfer-ownership="none">
|
|
<doc xml:space="preserve">the username to get the passwd file entry for</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unix_open_pipe" c:identifier="g_unix_open_pipe" version="2.30" throws="1">
|
|
<doc xml:space="preserve">Similar to the UNIX pipe() call, but on modern systems like Linux
|
|
uses the pipe2() system call, which atomically creates a pipe with
|
|
the configured flags. The only supported flag currently is
|
|
%FD_CLOEXEC. If for example you want to configure %O_NONBLOCK, that
|
|
must still be done separately with fcntl().
|
|
|
|
This function does not take %O_CLOEXEC, it takes %FD_CLOEXEC as if
|
|
for fcntl(); these are different on Linux/glibc.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE on success, %FALSE if not (and errno will be set).</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="fds" transfer-ownership="none">
|
|
<doc xml:space="preserve">Array of two integers</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">Bitfield of file descriptor flags, as for fcntl()</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unix_set_fd_nonblocking" c:identifier="g_unix_set_fd_nonblocking" version="2.30" throws="1">
|
|
<doc xml:space="preserve">Control the non-blocking state of the given file descriptor,
|
|
according to @nonblock. On most systems this uses %O_NONBLOCK, but
|
|
on some older ones may use %O_NDELAY.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if successful</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="fd" transfer-ownership="none">
|
|
<doc xml:space="preserve">A file descriptor</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="nonblock" transfer-ownership="none">
|
|
<doc xml:space="preserve">If %TRUE, set the descriptor to be non-blocking</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unix_signal_add" c:identifier="g_unix_signal_add" shadowed-by="unix_signal_add_full" version="2.30" introspectable="0">
|
|
<doc xml:space="preserve">A convenience function for g_unix_signal_source_new(), which
|
|
attaches to the default #GMainContext. You can remove the watch
|
|
using g_source_remove().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">An ID (greater than 0) for the event source</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="signum" transfer-ownership="none">
|
|
<doc xml:space="preserve">Signal number</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="handler" transfer-ownership="none" closure="2">
|
|
<doc xml:space="preserve">Callback</doc>
|
|
<type name="SourceFunc" c:type="GSourceFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">Data for @handler</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unix_signal_add_full" c:identifier="g_unix_signal_add_full" shadows="unix_signal_add" version="2.30">
|
|
<doc xml:space="preserve">A convenience function for g_unix_signal_source_new(), which
|
|
attaches to the default #GMainContext. You can remove the watch
|
|
using g_source_remove().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">An ID (greater than 0) for the event source</doc>
|
|
<type name="guint" c:type="guint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="priority" transfer-ownership="none">
|
|
<doc xml:space="preserve">the priority of the signal source. Typically this will be in
|
|
the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="signum" transfer-ownership="none">
|
|
<doc xml:space="preserve">Signal number</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="handler" transfer-ownership="none" scope="notified" closure="3" destroy="4">
|
|
<doc xml:space="preserve">Callback</doc>
|
|
<type name="SourceFunc" c:type="GSourceFunc"/>
|
|
</parameter>
|
|
<parameter name="user_data" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">Data for @handler</doc>
|
|
<type name="gpointer" c:type="gpointer"/>
|
|
</parameter>
|
|
<parameter name="notify" transfer-ownership="none" scope="async">
|
|
<doc xml:space="preserve">#GDestroyNotify for @handler</doc>
|
|
<type name="DestroyNotify" c:type="GDestroyNotify"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unix_signal_source_new" c:identifier="g_unix_signal_source_new" version="2.30">
|
|
<doc xml:space="preserve">Create a #GSource that will be dispatched upon delivery of the UNIX
|
|
signal @signum. In GLib versions before 2.36, only `SIGHUP`, `SIGINT`,
|
|
`SIGTERM` can be monitored. In GLib 2.36, `SIGUSR1` and `SIGUSR2`
|
|
were added. In GLib 2.54, `SIGWINCH` was added.
|
|
|
|
Note that unlike the UNIX default, all sources which have created a
|
|
watch will be dispatched, regardless of which underlying thread
|
|
invoked g_unix_signal_source_new().
|
|
|
|
For example, an effective use of this function is to handle `SIGTERM`
|
|
cleanly; flushing any outstanding files, and then calling
|
|
g_main_loop_quit (). It is not safe to do any of this a regular
|
|
UNIX signal handler; your handler may be invoked while malloc() or
|
|
another library function is running, causing reentrancy if you
|
|
attempt to use it from the handler. None of the GLib/GObject API
|
|
is safe against this kind of reentrancy.
|
|
|
|
The interaction of this source when combined with native UNIX
|
|
functions like sigprocmask() is not defined.
|
|
|
|
The source will not initially be associated with any #GMainContext
|
|
and must be added to one with g_source_attach() before it will be
|
|
executed.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">A newly created #GSource</doc>
|
|
<type name="Source" c:type="GSource*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="signum" transfer-ownership="none">
|
|
<doc xml:space="preserve">A signal number</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unlink" c:identifier="g_unlink" version="2.6">
|
|
<doc xml:space="preserve">A wrapper for the POSIX unlink() function. The unlink() function
|
|
deletes a name from the filesystem. If this was the last link to the
|
|
file and no processes have it opened, the diskspace occupied by the
|
|
file is freed.
|
|
|
|
See your C library manual for more details about unlink(). Note
|
|
that on Windows, it is in general not possible to delete files that
|
|
are open to some process, or mapped into memory.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">0 if the name was successfully deleted, -1 if an error
|
|
occurred</doc>
|
|
<type name="gint" c:type="int"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="filename" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pathname in the GLib file name encoding
|
|
(UTF-8 on Windows)</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="unsetenv" c:identifier="g_unsetenv" version="2.4">
|
|
<doc xml:space="preserve">Removes an environment variable from the environment.
|
|
|
|
Note that on some systems, when variables are overwritten, the
|
|
memory used for the previous variables and its value isn't reclaimed.
|
|
|
|
You should be mindful of the fact that environment variable handling
|
|
in UNIX is not thread-safe, and your program may crash if one thread
|
|
calls g_unsetenv() while another thread is calling getenv(). (And note
|
|
that many functions, such as gettext(), call getenv() internally.) This
|
|
function is only safe to use at the very start of your program, before
|
|
creating any other threads (or creating objects that create worker
|
|
threads of their own).
|
|
|
|
If you need to set up the environment for a child process, you can
|
|
use g_get_environ() to get an environment array, modify that with
|
|
g_environ_setenv() and g_environ_unsetenv(), and then pass that
|
|
array directly to execvpe(), g_spawn_async(), or the like.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="variable" transfer-ownership="none">
|
|
<doc xml:space="preserve">the environment variable to remove, must
|
|
not contain '='</doc>
|
|
<type name="filename" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_build" c:identifier="g_uri_build" moved-to="Uri.build" version="2.66">
|
|
<doc xml:space="preserve">Creates a new #GUri from the given components according to @flags.
|
|
|
|
See also g_uri_build_with_user(), which allows specifying the
|
|
components of the "userinfo" separately.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags describing how to build the #GUri</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
<parameter name="scheme" transfer-ownership="none">
|
|
<doc xml:space="preserve">the URI scheme</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="userinfo" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the userinfo component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="host" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the host component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="port" transfer-ownership="none">
|
|
<doc xml:space="preserve">the port, or `-1`</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="path" transfer-ownership="none">
|
|
<doc xml:space="preserve">the path component</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="query" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the query component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="fragment" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the fragment, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_build_with_user" c:identifier="g_uri_build_with_user" moved-to="Uri.build_with_user" version="2.66">
|
|
<doc xml:space="preserve">Creates a new #GUri from the given components according to @flags
|
|
(%G_URI_FLAGS_HAS_PASSWORD is added unconditionally). The @flags must be
|
|
coherent with the passed values, in particular use `%`-encoded values with
|
|
%G_URI_FLAGS_ENCODED.
|
|
|
|
In contrast to g_uri_build(), this allows specifying the components
|
|
of the ‘userinfo’ field separately. Note that @user must be non-%NULL
|
|
if either @password or @auth_params is non-%NULL.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GUri</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags describing how to build the #GUri</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
<parameter name="scheme" transfer-ownership="none">
|
|
<doc xml:space="preserve">the URI scheme</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="user" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the user component of the userinfo, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="password" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the password component of the userinfo, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="auth_params" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the auth params of the userinfo, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="host" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the host component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="port" transfer-ownership="none">
|
|
<doc xml:space="preserve">the port, or `-1`</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="path" transfer-ownership="none">
|
|
<doc xml:space="preserve">the path component</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="query" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the query component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="fragment" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the fragment, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_error_quark" c:identifier="g_uri_error_quark" moved-to="Uri.error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="uri_escape_bytes" c:identifier="g_uri_escape_bytes" moved-to="Uri.escape_bytes" version="2.66">
|
|
<doc xml:space="preserve">Escapes arbitrary data for use in a URI.
|
|
|
|
Normally all characters that are not ‘unreserved’ (i.e. ASCII
|
|
alphanumerical characters plus dash, dot, underscore and tilde) are
|
|
escaped. But if you specify characters in @reserved_chars_allowed
|
|
they are not escaped. This is useful for the ‘reserved’ characters
|
|
in the URI specification, since those are allowed unescaped in some
|
|
portions of a URI.
|
|
|
|
Though technically incorrect, this will also allow escaping nul
|
|
bytes as `%``00`.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an escaped version of @unescaped. The returned
|
|
string should be freed when no longer needed.</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="unescaped" transfer-ownership="none">
|
|
<doc xml:space="preserve">the unescaped input data.</doc>
|
|
<array length="1" zero-terminated="0" c:type="const guint8*">
|
|
<type name="guint8" c:type="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @unescaped</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="reserved_chars_allowed" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string of reserved
|
|
characters that are allowed to be used, or %NULL.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_escape_string" c:identifier="g_uri_escape_string" moved-to="Uri.escape_string" version="2.16">
|
|
<doc xml:space="preserve">Escapes a string for use in a URI.
|
|
|
|
Normally all characters that are not "unreserved" (i.e. ASCII
|
|
alphanumerical characters plus dash, dot, underscore and tilde) are
|
|
escaped. But if you specify characters in @reserved_chars_allowed
|
|
they are not escaped. This is useful for the "reserved" characters
|
|
in the URI specification, since those are allowed unescaped in some
|
|
portions of a URI.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an escaped version of @unescaped. The returned string
|
|
should be freed when no longer needed.</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="unescaped" transfer-ownership="none">
|
|
<doc xml:space="preserve">the unescaped input string.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="reserved_chars_allowed" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string of reserved
|
|
characters that are allowed to be used, or %NULL.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="allow_utf8" transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the result can include UTF-8 characters.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_is_valid" c:identifier="g_uri_is_valid" moved-to="Uri.is_valid" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Parses @uri_string according to @flags, to determine whether it is a valid
|
|
[absolute URI][relative-absolute-uris], i.e. it does not need to be resolved
|
|
relative to another URI using g_uri_parse_relative().
|
|
|
|
If it’s not a valid URI, an error is returned explaining how it’s invalid.
|
|
|
|
See g_uri_split(), and the definition of #GUriFlags, for more
|
|
information on the effect of @flags.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @uri_string is a valid absolute URI, %FALSE on error.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string containing an absolute URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags for parsing @uri_string</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_join" c:identifier="g_uri_join" moved-to="Uri.join" version="2.66">
|
|
<doc xml:space="preserve">Joins the given components together according to @flags to create
|
|
an absolute URI string. @path may not be %NULL (though it may be the empty
|
|
string).
|
|
|
|
When @host is present, @path must either be empty or begin with a slash (`/`)
|
|
character. When @host is not present, @path cannot begin with two slash
|
|
characters (`//`). See
|
|
[RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3).
|
|
|
|
See also g_uri_join_with_user(), which allows specifying the
|
|
components of the ‘userinfo’ separately.
|
|
|
|
%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set
|
|
in @flags.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an absolute URI string</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags describing how to build the URI string</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
<parameter name="scheme" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the URI scheme, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="userinfo" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the userinfo component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="host" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the host component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="port" transfer-ownership="none">
|
|
<doc xml:space="preserve">the port, or `-1`</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="path" transfer-ownership="none">
|
|
<doc xml:space="preserve">the path component</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="query" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the query component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="fragment" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the fragment, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_join_with_user" c:identifier="g_uri_join_with_user" moved-to="Uri.join_with_user" version="2.66">
|
|
<doc xml:space="preserve">Joins the given components together according to @flags to create
|
|
an absolute URI string. @path may not be %NULL (though it may be the empty
|
|
string).
|
|
|
|
In contrast to g_uri_join(), this allows specifying the components
|
|
of the ‘userinfo’ separately. It otherwise behaves the same.
|
|
|
|
%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set
|
|
in @flags.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an absolute URI string</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags describing how to build the URI string</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
<parameter name="scheme" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the URI scheme, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="user" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the user component of the userinfo, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="password" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the password component of the userinfo, or
|
|
%NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="auth_params" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the auth params of the userinfo, or
|
|
%NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="host" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the host component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="port" transfer-ownership="none">
|
|
<doc xml:space="preserve">the port, or `-1`</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</parameter>
|
|
<parameter name="path" transfer-ownership="none">
|
|
<doc xml:space="preserve">the path component</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="query" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the query component, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="fragment" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the fragment, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_list_extract_uris" c:identifier="g_uri_list_extract_uris" moved-to="Uri.list_extract_uris" version="2.6">
|
|
<doc xml:space="preserve">Splits an URI list conforming to the text/uri-list
|
|
mime type defined in RFC 2483 into individual URIs,
|
|
discarding any comments. The URIs are not validated.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated %NULL-terminated list
|
|
of strings holding the individual URIs. The array should be freed
|
|
with g_strfreev().</doc>
|
|
<array c:type="gchar**">
|
|
<type name="utf8"/>
|
|
</array>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri_list" transfer-ownership="none">
|
|
<doc xml:space="preserve">an URI list</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_parse" c:identifier="g_uri_parse" moved-to="Uri.parse" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Parses @uri_string according to @flags. If the result is not a
|
|
valid [absolute URI][relative-absolute-uris], it will be discarded, and an
|
|
error returned.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a new #GUri.</doc>
|
|
<type name="Uri" c:type="GUri*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string representing an absolute URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags describing how to parse @uri_string</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_parse_params" c:identifier="g_uri_parse_params" moved-to="Uri.parse_params" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Many URI schemes include one or more attribute/value pairs as part of the URI
|
|
value. This method can be used to parse them into a hash table. When an
|
|
attribute has multiple occurrences, the last value is the final returned
|
|
value. If you need to handle repeated attributes differently, use
|
|
#GUriParamsIter.
|
|
|
|
The @params string is assumed to still be `%`-encoded, but the returned
|
|
values will be fully decoded. (Thus it is possible that the returned values
|
|
may contain `=` or @separators, if the value was encoded in the input.)
|
|
Invalid `%`-encoding is treated as with the %G_URI_FLAGS_PARSE_RELAXED
|
|
rules for g_uri_parse(). (However, if @params is the path or query string
|
|
from a #GUri that was parsed without %G_URI_FLAGS_PARSE_RELAXED and
|
|
%G_URI_FLAGS_ENCODED, then you already know that it does not contain any
|
|
invalid encoding.)
|
|
|
|
%G_URI_PARAMS_WWW_FORM is handled as documented for g_uri_params_iter_init().
|
|
|
|
If %G_URI_PARAMS_CASE_INSENSITIVE is passed to @flags, attributes will be
|
|
compared case-insensitively, so a params string `attr=123&Attr=456` will only
|
|
return a single attribute–value pair, `Attr=456`. Case will be preserved in
|
|
the returned attributes.
|
|
|
|
If @params cannot be parsed (for example, it contains two @separators
|
|
characters in a row), then @error is set and %NULL is returned.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">A hash table of
|
|
attribute/value pairs, with both names and values fully-decoded; or %NULL
|
|
on error.</doc>
|
|
<type name="GLib.HashTable" c:type="GHashTable*">
|
|
<type name="utf8"/>
|
|
<type name="utf8"/>
|
|
</type>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="params" transfer-ownership="none">
|
|
<doc xml:space="preserve">a `%`-encoded string containing `attribute=value`
|
|
parameters</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of @params, or `-1` if it is nul-terminated</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="separators" transfer-ownership="none">
|
|
<doc xml:space="preserve">the separator byte character set between parameters. (usually
|
|
`&`, but sometimes `;` or both `&;`). Note that this function works on
|
|
bytes not characters, so it can't be used to delimit UTF-8 strings for
|
|
anything but ASCII characters. You may pass an empty set, in which case
|
|
no splitting will occur.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags to modify the way the parameters are handled.</doc>
|
|
<type name="UriParamsFlags" c:type="GUriParamsFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_parse_scheme" c:identifier="g_uri_parse_scheme" moved-to="Uri.parse_scheme" version="2.16">
|
|
<doc xml:space="preserve">Gets the scheme portion of a URI string.
|
|
[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
|
|
as:
|
|
|[
|
|
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
|
|
]|
|
|
Common schemes include `file`, `https`, `svn+ssh`, etc.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">The ‘scheme’ component of the URI, or
|
|
%NULL on error. The returned string should be freed when no longer needed.</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_peek_scheme" c:identifier="g_uri_peek_scheme" moved-to="Uri.peek_scheme" version="2.66">
|
|
<doc xml:space="preserve">Gets the scheme portion of a URI string.
|
|
[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
|
|
as:
|
|
|[
|
|
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
|
|
]|
|
|
Common schemes include `file`, `https`, `svn+ssh`, etc.
|
|
|
|
Unlike g_uri_parse_scheme(), the returned scheme is normalized to
|
|
all-lowercase and does not need to be freed.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">The ‘scheme’ component of the URI, or
|
|
%NULL on error. The returned string is normalized to all-lowercase, and
|
|
interned via g_intern_string(), so it does not need to be freed.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri" transfer-ownership="none">
|
|
<doc xml:space="preserve">a valid URI.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_resolve_relative" c:identifier="g_uri_resolve_relative" moved-to="Uri.resolve_relative" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Parses @uri_ref according to @flags and, if it is a
|
|
[relative URI][relative-absolute-uris], resolves it relative to
|
|
@base_uri_string. If the result is not a valid absolute URI, it will be
|
|
discarded, and an error returned.
|
|
|
|
(If @base_uri_string is %NULL, this just returns @uri_ref, or
|
|
%NULL if @uri_ref is invalid or not absolute.)</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the resolved URI string.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="base_uri_string" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string representing a base URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="uri_ref" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string representing a relative or absolute URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags describing how to parse @uri_ref</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_split" c:identifier="g_uri_split" moved-to="Uri.split" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Parses @uri_ref (which can be an
|
|
[absolute or relative URI][relative-absolute-uris]) according to @flags, and
|
|
returns the pieces. Any component that doesn't appear in @uri_ref will be
|
|
returned as %NULL (but note that all URIs always have a path component,
|
|
though it may be the empty string).
|
|
|
|
If @flags contains %G_URI_FLAGS_ENCODED, then `%`-encoded characters in
|
|
@uri_ref will remain encoded in the output strings. (If not,
|
|
then all such characters will be decoded.) Note that decoding will
|
|
only work if the URI components are ASCII or UTF-8, so you will
|
|
need to use %G_URI_FLAGS_ENCODED if they are not.
|
|
|
|
Note that the %G_URI_FLAGS_HAS_PASSWORD and
|
|
%G_URI_FLAGS_HAS_AUTH_PARAMS @flags are ignored by g_uri_split(),
|
|
since it always returns only the full userinfo; use
|
|
g_uri_split_with_user() if you want it split up.</doc>
|
|
<return-value transfer-ownership="none" skip="1">
|
|
<doc xml:space="preserve">%TRUE if @uri_ref parsed successfully, %FALSE
|
|
on error.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri_ref" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string containing a relative or absolute URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags for parsing @uri_ref</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
<parameter name="scheme" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the scheme (converted to lowercase), or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="userinfo" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the userinfo, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="host" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
host, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="port" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
port, or `-1`</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="path" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
path</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="query" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
query, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="fragment" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the fragment, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_split_network" c:identifier="g_uri_split_network" moved-to="Uri.split_network" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Parses @uri_string (which must be an [absolute URI][relative-absolute-uris])
|
|
according to @flags, and returns the pieces relevant to connecting to a host.
|
|
See the documentation for g_uri_split() for more details; this is
|
|
mostly a wrapper around that function with simpler arguments.
|
|
However, it will return an error if @uri_string is a relative URI,
|
|
or does not contain a hostname component.</doc>
|
|
<return-value transfer-ownership="none" skip="1">
|
|
<doc xml:space="preserve">%TRUE if @uri_string parsed successfully,
|
|
%FALSE on error.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string containing an absolute URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags for parsing @uri_string</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
<parameter name="scheme" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the scheme (converted to lowercase), or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="host" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
host, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="port" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
port, or `-1`</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_split_with_user" c:identifier="g_uri_split_with_user" moved-to="Uri.split_with_user" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Parses @uri_ref (which can be an
|
|
[absolute or relative URI][relative-absolute-uris]) according to @flags, and
|
|
returns the pieces. Any component that doesn't appear in @uri_ref will be
|
|
returned as %NULL (but note that all URIs always have a path component,
|
|
though it may be the empty string).
|
|
|
|
See g_uri_split(), and the definition of #GUriFlags, for more
|
|
information on the effect of @flags. Note that @password will only
|
|
be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and
|
|
@auth_params will only be parsed out if @flags contains
|
|
%G_URI_FLAGS_HAS_AUTH_PARAMS.</doc>
|
|
<return-value transfer-ownership="none" skip="1">
|
|
<doc xml:space="preserve">%TRUE if @uri_ref parsed successfully, %FALSE
|
|
on error.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="uri_ref" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string containing a relative or absolute URI</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve">flags for parsing @uri_ref</doc>
|
|
<type name="UriFlags" c:type="GUriFlags"/>
|
|
</parameter>
|
|
<parameter name="scheme" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the scheme (converted to lowercase), or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="user" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the user, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="password" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the password, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="auth_params" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the auth_params, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="host" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
host, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="port" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
port, or `-1`</doc>
|
|
<type name="gint" c:type="gint*"/>
|
|
</parameter>
|
|
<parameter name="path" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
path</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="query" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains the
|
|
query, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="fragment" direction="out" caller-allocates="0" transfer-ownership="full" nullable="1" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">on return, contains
|
|
the fragment, or %NULL</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_unescape_bytes" c:identifier="g_uri_unescape_bytes" moved-to="Uri.unescape_bytes" version="2.66" throws="1">
|
|
<doc xml:space="preserve">Unescapes a segment of an escaped string as binary data.
|
|
|
|
Note that in contrast to g_uri_unescape_string(), this does allow
|
|
nul bytes to appear in the output.
|
|
|
|
If any of the characters in @illegal_characters appears as an escaped
|
|
character in @escaped_string, then that is an error and %NULL will be
|
|
returned. This is useful if you want to avoid for instance having a slash
|
|
being expanded in an escaped path element, which might confuse pathname
|
|
handling.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an unescaped version of @escaped_string or %NULL on
|
|
error (if decoding failed, using %G_URI_ERROR_FAILED error code). The
|
|
returned #GBytes should be unreffed when no longer needed.</doc>
|
|
<type name="Bytes" c:type="GBytes*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="escaped_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">A URI-escaped string</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="length" transfer-ownership="none">
|
|
<doc xml:space="preserve">the length (in bytes) of @escaped_string to escape, or `-1` if it
|
|
is nul-terminated.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="illegal_characters" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string of illegal characters
|
|
not to be allowed, or %NULL.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_unescape_segment" c:identifier="g_uri_unescape_segment" moved-to="Uri.unescape_segment" version="2.16">
|
|
<doc xml:space="preserve">Unescapes a segment of an escaped string.
|
|
|
|
If any of the characters in @illegal_characters or the NUL
|
|
character appears as an escaped character in @escaped_string, then
|
|
that is an error and %NULL will be returned. This is useful if you
|
|
want to avoid for instance having a slash being expanded in an
|
|
escaped path element, which might confuse pathname handling.
|
|
|
|
Note: `NUL` byte is not accepted in the output, in contrast to
|
|
g_uri_unescape_bytes().</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an unescaped version of @escaped_string or %NULL on error.
|
|
The returned string should be freed when no longer needed. As a
|
|
special case if %NULL is given for @escaped_string, this function
|
|
will return %NULL.</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="escaped_string" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">A string, may be %NULL</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="escaped_string_end" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">Pointer to end of @escaped_string,
|
|
may be %NULL</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="illegal_characters" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">An optional string of illegal
|
|
characters not to be allowed, may be %NULL</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uri_unescape_string" c:identifier="g_uri_unescape_string" moved-to="Uri.unescape_string" version="2.16">
|
|
<doc xml:space="preserve">Unescapes a whole escaped string.
|
|
|
|
If any of the characters in @illegal_characters or the NUL
|
|
character appears as an escaped character in @escaped_string, then
|
|
that is an error and %NULL will be returned. This is useful if you
|
|
want to avoid for instance having a slash being expanded in an
|
|
escaped path element, which might confuse pathname handling.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">an unescaped version of @escaped_string. The returned string
|
|
should be freed when no longer needed.</doc>
|
|
<type name="utf8" c:type="char*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="escaped_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">an escaped string to be unescaped.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="illegal_characters" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a string of illegal characters
|
|
not to be allowed, or %NULL.</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="usleep" c:identifier="g_usleep">
|
|
<doc xml:space="preserve">Pauses the current thread for the given number of microseconds.
|
|
|
|
There are 1 million microseconds per second (represented by the
|
|
#G_USEC_PER_SEC macro). g_usleep() may have limited precision,
|
|
depending on hardware and operating system; don't rely on the exact
|
|
length of the sleep.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="microseconds" transfer-ownership="none">
|
|
<doc xml:space="preserve">number of microseconds to pause</doc>
|
|
<type name="gulong" c:type="gulong"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf16_to_ucs4" c:identifier="g_utf16_to_ucs4" throws="1">
|
|
<doc xml:space="preserve">Convert a string from UTF-16 to UCS-4. The result will be
|
|
nul-terminated.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to a newly allocated UCS-4 string.
|
|
This value must be freed with g_free(). If an error occurs,
|
|
%NULL will be returned and @error set.</doc>
|
|
<type name="gunichar" c:type="gunichar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-16 encoded string</doc>
|
|
<type name="guint16" c:type="const gunichar2*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum length (number of #gunichar2) of @str to use.
|
|
If @len < 0, then the string is nul-terminated.</doc>
|
|
<type name="glong" c:type="glong"/>
|
|
</parameter>
|
|
<parameter name="items_read" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store number of
|
|
words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will
|
|
be returned in case @str contains a trailing partial character. If
|
|
an error occurs then the index of the invalid input is stored here.</doc>
|
|
<type name="glong" c:type="glong*"/>
|
|
</parameter>
|
|
<parameter name="items_written" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store number
|
|
of characters written, or %NULL. The value stored here does not include
|
|
the trailing 0 character.</doc>
|
|
<type name="glong" c:type="glong*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf16_to_utf8" c:identifier="g_utf16_to_utf8" throws="1">
|
|
<doc xml:space="preserve">Convert a string from UTF-16 to UTF-8. The result will be
|
|
terminated with a 0 byte.
|
|
|
|
Note that the input is expected to be already in native endianness,
|
|
an initial byte-order-mark character is not handled specially.
|
|
g_convert() can be used to convert a byte buffer of UTF-16 data of
|
|
ambiguous endianness.
|
|
|
|
Further note that this function does not validate the result
|
|
string; it may e.g. include embedded NUL characters. The only
|
|
validation done by this function is to ensure that the input can
|
|
be correctly interpreted as UTF-16, i.e. it doesn't contain
|
|
things unpaired surrogates.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to a newly allocated UTF-8 string.
|
|
This value must be freed with g_free(). If an error occurs,
|
|
%NULL will be returned and @error set.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-16 encoded string</doc>
|
|
<type name="guint16" c:type="const gunichar2*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum length (number of #gunichar2) of @str to use.
|
|
If @len < 0, then the string is nul-terminated.</doc>
|
|
<type name="glong" c:type="glong"/>
|
|
</parameter>
|
|
<parameter name="items_read" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store number of
|
|
words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will
|
|
be returned in case @str contains a trailing partial character. If
|
|
an error occurs then the index of the invalid input is stored here.</doc>
|
|
<type name="glong" c:type="glong*"/>
|
|
</parameter>
|
|
<parameter name="items_written" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store number
|
|
of bytes written, or %NULL. The value stored here does not include the
|
|
trailing 0 byte.</doc>
|
|
<type name="glong" c:type="glong*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_casefold" c:identifier="g_utf8_casefold">
|
|
<doc xml:space="preserve">Converts a string into a form that is independent of case. The
|
|
result will not correspond to any particular case, but can be
|
|
compared for equality or ordered with the results of calling
|
|
g_utf8_casefold() on other strings.
|
|
|
|
Note that calling g_utf8_casefold() followed by g_utf8_collate() is
|
|
only an approximation to the correct linguistic case insensitive
|
|
ordering, though it is a fairly good one. Getting this exactly
|
|
right would require a more sophisticated collation function that
|
|
takes case sensitivity into account. GLib does not currently
|
|
provide such a function.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string, that is a
|
|
case independent form of @str.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @str, in bytes, or -1 if @str is nul-terminated.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_collate" c:identifier="g_utf8_collate">
|
|
<doc xml:space="preserve">Compares two strings for ordering using the linguistically
|
|
correct rules for the [current locale][setlocale].
|
|
When sorting a large number of strings, it will be significantly
|
|
faster to obtain collation keys with g_utf8_collate_key() and
|
|
compare the keys with strcmp() when sorting instead of sorting
|
|
the original strings.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">< 0 if @str1 compares before @str2,
|
|
0 if they compare equal, > 0 if @str1 compares after @str2.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str1" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="str2" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_collate_key" c:identifier="g_utf8_collate_key">
|
|
<doc xml:space="preserve">Converts a string into a collation key that can be compared
|
|
with other collation keys produced by the same function using
|
|
strcmp().
|
|
|
|
The results of comparing the collation keys of two strings
|
|
with strcmp() will always be the same as comparing the two
|
|
original keys with g_utf8_collate().
|
|
|
|
Note that this function depends on the [current locale][setlocale].</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string. This string should
|
|
be freed with g_free() when you are done with it.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @str, in bytes, or -1 if @str is nul-terminated.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_collate_key_for_filename" c:identifier="g_utf8_collate_key_for_filename" version="2.8">
|
|
<doc xml:space="preserve">Converts a string into a collation key that can be compared
|
|
with other collation keys produced by the same function using strcmp().
|
|
|
|
In order to sort filenames correctly, this function treats the dot '.'
|
|
as a special case. Most dictionary orderings seem to consider it
|
|
insignificant, thus producing the ordering "event.c" "eventgenerator.c"
|
|
"event.h" instead of "event.c" "event.h" "eventgenerator.c". Also, we
|
|
would like to treat numbers intelligently so that "file1" "file10" "file5"
|
|
is sorted as "file1" "file5" "file10".
|
|
|
|
Note that this function depends on the [current locale][setlocale].</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string. This string should
|
|
be freed with g_free() when you are done with it.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @str, in bytes, or -1 if @str is nul-terminated.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_find_next_char" c:identifier="g_utf8_find_next_char">
|
|
<doc xml:space="preserve">Finds the start of the next UTF-8 character in the string after @p.
|
|
|
|
@p does not have to be at the beginning of a UTF-8 character. No check
|
|
is made to see if the character found is actually valid other than
|
|
it starts with an appropriate byte.
|
|
|
|
If @end is %NULL, the return value will never be %NULL: if the end of the
|
|
string is reached, a pointer to the terminating nul byte is returned. If
|
|
@end is non-%NULL, the return value will be %NULL if the end of the string
|
|
is reached.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">a pointer to the found character or %NULL if @end is
|
|
set and is reached</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="p" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a position within a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="end" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a pointer to the byte following the end of the string,
|
|
or %NULL to indicate that the string is nul-terminated</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_find_prev_char" c:identifier="g_utf8_find_prev_char">
|
|
<doc xml:space="preserve">Given a position @p with a UTF-8 encoded string @str, find the start
|
|
of the previous UTF-8 character starting before @p. Returns %NULL if no
|
|
UTF-8 characters are present in @str before @p.
|
|
|
|
@p does not have to be at the beginning of a UTF-8 character. No check
|
|
is made to see if the character found is actually valid other than
|
|
it starts with an appropriate byte.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">a pointer to the found character or %NULL.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">pointer to the beginning of a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="p" transfer-ownership="none">
|
|
<doc xml:space="preserve">pointer to some position within @str</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_get_char" c:identifier="g_utf8_get_char">
|
|
<doc xml:space="preserve">Converts a sequence of bytes encoded as UTF-8 to a Unicode character.
|
|
|
|
If @p does not point to a valid UTF-8 encoded character, results
|
|
are undefined. If you are not sure that the bytes are complete
|
|
valid Unicode characters, you should use g_utf8_get_char_validated()
|
|
instead.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the resulting character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="p" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to Unicode character encoded as UTF-8</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_get_char_validated" c:identifier="g_utf8_get_char_validated">
|
|
<doc xml:space="preserve">Convert a sequence of bytes encoded as UTF-8 to a Unicode character.
|
|
This function checks for incomplete characters, for invalid characters
|
|
such as characters that are out of the range of Unicode, and for
|
|
overlong encodings of valid characters.
|
|
|
|
Note that g_utf8_get_char_validated() returns (gunichar)-2 if
|
|
@max_len is positive and any of the bytes in the first UTF-8 character
|
|
sequence are nul.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the resulting character. If @p points to a partial
|
|
sequence at the end of a string that could begin a valid
|
|
character (or if @max_len is zero), returns (gunichar)-2;
|
|
otherwise, if @p does not point to a valid UTF-8 encoded
|
|
Unicode character, returns (gunichar)-1.</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="p" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to Unicode character encoded as UTF-8</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="max_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum number of bytes to read, or -1 if @p is nul-terminated</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_make_valid" c:identifier="g_utf8_make_valid" version="2.52">
|
|
<doc xml:space="preserve">If the provided string is valid UTF-8, return a copy of it. If not,
|
|
return a copy in which bytes that could not be interpreted as valid Unicode
|
|
are replaced with the Unicode replacement character (U+FFFD).
|
|
|
|
For example, this is an appropriate function to use if you have received
|
|
a string that was incorrectly declared to be UTF-8, and you need a valid
|
|
UTF-8 version of it that can be logged or displayed to the user, with the
|
|
assumption that it is close enough to ASCII or UTF-8 to be mostly
|
|
readable as-is.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a valid UTF-8 string whose content resembles @str</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">string to coerce into UTF-8</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum length of @str to use, in bytes. If @len < 0,
|
|
then the string is nul-terminated.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="utf8_next_char" c:identifier="g_utf8_next_char" introspectable="0">
|
|
<doc xml:space="preserve">Skips to the next character in a UTF-8 string. The string must be
|
|
valid; this macro is as fast as possible, and has no error-checking.
|
|
You would use this macro to iterate over a string character by
|
|
character. The macro returns the start of the next UTF-8 character.
|
|
Before using this macro, use g_utf8_validate() to validate strings
|
|
that may contain invalid UTF-8.</doc>
|
|
<parameters>
|
|
<parameter name="p">
|
|
<doc xml:space="preserve">Pointer to the start of a valid UTF-8 character</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="utf8_normalize" c:identifier="g_utf8_normalize">
|
|
<doc xml:space="preserve">Converts a string into canonical form, standardizing
|
|
such issues as whether a character with an accent
|
|
is represented as a base character and combining
|
|
accent or as a single precomposed character. The
|
|
string has to be valid UTF-8, otherwise %NULL is
|
|
returned. You should generally call g_utf8_normalize()
|
|
before comparing two Unicode strings.
|
|
|
|
The normalization mode %G_NORMALIZE_DEFAULT only
|
|
standardizes differences that do not affect the
|
|
text content, such as the above-mentioned accent
|
|
representation. %G_NORMALIZE_ALL also standardizes
|
|
the "compatibility" characters in Unicode, such
|
|
as SUPERSCRIPT THREE to the standard forms
|
|
(in this case DIGIT THREE). Formatting information
|
|
may be lost but for most text operations such
|
|
characters should be considered the same.
|
|
|
|
%G_NORMALIZE_DEFAULT_COMPOSE and %G_NORMALIZE_ALL_COMPOSE
|
|
are like %G_NORMALIZE_DEFAULT and %G_NORMALIZE_ALL,
|
|
but returned a result with composed forms rather
|
|
than a maximally decomposed form. This is often
|
|
useful if you intend to convert the string to
|
|
a legacy encoding or pass it to a system with
|
|
less capable Unicode handling.</doc>
|
|
<return-value transfer-ownership="full" nullable="1">
|
|
<doc xml:space="preserve">a newly allocated string, that
|
|
is the normalized form of @str, or %NULL if @str
|
|
is not valid UTF-8.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string.</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @str, in bytes, or -1 if @str is nul-terminated.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="mode" transfer-ownership="none">
|
|
<doc xml:space="preserve">the type of normalization to perform.</doc>
|
|
<type name="NormalizeMode" c:type="GNormalizeMode"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_offset_to_pointer" c:identifier="g_utf8_offset_to_pointer">
|
|
<doc xml:space="preserve">Converts from an integer character offset to a pointer to a position
|
|
within the string.
|
|
|
|
Since 2.10, this function allows to pass a negative @offset to
|
|
step backwards. It is usually worth stepping backwards from the end
|
|
instead of forwards if @offset is in the last fourth of the string,
|
|
since moving forward is about 3 times faster than moving backward.
|
|
|
|
Note that this function doesn't abort when reaching the end of @str.
|
|
Therefore you should be sure that @offset is within string boundaries
|
|
before calling that function. Call g_utf8_strlen() when unsure.
|
|
This limitation exists as this function is called frequently during
|
|
text rendering and therefore has to be as fast as possible.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the resulting pointer</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="offset" transfer-ownership="none">
|
|
<doc xml:space="preserve">a character offset within @str</doc>
|
|
<type name="glong" c:type="glong"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_pointer_to_offset" c:identifier="g_utf8_pointer_to_offset">
|
|
<doc xml:space="preserve">Converts from a pointer to position within a string to an integer
|
|
character offset.
|
|
|
|
Since 2.10, this function allows @pos to be before @str, and returns
|
|
a negative offset in this case.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the resulting character offset</doc>
|
|
<type name="glong" c:type="glong"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="pos" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a position within @str</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_prev_char" c:identifier="g_utf8_prev_char">
|
|
<doc xml:space="preserve">Finds the previous UTF-8 character in the string before @p.
|
|
|
|
@p does not have to be at the beginning of a UTF-8 character. No check
|
|
is made to see if the character found is actually valid other than
|
|
it starts with an appropriate byte. If @p might be the first
|
|
character of the string, you must use g_utf8_find_prev_char() instead.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to the found character</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="p" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to a position within a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_strchr" c:identifier="g_utf8_strchr">
|
|
<doc xml:space="preserve">Finds the leftmost occurrence of the given Unicode character
|
|
in a UTF-8 encoded string, while limiting the search to @len bytes.
|
|
If @len is -1, allow unbounded search.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">%NULL if the string does not contain the character,
|
|
otherwise, a pointer to the start of the leftmost occurrence
|
|
of the character in the string.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="p" transfer-ownership="none">
|
|
<doc xml:space="preserve">a nul-terminated UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum length of @p</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_strdown" c:identifier="g_utf8_strdown">
|
|
<doc xml:space="preserve">Converts all Unicode characters in the string that have a case
|
|
to lowercase. The exact manner that this is done depends
|
|
on the current locale, and may result in the number of
|
|
characters in the string changing.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string, with all characters
|
|
converted to lowercase.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @str, in bytes, or -1 if @str is nul-terminated.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_strlen" c:identifier="g_utf8_strlen">
|
|
<doc xml:space="preserve">Computes the length of the string in characters, not including
|
|
the terminating nul character. If the @max'th byte falls in the
|
|
middle of a character, the last (partial) character is not counted.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the length of the string in characters</doc>
|
|
<type name="glong" c:type="glong"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="p" transfer-ownership="none">
|
|
<doc xml:space="preserve">pointer to the start of a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="max" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum number of bytes to examine. If @max
|
|
is less than 0, then the string is assumed to be
|
|
nul-terminated. If @max is 0, @p will not be examined and
|
|
may be %NULL. If @max is greater than 0, up to @max
|
|
bytes are examined</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_strncpy" c:identifier="g_utf8_strncpy">
|
|
<doc xml:space="preserve">Like the standard C strncpy() function, but copies a given number
|
|
of characters instead of a given number of bytes. The @src string
|
|
must be valid UTF-8 encoded text. (Use g_utf8_validate() on all
|
|
text before trying to use UTF-8 utility functions with it.)
|
|
|
|
Note you must ensure @dest is at least 4 * @n to fit the
|
|
largest possible UTF-8 characters</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">@dest</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="dest" transfer-ownership="none">
|
|
<doc xml:space="preserve">buffer to fill with characters from @src</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="src" transfer-ownership="none">
|
|
<doc xml:space="preserve">UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">character count</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_strrchr" c:identifier="g_utf8_strrchr">
|
|
<doc xml:space="preserve">Find the rightmost occurrence of the given Unicode character
|
|
in a UTF-8 encoded string, while limiting the search to @len bytes.
|
|
If @len is -1, allow unbounded search.</doc>
|
|
<return-value transfer-ownership="none" nullable="1">
|
|
<doc xml:space="preserve">%NULL if the string does not contain the character,
|
|
otherwise, a pointer to the start of the rightmost occurrence
|
|
of the character in the string.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="p" transfer-ownership="none">
|
|
<doc xml:space="preserve">a nul-terminated UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum length of @p</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="c" transfer-ownership="none">
|
|
<doc xml:space="preserve">a Unicode character</doc>
|
|
<type name="gunichar" c:type="gunichar"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_strreverse" c:identifier="g_utf8_strreverse" version="2.2">
|
|
<doc xml:space="preserve">Reverses a UTF-8 string. @str must be valid UTF-8 encoded text.
|
|
(Use g_utf8_validate() on all text before trying to use UTF-8
|
|
utility functions with it.)
|
|
|
|
This function is intended for programmatic uses of reversed strings.
|
|
It pays no attention to decomposed characters, combining marks, byte
|
|
order marks, directional indicators (LRM, LRO, etc) and similar
|
|
characters which might need special handling when reversing a string
|
|
for display purposes.
|
|
|
|
Note that unlike g_strreverse(), this function returns
|
|
newly-allocated memory, which should be freed with g_free() when
|
|
no longer needed.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly-allocated string which is the reverse of @str</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum length of @str to use, in bytes. If @len < 0,
|
|
then the string is nul-terminated.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_strup" c:identifier="g_utf8_strup">
|
|
<doc xml:space="preserve">Converts all Unicode characters in the string that have a case
|
|
to uppercase. The exact manner that this is done depends
|
|
on the current locale, and may result in the number of
|
|
characters in the string increasing. (For instance, the
|
|
German ess-zet will be changed to SS.)</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated string, with all characters
|
|
converted to uppercase.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">length of @str, in bytes, or -1 if @str is nul-terminated.</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_substring" c:identifier="g_utf8_substring" version="2.30">
|
|
<doc xml:space="preserve">Copies a substring out of a UTF-8 encoded string.
|
|
The substring will contain @end_pos - @start_pos characters.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a newly allocated copy of the requested
|
|
substring. Free with g_free() when no longer needed.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="start_pos" transfer-ownership="none">
|
|
<doc xml:space="preserve">a character offset within @str</doc>
|
|
<type name="glong" c:type="glong"/>
|
|
</parameter>
|
|
<parameter name="end_pos" transfer-ownership="none">
|
|
<doc xml:space="preserve">another character offset within @str</doc>
|
|
<type name="glong" c:type="glong"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_to_ucs4" c:identifier="g_utf8_to_ucs4" throws="1">
|
|
<doc xml:space="preserve">Convert a string from UTF-8 to a 32-bit fixed width
|
|
representation as UCS-4. A trailing 0 character will be added to the
|
|
string after the converted text.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to a newly allocated UCS-4 string.
|
|
This value must be freed with g_free(). If an error occurs,
|
|
%NULL will be returned and @error set.</doc>
|
|
<type name="gunichar" c:type="gunichar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum length of @str to use, in bytes. If @len < 0,
|
|
then the string is nul-terminated.</doc>
|
|
<type name="glong" c:type="glong"/>
|
|
</parameter>
|
|
<parameter name="items_read" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store number of
|
|
bytes read, or %NULL.
|
|
If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
|
|
returned in case @str contains a trailing partial
|
|
character. If an error occurs then the index of the
|
|
invalid input is stored here.</doc>
|
|
<type name="glong" c:type="glong*"/>
|
|
</parameter>
|
|
<parameter name="items_written" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store number
|
|
of characters written or %NULL. The value here stored does not include
|
|
the trailing 0 character.</doc>
|
|
<type name="glong" c:type="glong*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_to_ucs4_fast" c:identifier="g_utf8_to_ucs4_fast">
|
|
<doc xml:space="preserve">Convert a string from UTF-8 to a 32-bit fixed width
|
|
representation as UCS-4, assuming valid UTF-8 input.
|
|
This function is roughly twice as fast as g_utf8_to_ucs4()
|
|
but does no error checking on the input. A trailing 0 character
|
|
will be added to the string after the converted text.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to a newly allocated UCS-4 string.
|
|
This value must be freed with g_free().</doc>
|
|
<type name="gunichar" c:type="gunichar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum length of @str to use, in bytes. If @len < 0,
|
|
then the string is nul-terminated.</doc>
|
|
<type name="glong" c:type="glong"/>
|
|
</parameter>
|
|
<parameter name="items_written" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store the
|
|
number of characters in the result, or %NULL.</doc>
|
|
<type name="glong" c:type="glong*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_to_utf16" c:identifier="g_utf8_to_utf16" throws="1">
|
|
<doc xml:space="preserve">Convert a string from UTF-8 to UTF-16. A 0 character will be
|
|
added to the result after the converted text.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a pointer to a newly allocated UTF-16 string.
|
|
This value must be freed with g_free(). If an error occurs,
|
|
%NULL will be returned and @error set.</doc>
|
|
<type name="guint16" c:type="gunichar2*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a UTF-8 encoded string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="len" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum length (number of bytes) of @str to use.
|
|
If @len < 0, then the string is nul-terminated.</doc>
|
|
<type name="glong" c:type="glong"/>
|
|
</parameter>
|
|
<parameter name="items_read" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store number of
|
|
bytes read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will
|
|
be returned in case @str contains a trailing partial character. If
|
|
an error occurs then the index of the invalid input is stored here.</doc>
|
|
<type name="glong" c:type="glong*"/>
|
|
</parameter>
|
|
<parameter name="items_written" direction="out" caller-allocates="1" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store number
|
|
of #gunichar2 written, or %NULL. The value stored here does not include
|
|
the trailing 0.</doc>
|
|
<type name="glong" c:type="glong*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_validate" c:identifier="g_utf8_validate">
|
|
<doc xml:space="preserve">Validates UTF-8 encoded text. @str is the text to validate;
|
|
if @str is nul-terminated, then @max_len can be -1, otherwise
|
|
@max_len should be the number of bytes to validate.
|
|
If @end is non-%NULL, then the end of the valid range
|
|
will be stored there (i.e. the start of the first invalid
|
|
character if some bytes were invalid, or the end of the text
|
|
being validated otherwise).
|
|
|
|
Note that g_utf8_validate() returns %FALSE if @max_len is
|
|
positive and any of the @max_len bytes are nul.
|
|
|
|
Returns %TRUE if all of @str was valid. Many GLib and GTK+
|
|
routines require valid UTF-8 as input; so data read from a file
|
|
or the network should be checked with g_utf8_validate() before
|
|
doing anything else with it.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the text was valid UTF-8</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to character data</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="max_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">max bytes to validate, or -1 to go until NUL</doc>
|
|
<type name="gssize" c:type="gssize"/>
|
|
</parameter>
|
|
<parameter name="end" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for end of valid data</doc>
|
|
<type name="utf8" c:type="const gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="utf8_validate_len" c:identifier="g_utf8_validate_len" version="2.60">
|
|
<doc xml:space="preserve">Validates UTF-8 encoded text.
|
|
|
|
As with g_utf8_validate(), but @max_len must be set, and hence this function
|
|
will always return %FALSE if any of the bytes of @str are nul.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if the text was valid UTF-8</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to character data</doc>
|
|
<array length="1" zero-terminated="0" c:type="const gchar*">
|
|
<type name="guint8"/>
|
|
</array>
|
|
</parameter>
|
|
<parameter name="max_len" transfer-ownership="none">
|
|
<doc xml:space="preserve">max bytes to validate</doc>
|
|
<type name="gsize" c:type="gsize"/>
|
|
</parameter>
|
|
<parameter name="end" direction="out" caller-allocates="0" transfer-ownership="none" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">return location for end of valid data</doc>
|
|
<type name="utf8" c:type="const gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="uuid">
|
|
<doc xml:space="preserve">A UUID, or Universally unique identifier, is intended to uniquely
|
|
identify information in a distributed environment. For the
|
|
definition of UUID, see [RFC 4122](https://tools.ietf.org/html/rfc4122.html).
|
|
|
|
The creation of UUIDs does not require a centralized authority.
|
|
|
|
UUIDs are of relatively small size (128 bits, or 16 bytes). The
|
|
common string representation (ex:
|
|
1d6c0810-2bd6-45f3-9890-0268422a6f14) needs 37 bytes.
|
|
|
|
The UUID specification defines 5 versions, and calling
|
|
g_uuid_string_random() will generate a unique (or rather random)
|
|
UUID of the most common version, version 4.</doc>
|
|
</docsection>
|
|
<function name="uuid_string_is_valid" c:identifier="g_uuid_string_is_valid" version="2.52">
|
|
<doc xml:space="preserve">Parses the string @str and verify if it is a UUID.
|
|
|
|
The function accepts the following syntax:
|
|
|
|
- simple forms (e.g. `f81d4fae-7dec-11d0-a765-00a0c91e6bf6`)
|
|
|
|
Note that hyphens are required within the UUID string itself,
|
|
as per the aforementioned RFC.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @str is a valid UUID, %FALSE otherwise.</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="str" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string representing a UUID</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="uuid_string_random" c:identifier="g_uuid_string_random" version="2.52">
|
|
<doc xml:space="preserve">Generates a random UUID (RFC 4122 version 4) as a string. It has the same
|
|
randomness guarantees as #GRand, so must not be used for cryptographic
|
|
purposes such as key generation, nonces, salts or one-time pads.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">A string that should be freed with g_free().</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="variant_get_gtype" c:identifier="g_variant_get_gtype">
|
|
<return-value transfer-ownership="none">
|
|
<type name="GType" c:type="GType"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="variant_is_object_path" c:identifier="g_variant_is_object_path" moved-to="Variant.is_object_path" version="2.24">
|
|
<doc xml:space="preserve">Determines if a given string is a valid D-Bus object path. You
|
|
should ensure that a string is a valid D-Bus object path before
|
|
passing it to g_variant_new_object_path().
|
|
|
|
A valid object path starts with `/` followed by zero or more
|
|
sequences of characters separated by `/` characters. Each sequence
|
|
must contain only the characters `[A-Z][a-z][0-9]_`. No sequence
|
|
(including the one following the final `/` character) may be empty.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @string is a D-Bus object path</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a normal C nul-terminated string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="variant_is_signature" c:identifier="g_variant_is_signature" moved-to="Variant.is_signature" version="2.24">
|
|
<doc xml:space="preserve">Determines if a given string is a valid D-Bus type signature. You
|
|
should ensure that a string is a valid D-Bus type signature before
|
|
passing it to g_variant_new_signature().
|
|
|
|
D-Bus type signatures consist of zero or more definite #GVariantType
|
|
strings in sequence.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @string is a D-Bus type signature</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a normal C nul-terminated string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="variant_parse" c:identifier="g_variant_parse" moved-to="Variant.parse" throws="1">
|
|
<doc xml:space="preserve">Parses a #GVariant from a text representation.
|
|
|
|
A single #GVariant is parsed from the content of @text.
|
|
|
|
The format is described [here][gvariant-text].
|
|
|
|
The memory at @limit will never be accessed and the parser behaves as
|
|
if the character at @limit is the nul terminator. This has the
|
|
effect of bounding @text.
|
|
|
|
If @endptr is non-%NULL then @text is permitted to contain data
|
|
following the value that this function parses and @endptr will be
|
|
updated to point to the first character past the end of the text
|
|
parsed by this function. If @endptr is %NULL and there is extra data
|
|
then an error is returned.
|
|
|
|
If @type is non-%NULL then the value will be parsed to have that
|
|
type. This may result in additional parse errors (in the case that
|
|
the parsed value doesn't fit the type) but may also result in fewer
|
|
errors (in the case that the type would have been ambiguous, such as
|
|
with empty arrays).
|
|
|
|
In the event that the parsing is successful, the resulting #GVariant
|
|
is returned. It is never floating, and must be freed with
|
|
g_variant_unref().
|
|
|
|
In case of any error, %NULL will be returned. If @error is non-%NULL
|
|
then it will be set to reflect the error that occurred.
|
|
|
|
Officially, the language understood by the parser is "any string
|
|
produced by g_variant_print()".
|
|
|
|
There may be implementation specific restrictions on deeply nested values,
|
|
which would result in a %G_VARIANT_PARSE_ERROR_RECURSION error. #GVariant is
|
|
guaranteed to handle nesting up to at least 64 levels.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">a non-floating reference to a #GVariant, or %NULL</doc>
|
|
<type name="Variant" c:type="GVariant*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="type" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a #GVariantType, or %NULL</doc>
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</parameter>
|
|
<parameter name="text" transfer-ownership="none">
|
|
<doc xml:space="preserve">a string containing a GVariant in text form</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="limit" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a pointer to the end of @text, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="endptr" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">a location to store the end pointer, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="variant_parse_error_print_context" c:identifier="g_variant_parse_error_print_context" moved-to="Variant.parse_error_print_context" version="2.40">
|
|
<doc xml:space="preserve">Pretty-prints a message showing the context of a #GVariant parse
|
|
error within the string for which parsing was attempted.
|
|
|
|
The resulting string is suitable for output to the console or other
|
|
monospace media where newlines are treated in the usual way.
|
|
|
|
The message will typically look something like one of the following:
|
|
|
|
|[
|
|
unterminated string constant:
|
|
(1, 2, 3, 'abc
|
|
^^^^
|
|
]|
|
|
|
|
or
|
|
|
|
|[
|
|
unable to find a common type:
|
|
[1, 2, 3, 'str']
|
|
^ ^^^^^
|
|
]|
|
|
|
|
The format of the message may change in a future version.
|
|
|
|
@error must have come from a failed attempt to g_variant_parse() and
|
|
@source_str must be exactly the same string that caused the error.
|
|
If @source_str was not nul-terminated when you passed it to
|
|
g_variant_parse() then you must add nul termination before using this
|
|
function.</doc>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve">the printed message</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="error" transfer-ownership="none">
|
|
<doc xml:space="preserve">a #GError from the #GVariantParseError domain</doc>
|
|
<type name="Error" c:type="GError*"/>
|
|
</parameter>
|
|
<parameter name="source_str" transfer-ownership="none">
|
|
<doc xml:space="preserve">the string that was given to the parser</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="variant_parse_error_quark" c:identifier="g_variant_parse_error_quark" moved-to="Variant.parse_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="variant_parser_get_error_quark" c:identifier="g_variant_parser_get_error_quark" moved-to="Variant.parser_get_error_quark" deprecated="1">
|
|
<doc xml:space="preserve">Same as g_variant_error_quark().</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_variant_parse_error_quark() instead.</doc-deprecated>
|
|
<return-value transfer-ownership="none">
|
|
<type name="Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="variant_type_checked_" c:identifier="g_variant_type_checked_" moved-to="VariantType.checked_">
|
|
<return-value transfer-ownership="none">
|
|
<type name="VariantType" c:type="const GVariantType*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="arg0" transfer-ownership="none">
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="variant_type_string_get_depth_" c:identifier="g_variant_type_string_get_depth_" moved-to="VariantType.string_get_depth_">
|
|
<return-value transfer-ownership="none">
|
|
<type name="gsize" c:type="gsize"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="type_string" transfer-ownership="none">
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="variant_type_string_is_valid" c:identifier="g_variant_type_string_is_valid" moved-to="VariantType.string_is_valid">
|
|
<doc xml:space="preserve">Checks if @type_string is a valid GVariant type string. This call is
|
|
equivalent to calling g_variant_type_string_scan() and confirming
|
|
that the following character is a nul terminator.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if @type_string is exactly one valid type string
|
|
|
|
Since 2.24</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="type_string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to any string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="variant_type_string_scan" c:identifier="g_variant_type_string_scan" moved-to="VariantType.string_scan" version="2.24">
|
|
<doc xml:space="preserve">Scan for a single complete and valid GVariant type string in @string.
|
|
The memory pointed to by @limit (or bytes beyond it) is never
|
|
accessed.
|
|
|
|
If a valid type string is found, @endptr is updated to point to the
|
|
first character past the end of the string that was found and %TRUE
|
|
is returned.
|
|
|
|
If there is no valid type string starting at @string, or if the type
|
|
string does not end before @limit then %FALSE is returned.
|
|
|
|
For the simple case of checking if a string is a valid type string,
|
|
see g_variant_type_string_is_valid().</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">%TRUE if a valid type string was found</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">a pointer to any string</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="limit" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">the end of @string, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="endptr" direction="out" caller-allocates="0" transfer-ownership="full" optional="1" allow-none="1">
|
|
<doc xml:space="preserve">location to store the end pointer, or %NULL</doc>
|
|
<type name="utf8" c:type="const gchar**"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="vasprintf" c:identifier="g_vasprintf" version="2.4" introspectable="0">
|
|
<doc xml:space="preserve">An implementation of the GNU vasprintf() function which supports
|
|
positional parameters, as specified in the Single Unix Specification.
|
|
This function is similar to g_vsprintf(), except that it allocates a
|
|
string to hold the output, instead of putting the output in a buffer
|
|
you allocate in advance.
|
|
|
|
The returned value in @string is guaranteed to be non-NULL, unless
|
|
@format contains `%lc` or `%ls` conversions, which can fail if no
|
|
multibyte representation is available for the given character.
|
|
|
|
`glib/gprintf.h` must be explicitly included in order to use this function.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes printed.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the return location for the newly-allocated string.</doc>
|
|
<type name="utf8" c:type="gchar**"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">a standard printf() format string, but notice
|
|
[string precision pitfalls][string-precision]</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="args" transfer-ownership="none">
|
|
<doc xml:space="preserve">the list of arguments to insert in the output.</doc>
|
|
<type name="va_list" c:type="va_list"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="version">
|
|
<doc xml:space="preserve">GLib provides version information, primarily useful in configure
|
|
checks for builds that have a configure script. Applications will
|
|
not typically use the features described here.
|
|
|
|
The GLib headers annotate deprecated APIs in a way that produces
|
|
compiler warnings if these deprecated APIs are used. The warnings
|
|
can be turned off by defining the macro %GLIB_DISABLE_DEPRECATION_WARNINGS
|
|
before including the glib.h header.
|
|
|
|
GLib also provides support for building applications against
|
|
defined subsets of deprecated or new GLib APIs. Define the macro
|
|
%GLIB_VERSION_MIN_REQUIRED to specify up to what version of GLib
|
|
you want to receive warnings about deprecated APIs. Define the
|
|
macro %GLIB_VERSION_MAX_ALLOWED to specify the newest version of
|
|
GLib whose API you want to use.</doc>
|
|
</docsection>
|
|
<function name="vfprintf" c:identifier="g_vfprintf" version="2.2" introspectable="0">
|
|
<doc xml:space="preserve">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.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes printed.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="file" transfer-ownership="none">
|
|
<doc xml:space="preserve">the stream to write to.</doc>
|
|
<type name="gpointer" c:type="FILE*"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">a standard printf() format string, but notice
|
|
[string precision pitfalls][string-precision]</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="args" transfer-ownership="none">
|
|
<doc xml:space="preserve">the list of arguments to insert in the output.</doc>
|
|
<type name="va_list" c:type="va_list"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="vprintf" c:identifier="g_vprintf" version="2.2" introspectable="0">
|
|
<doc xml:space="preserve">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.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes printed.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">a standard printf() format string, but notice
|
|
[string precision pitfalls][string-precision]</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="args" transfer-ownership="none">
|
|
<doc xml:space="preserve">the list of arguments to insert in the output.</doc>
|
|
<type name="va_list" c:type="va_list"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="vsnprintf" c:identifier="g_vsnprintf" introspectable="0">
|
|
<doc xml:space="preserve">A safer form of the standard vsprintf() function. The output is guaranteed
|
|
to not exceed @n characters (including the terminating nul character), so
|
|
it is easy to ensure that a buffer overflow cannot occur.
|
|
|
|
See also g_strdup_vprintf().
|
|
|
|
In versions of GLib prior to 1.2.3, this function may return -1 if the
|
|
output was truncated, and the truncated string may not be nul-terminated.
|
|
In versions prior to 1.3.12, this function returns the length of the output
|
|
string.
|
|
|
|
The return value of g_vsnprintf() conforms to the vsnprintf() function
|
|
as standardized in ISO C99. Note that this is different from traditional
|
|
vsnprintf(), which returns the length of the output string.
|
|
|
|
The format string may contain positional parameters, as specified in
|
|
the Single Unix Specification.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes which would be produced if the buffer
|
|
was large enough.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the buffer to hold the output.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="n" transfer-ownership="none">
|
|
<doc xml:space="preserve">the maximum number of bytes to produce (including the
|
|
terminating nul character).</doc>
|
|
<type name="gulong" c:type="gulong"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">a standard printf() format string, but notice
|
|
string precision pitfalls][string-precision]</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="args" transfer-ownership="none">
|
|
<doc xml:space="preserve">the list of arguments to insert in the output.</doc>
|
|
<type name="va_list" c:type="va_list"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="vsprintf" c:identifier="g_vsprintf" version="2.2" introspectable="0">
|
|
<doc xml:space="preserve">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.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve">the number of bytes printed.</doc>
|
|
<type name="gint" c:type="gint"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="string" transfer-ownership="none">
|
|
<doc xml:space="preserve">the buffer to hold the output.</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</parameter>
|
|
<parameter name="format" transfer-ownership="none">
|
|
<doc xml:space="preserve">a standard printf() format string, but notice
|
|
[string precision pitfalls][string-precision]</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="args" transfer-ownership="none">
|
|
<doc xml:space="preserve">the list of arguments to insert in the output.</doc>
|
|
<type name="va_list" c:type="va_list"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function-macro name="warn_if_fail" c:identifier="g_warn_if_fail" version="2.16" introspectable="0">
|
|
<doc xml:space="preserve">Logs a warning if the expression is not true.</doc>
|
|
<parameters>
|
|
<parameter name="expr">
|
|
<doc xml:space="preserve">the expression to check</doc>
|
|
</parameter>
|
|
</parameters>
|
|
</function-macro>
|
|
<function name="warn_message" c:identifier="g_warn_message" introspectable="0">
|
|
<doc xml:space="preserve">Internal function used to print messages from the public g_warn_if_reached()
|
|
and g_warn_if_fail() macros.</doc>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="domain" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">log domain</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="file" transfer-ownership="none">
|
|
<doc xml:space="preserve">file containing the warning</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="line" transfer-ownership="none">
|
|
<doc xml:space="preserve">line number of the warning</doc>
|
|
<type name="gint" c:type="int"/>
|
|
</parameter>
|
|
<parameter name="func" transfer-ownership="none">
|
|
<doc xml:space="preserve">function containing the warning</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
<parameter name="warnexpr" transfer-ownership="none" nullable="1" allow-none="1">
|
|
<doc xml:space="preserve">expression which failed</doc>
|
|
<type name="utf8" c:type="const char*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<docsection name="warnings">
|
|
<doc xml:space="preserve">GLib defines several warning functions and assertions which can be used to
|
|
warn of programmer errors when calling functions, and print error messages
|
|
from command line programs.
|
|
|
|
The g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and
|
|
g_return_val_if_reached() macros are intended as pre-condition assertions, to
|
|
be used at the top of a public function to check that the function’s
|
|
arguments are acceptable. Any failure of such a pre-condition assertion is
|
|
considered a programming error on the part of the caller of the public API,
|
|
and the program is considered to be in an undefined state afterwards. They
|
|
are similar to the libc assert() function, but provide more context on
|
|
failures.
|
|
|
|
For example:
|
|
|[<!-- language="C" -->
|
|
gboolean
|
|
g_dtls_connection_shutdown (GDtlsConnection *conn,
|
|
gboolean shutdown_read,
|
|
gboolean shutdown_write,
|
|
GCancellable *cancellable,
|
|
GError **error)
|
|
{
|
|
// local variable declarations
|
|
|
|
g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
|
|
g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
|
|
g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
|
|
|
|
// function body
|
|
|
|
return return_val;
|
|
}
|
|
]|
|
|
|
|
g_print(), g_printerr() and g_set_print_handler() are intended to be used for
|
|
output from command line applications, since they output to standard output
|
|
and standard error by default — whereas functions like g_message() and
|
|
g_log() may be redirected to special purpose message windows, files, or the
|
|
system journal.</doc>
|
|
</docsection>
|
|
<docsection name="windows">
|
|
<doc xml:space="preserve">These functions provide some level of UNIX emulation on the
|
|
Windows platform. If your application really needs the POSIX
|
|
APIs, we suggest you try the Cygwin project.</doc>
|
|
</docsection>
|
|
</namespace>
|
|
</repository>
|