guile-examples/gui/guile-gi/docs/GLib.gtkdoc.xml

<?xml version="1.0"?><book><chapter><title>GLib</title><refentry><refnamediv><refname>&lt;GArray&gt;</refname></refnamediv><refsect1><title>Description</title><para>Contains the public fields of a GArray.</para></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibAsciiType&gt;</refname></refnamediv><refsect1><title>Members</title><refsect2><title>alnum</title><remark>alias <code>G_ASCII_ALNUM</code></remark><para>Undocumented</para></refsect2><refsect2><title>alpha</title><remark>alias <code>G_ASCII_ALPHA</code></remark><para>Undocumented</para></refsect2><refsect2><title>cntrl</title><remark>alias <code>G_ASCII_CNTRL</code></remark><para>Undocumented</para></refsect2><refsect2><title>digit</title><remark>alias <code>G_ASCII_DIGIT</code></remark><para>Undocumented</para></refsect2><refsect2><title>graph</title><remark>alias <code>G_ASCII_GRAPH</code></remark><para>Undocumented</para></refsect2><refsect2><title>lower</title><remark>alias <code>G_ASCII_LOWER</code></remark><para>Undocumented</para></refsect2><refsect2><title>print</title><remark>alias <code>G_ASCII_PRINT</code></remark><para>Undocumented</para></refsect2><refsect2><title>punct</title><remark>alias <code>G_ASCII_PUNCT</code></remark><para>Undocumented</para></refsect2><refsect2><title>space</title><remark>alias <code>G_ASCII_SPACE</code></remark><para>Undocumented</para></refsect2><refsect2><title>upper</title><remark>alias <code>G_ASCII_UPPER</code></remark><para>Undocumented</para></refsect2><refsect2><title>xdigit</title><remark>alias <code>G_ASCII_XDIGIT</code></remark><para>Undocumented</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibBookmarkFileError&gt;</refname></refnamediv><refsect1><title>Description</title><para>Error codes returned by bookmark file parsing.</para></refsect1><refsect1><title>Members</title><refsect2><title>invalid-uri</title><remark>alias <code>G_BOOKMARK_FILE_ERROR_INVALID_URI</code></remark><para>URI was ill-formed</para></refsect2><refsect2><title>invalid-value</title><remark>alias <code>G_BOOKMARK_FILE_ERROR_INVALID_VALUE</code></remark><para>a requested field was not found</para></refsect2><refsect2><title>app-not-registered</title><remark>alias <code>G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED</code></remark><para>a requested application did
    not register a bookmark</para></refsect2><refsect2><title>uri-not-found</title><remark>alias <code>G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND</code></remark><para>a requested URI was not found</para></refsect2><refsect2><title>read</title><remark>alias <code>G_BOOKMARK_FILE_ERROR_READ</code></remark><para>document was ill formed</para></refsect2><refsect2><title>unknown-encoding</title><remark>alias <code>G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING</code></remark><para>the text being parsed was
    in an unknown encoding</para></refsect2><refsect2><title>write</title><remark>alias <code>G_BOOKMARK_FILE_ERROR_WRITE</code></remark><para>an error occurred while writing</para></refsect2><refsect2><title>file-not-found</title><remark>alias <code>G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND</code></remark><para>requested file was not found</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GByteArray&gt;</refname></refnamediv><refsect1><title>Description</title><para>Contains the public fields of a GByteArray.</para></refsect1><refsect1><title>Functions</title><refsect2><title>byte-array:free</title><informalexample><programlisting>(define-values (%return) (byte-array:free array free-segment))
</programlisting></informalexample><para>Frees the memory allocated by the <type>GByteArray</type>. If <parameter>free_segment</parameter> is
<constant>TRUE</constant> it frees the actual byte data. If the reference count of
<parameter>array</parameter> is greater than one, the <type>GByteArray</type> wrapper is preserved but
the size of <parameter>array</parameter> will be set to zero.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>array</para></td><td class="parameter_description"><para>a <type>GByteArray</type></para><para>Passed as <code>array</code></para></td></tr><tr><td class="parameter_name"><para>free_segment</para></td><td class="parameter_description"><para>if <constant>TRUE</constant> the actual byte data is freed as well</para><para>Passed as <code>free-segment</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>byte-array:free-to-bytes</title><informalexample><programlisting>(define-values (%return) (byte-array:free-to-bytes array))
</programlisting></informalexample><para>Transfers the data from the <type>GByteArray</type> into a new immutable <type>GBytes</type>.
</para>
<para>The <type>GByteArray</type> is freed unless the reference count of <parameter>array</parameter> is greater
than one, the <type>GByteArray</type> wrapper is preserved but the size of <parameter>array</parameter>
will be set to zero.
</para>
<para>This is identical to using <function>g_bytes_new_take()</function> and <function>g_byte_array_free()</function>
together.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>array</para></td><td class="parameter_description"><para>a <type>GByteArray</type></para><para>Passed as <code>array</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>byte-array:new</title><informalexample><programlisting>(define-values (%return) (byte-array:new))
</programlisting></informalexample><para>Creates a new <type>GByteArray</type> with a reference count of 1.</para></refsect2><refsect2><title>byte-array:new-take</title><informalexample><programlisting>(define-values (%return) (byte-array:new-take data))
</programlisting></informalexample><para>Create byte array containing the data. The data will be owned by the array
and will be freed with <function>g_free()</function>, i.e. it could be allocated using <function>g_strdup()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>byte data for the array</para><para>Passed as <code>data</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>length of <parameter>data</parameter></para><para>Inferred from <code>data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>byte-array:steal</title><informalexample><programlisting>(define-values (%return len) (byte-array:steal array len))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>array</para></td><td class="parameter_description"><para>a <type>GByteArray</type>.</para><para>Passed as <code>array</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>pointer to retrieve the number of
   elements of the original array</para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>byte-array:unref</title><informalexample><programlisting>(define-values () (byte-array:unref array))
</programlisting></informalexample><para>Atomically decrements the reference count of <parameter>array</parameter> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>array</para></td><td class="parameter_description"><para>A <type>GByteArray</type></para><para>Passed as <code>array</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GBytes&gt;</refname></refnamediv><refsect1><title>Description</title><para>A simple refcounted data type representing an immutable sequence of zero or
more bytes from an unspecified origin.
</para>
<para>The purpose of a <type>GBytes</type> 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 <type>GBytes</type> without coordinating
their activities, resting assured that the byte data will not change or
move while they hold a reference.
</para>
<para>A <type>GBytes</type> can come from many different origins that may have
different procedures for freeing the memory region.  Examples are
memory from <function>g_malloc()</function>, from memory slices, from a <type>GMappedFile</type> or
memory from other allocators.
</para>
<para><type>GBytes</type> work well as keys in <type>GHashTable</type>. Use <function>g_bytes_equal()</function> and
<function>g_bytes_hash()</function> as parameters to <function>g_hash_table_new()</function> or <function>g_hash_table_new_full()</function>.
<type>GBytes</type> can also be used as keys in a <type>GTree</type> by passing the <function>g_bytes_compare()</function>
function to <function>g_tree_new()</function>.
</para>
<para>The data pointed to by this bytes must not be modified. For a mutable
array of bytes see <type>GByteArray</type>. Use <function>g_bytes_unref_to_array()</function> to create a
mutable array for a <type>GBytes</type> sequence. To create an immutable <type>GBytes</type> from
a mutable <type>GByteArray</type>, use the <function>g_byte_array_free_to_bytes()</function> function.</para></refsect1><refsect1><title>Functions</title><refsect2><title>compare</title><informalexample><programlisting>(define-values (%return) (bytes:compare self bytes2))
</programlisting></informalexample><para>Compares the two <type>GBytes</type> values.
</para>
<para>This function can be used to sort GBytes instances in lexicographical order.
</para>
<para>If <parameter>bytes1</parameter> and <parameter>bytes2</parameter> 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 <parameter>bytes1</parameter> has a smaller value at that position it is
considered less, otherwise greater than <parameter>bytes2</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>bytes1</para></td><td class="parameter_description"><para>a pointer to a <type>GBytes</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>bytes2</para></td><td class="parameter_description"><para>a pointer to a <type>GBytes</type> to compare with <parameter>bytes1</parameter></para><para>Passed as <code>bytes2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>equal?</title><informalexample><programlisting>(define-values (%return) (bytes:equal? self bytes2))
</programlisting></informalexample><para>Compares the two <type>GBytes</type> values being pointed to and returns
<constant>TRUE</constant> if they are equal.
</para>
<para>This function can be passed to <function>g_hash_table_new()</function> as the <parameter>key_equal_func</parameter>
parameter, when using non-<constant>NULL</constant> <type>GBytes</type> pointers as keys in a <type>GHashTable</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>bytes1</para></td><td class="parameter_description"><para>a pointer to a <type>GBytes</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>bytes2</para></td><td class="parameter_description"><para>a pointer to a <type>GBytes</type> to compare with <parameter>bytes1</parameter></para><para>Passed as <code>bytes2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-data</title><informalexample><programlisting>(define-values (%return size) (bytes:get-data self))
</programlisting></informalexample><para>Get the byte data in the <type>GBytes</type>. This data should not be modified.
</para>
<para>This function will always return the same pointer for a given <type>GBytes</type>.
</para>
<para><constant>NULL</constant> may be returned if <parameter>size</parameter> is 0. This is not guaranteed, as the <type>GBytes</type>
may represent an empty string with <parameter>data</parameter> non-<constant>NULL</constant> and <parameter>size</parameter> as 0. <constant>NULL</constant> will
not be returned if <parameter>size</parameter> is non-zero.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>bytes</para></td><td class="parameter_description"><para>a <type>GBytes</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>size</para></td><td class="parameter_description"><para>location to return size of byte data</para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-region</title><informalexample><programlisting>(define-values
  (%return)
  (bytes:get-region self element-size offset n-elements))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>bytes</para></td><td class="parameter_description"><para></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>element_size</para></td><td class="parameter_description"><para></para><para>Passed as <code>element-size</code></para></td></tr><tr><td class="parameter_name"><para>offset</para></td><td class="parameter_description"><para></para><para>Passed as <code>offset</code></para></td></tr><tr><td class="parameter_name"><para>n_elements</para></td><td class="parameter_description"><para></para><para>Passed as <code>n-elements</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-size</title><informalexample><programlisting>(define-values (%return) (bytes:get-size self))
</programlisting></informalexample><para>Get the size of the byte data in the <type>GBytes</type>.
</para>
<para>This function will always return the same value for a given <type>GBytes</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>bytes</para></td><td class="parameter_description"><para>a <type>GBytes</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash</title><informalexample><programlisting>(define-values (%return) (bytes:hash self))
</programlisting></informalexample><para>Creates an integer hash code for the byte data in the <type>GBytes</type>.
</para>
<para>This function can be passed to <function>g_hash_table_new()</function> as the <parameter>key_hash_func</parameter>
parameter, when using non-<constant>NULL</constant> <type>GBytes</type> pointers as keys in a <type>GHashTable</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>bytes</para></td><td class="parameter_description"><para>a pointer to a <type>GBytes</type> key</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>new-from-bytes</title><informalexample><programlisting>(define-values (%return) (bytes:new-from-bytes self offset length))
</programlisting></informalexample><para>Creates a <type>GBytes</type> which is a subsection of another <type>GBytes</type>. The <parameter>offset</parameter> +
<parameter>length</parameter> may not be longer than the size of <parameter>bytes</parameter>.
</para>
<para>A reference to <parameter>bytes</parameter> will be held by the newly created <type>GBytes</type> until
the byte data is no longer needed.
</para>
<para>Since 2.56, if <parameter>offset</parameter> is 0 and <parameter>length</parameter> matches the size of <parameter>bytes</parameter>, then
<parameter>bytes</parameter> will be returned with the reference count incremented by 1. If <parameter>bytes</parameter>
is a slice of another <type>GBytes</type>, then the resulting <type>GBytes</type> will reference
the same <type>GBytes</type> instead of <parameter>bytes</parameter>. This allows consumers to simplify the
usage of <type>GBytes</type> when asynchronously writing to streams.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>bytes</para></td><td class="parameter_description"><para>a <type>GBytes</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>offset</para></td><td class="parameter_description"><para>offset which subsection starts at</para><para>Passed as <code>offset</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>length of subsection</para><para>Passed as <code>length</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref</title><informalexample><programlisting>(define-values (%return) (bytes:ref self))
</programlisting></informalexample><para>Increase the reference count on <parameter>bytes</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>bytes</para></td><td class="parameter_description"><para>a <type>GBytes</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (bytes:unref self))
</programlisting></informalexample><para>Releases a reference on <parameter>bytes</parameter>.  This may result in the bytes being
freed. If <parameter>bytes</parameter> is <constant>NULL</constant>, it will return immediately.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>bytes</para></td><td class="parameter_description"><para>a <type>GBytes</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref-to-array</title><informalexample><programlisting>(define-values (%return) (bytes:unref-to-array self))
</programlisting></informalexample><para>Unreferences the bytes, and returns a new mutable <type>GByteArray</type> containing
the same byte data.
</para>
<para>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
<function>g_bytes_new()</function>, <function>g_bytes_new_take()</function> or <function>g_byte_array_free_to_bytes()</function>. In all
other cases the data is copied.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>bytes</para></td><td class="parameter_description"><para>a <type>GBytes</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref-to-data</title><informalexample><programlisting>(define-values (%return size) (bytes:unref-to-data self))
</programlisting></informalexample><para>Unreferences the bytes, and returns a pointer the same byte data
contents.
</para>
<para>As an optimization, the byte data is returned without copying if this was
the last reference to bytes and bytes was created with <function>g_bytes_new()</function>,
<function>g_bytes_new_take()</function> or <function>g_byte_array_free_to_bytes()</function>. In all other cases the
data is copied.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>bytes</para></td><td class="parameter_description"><para>a <type>GBytes</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>size</para></td><td class="parameter_description"><para>location to place the length of the returned data</para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>bytes:new-take</title><informalexample><programlisting>(define-values (%return) (bytes:new-take data))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para></para><para>Passed as <code>data</code></para></td></tr><tr><td class="parameter_name"><para>size</para></td><td class="parameter_description"><para></para><para>Inferred from <code>data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>bytes:new</title><informalexample><programlisting>(define-values (%return) (bytes:new data))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para></para><para>Passed as <code>data</code></para></td></tr><tr><td class="parameter_name"><para>size</para></td><td class="parameter_description"><para></para><para>Inferred from <code>data</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GChecksum&gt;</refname></refnamediv><refsect1><title>Description</title><para>An opaque structure representing a checksumming operation.
</para>
<para>To create a new GChecksum, use <function>g_checksum_new()</function>. To free
a GChecksum, use <function>g_checksum_free()</function>.</para></refsect1><refsect1><title>Functions</title><refsect2><title>copy</title><informalexample><programlisting>(define-values (%return) (checksum:copy self))
</programlisting></informalexample><para>Copies a <type>GChecksum</type>. If <parameter>checksum</parameter> has been closed, by calling
<function>g_checksum_get_string()</function> or <function>g_checksum_get_digest()</function>, the copied
checksum will be closed as well.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>checksum</para></td><td class="parameter_description"><para>the <type>GChecksum</type> to copy</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>free</title><informalexample><programlisting>(define-values () (checksum:free self))
</programlisting></informalexample><para>Frees the memory allocated for <parameter>checksum</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>checksum</para></td><td class="parameter_description"><para>a <type>GChecksum</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-string</title><informalexample><programlisting>(define-values (%return) (checksum:get-string self))
</programlisting></informalexample><para>Gets the digest as a hexadecimal string.
</para>
<para>Once this function has been called the <type>GChecksum</type> can no longer be
updated with <function>g_checksum_update()</function>.
</para>
<para>The hexadecimal characters will be lower case.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>checksum</para></td><td class="parameter_description"><para>a <type>GChecksum</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>reset</title><informalexample><programlisting>(define-values () (checksum:reset self))
</programlisting></informalexample><para>Resets the state of the <parameter>checksum</parameter> back to its initial state.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>checksum</para></td><td class="parameter_description"><para>the <type>GChecksum</type> to reset</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>update</title><informalexample><programlisting>(define-values () (checksum:update self data))
</programlisting></informalexample><para>Feeds <parameter>data</parameter> into an existing <type>GChecksum</type>. The checksum must still be
open, that is <function>g_checksum_get_string()</function> or <function>g_checksum_get_digest()</function> must
not have been called on <parameter>checksum</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>checksum</para></td><td class="parameter_description"><para>a <type>GChecksum</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>buffer used to compute the checksum</para><para>Passed as <code>data</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>size of the buffer, or -1 if it is a null-terminated string.</para><para>Inferred from <code>data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>checksum:new</title><informalexample><programlisting>(define-values (%return) (checksum:new checksum-type))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>checksum_type</para></td><td class="parameter_description"><para></para><para>Passed as <code>checksum-type</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>checksum:type-get-length</title><informalexample><programlisting>(define-values (%return) (checksum:type-get-length checksum-type))
</programlisting></informalexample><para>Gets the length in bytes of digests of type <parameter>checksum_type</parameter></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>checksum_type</para></td><td class="parameter_description"><para>a <type>GChecksumType</type></para><para>Passed as <code>checksum-type</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibChecksumType&gt;</refname></refnamediv><refsect1><title>Description</title><para>The hashing algorithm to be used by <type>GChecksum</type> when performing the
digest of some data.
</para>
<para>Note that the <type>GChecksumType</type> enumeration may be extended at a later
date to include new hashing algorithm types.</para></refsect1><refsect1><title>Members</title><refsect2><title>md5</title><remark>alias <code>G_CHECKSUM_MD5</code></remark><para>Use the MD5 hashing algorithm</para></refsect2><refsect2><title>sha1</title><remark>alias <code>G_CHECKSUM_SHA1</code></remark><para>Use the SHA-1 hashing algorithm</para></refsect2><refsect2><title>sha256</title><remark>alias <code>G_CHECKSUM_SHA256</code></remark><para>Use the SHA-256 hashing algorithm</para></refsect2><refsect2><title>sha512</title><remark>alias <code>G_CHECKSUM_SHA512</code></remark><para>Use the SHA-512 hashing algorithm (Since: 2.36)</para></refsect2><refsect2><title>sha384</title><remark>alias <code>G_CHECKSUM_SHA384</code></remark><para>Use the SHA-384 hashing algorithm (Since: 2.51)</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibConvertError&gt;</refname></refnamediv><refsect1><title>Description</title><para>Error codes returned by character set conversion routines.</para></refsect1><refsect1><title>Members</title><refsect2><title>no-conversion</title><remark>alias <code>G_CONVERT_ERROR_NO_CONVERSION</code></remark><para>Conversion between the requested character
    sets is not supported.</para></refsect2><refsect2><title>illegal-sequence</title><remark>alias <code>G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code></remark><para>Invalid byte sequence in conversion input;
   or the character sequence could not be represented in the target
   character set.</para></refsect2><refsect2><title>failed</title><remark>alias <code>G_CONVERT_ERROR_FAILED</code></remark><para>Conversion failed for some reason.</para></refsect2><refsect2><title>partial-input</title><remark>alias <code>G_CONVERT_ERROR_PARTIAL_INPUT</code></remark><para>Partial character sequence at end of input.</para></refsect2><refsect2><title>bad-uri</title><remark>alias <code>G_CONVERT_ERROR_BAD_URI</code></remark><para>URI is invalid.</para></refsect2><refsect2><title>not-absolute-path</title><remark>alias <code>G_CONVERT_ERROR_NOT_ABSOLUTE_PATH</code></remark><para>Pathname is not an absolute path.</para></refsect2><refsect2><title>no-memory</title><remark>alias <code>G_CONVERT_ERROR_NO_MEMORY</code></remark><para>No memory available. Since: 2.40</para></refsect2><refsect2><title>embedded-nul</title><remark>alias <code>G_CONVERT_ERROR_EMBEDDED_NUL</code></remark><para>An embedded NUL character is present in
    conversion output where a NUL-terminated string is expected.
    Since: 2.56</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GDate&gt;</refname></refnamediv><refsect1><title>Description</title><para>Represents a day between January 1, Year 1 and a few thousand years in
the future. None of its members should be accessed directly.
</para>
<para>If the <type>GDate</type>-struct is obtained from <function>g_date_new()</function>, it will be safe
to mutate but invalid and thus not safe for calendrical computations.
</para>
<para>If it's declared on the stack, it will contain garbage so must be
initialized with <function>g_date_clear()</function>. <function>g_date_clear()</function> makes the date invalid
but safe. An invalid date doesn't represent a day, it's &quot;empty.&quot; A date
becomes valid after you set it to a Julian day or you set a day, month,
and year.</para></refsect1><refsect1><title>Functions</title><refsect2><title>add-days</title><informalexample><programlisting>(define-values () (date:add-days self n-days))
</programlisting></informalexample><para>Increments a date some number of days.
To move forward by weeks, add weeks*7 days.
The date must be valid.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to increment</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>n_days</para></td><td class="parameter_description"><para>number of days to move the date forward</para><para>Passed as <code>n-days</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>add-months</title><informalexample><programlisting>(define-values () (date:add-months self n-months))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to increment</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>n_months</para></td><td class="parameter_description"><para>number of months to move forward</para><para>Passed as <code>n-months</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>add-years</title><informalexample><programlisting>(define-values () (date:add-years self n-years))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to increment</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>n_years</para></td><td class="parameter_description"><para>number of years to move forward</para><para>Passed as <code>n-years</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>clamp</title><informalexample><programlisting>(define-values () (date:clamp self min-date max-date))
</programlisting></informalexample><para>If <parameter>date</parameter> is prior to <parameter>min_date</parameter>, sets <parameter>date</parameter> equal to <parameter>min_date</parameter>.
If <parameter>date</parameter> falls after <parameter>max_date</parameter>, sets <parameter>date</parameter> equal to <parameter>max_date</parameter>.
Otherwise, <parameter>date</parameter> is unchanged.
Either of <parameter>min_date</parameter> and <parameter>max_date</parameter> may be <constant>NULL</constant>.
All non-<constant>NULL</constant> dates must be valid.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to clamp</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>min_date</para></td><td class="parameter_description"><para>minimum accepted value for <parameter>date</parameter></para><para>Passed as <code>min-date</code></para></td></tr><tr><td class="parameter_name"><para>max_date</para></td><td class="parameter_description"><para>maximum accepted value for <parameter>date</parameter></para><para>Passed as <code>max-date</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>clear</title><informalexample><programlisting>(define-values () (date:clear self n-dates))
</programlisting></informalexample><para>Initializes one or more <type>GDate</type> 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 <function>g_date_valid()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>pointer to one or more dates to clear</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>n_dates</para></td><td class="parameter_description"><para>number of dates to clear</para><para>Passed as <code>n-dates</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>compare</title><informalexample><programlisting>(define-values (%return) (date:compare self rhs))
</programlisting></informalexample><para><function>qsort()</function>-style comparison function for dates.
Both dates must be valid.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>lhs</para></td><td class="parameter_description"><para>first date to compare</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>rhs</para></td><td class="parameter_description"><para>second date to compare</para><para>Passed as <code>rhs</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>copy</title><informalexample><programlisting>(define-values (%return) (date:copy self))
</programlisting></informalexample><para>Copies a GDate to a newly-allocated GDate. If the input was invalid
(as determined by <function>g_date_valid()</function>), the invalid state will be copied
as is into the new object.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to copy</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>days-between</title><informalexample><programlisting>(define-values (%return) (date:days-between self date2))
</programlisting></informalexample><para>Computes the number of days between two dates.
If <parameter>date2</parameter> is prior to <parameter>date1</parameter>, the returned value is negative.
Both dates must be valid.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date1</para></td><td class="parameter_description"><para>the first date</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>date2</para></td><td class="parameter_description"><para>the second date</para><para>Passed as <code>date2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>free</title><informalexample><programlisting>(define-values () (date:free self))
</programlisting></informalexample><para>Frees a <type>GDate</type> returned from <function>g_date_new()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to free</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-day</title><informalexample><programlisting>(define-values (%return) (date:get-day self))
</programlisting></informalexample><para>Returns the day of the month. The date must be valid.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to extract the day of the month from</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-day-of-year</title><informalexample><programlisting>(define-values (%return) (date:get-day-of-year self))
</programlisting></informalexample><para>Returns the day of the year, where Jan 1 is the first day of the
year. The date must be valid.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to extract day of year from</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-iso8601-week-of-year</title><informalexample><programlisting>(define-values (%return) (date:get-iso8601-week-of-year self))
</programlisting></informalexample><para>Returns the week of the year, where weeks are interpreted according
to ISO 8601.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a valid <type>GDate</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-julian</title><informalexample><programlisting>(define-values (%return) (date:get-julian self))
</programlisting></informalexample><para>Returns the Julian day or &quot;serial number&quot; of the <type>GDate</type>. 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to extract the Julian day from</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-monday-week-of-year</title><informalexample><programlisting>(define-values (%return) (date:get-monday-week-of-year self))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-month</title><informalexample><programlisting>(define-values (%return) (date:get-month self))
</programlisting></informalexample><para>Returns the month of the year. The date must be valid.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to get the month from</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-sunday-week-of-year</title><informalexample><programlisting>(define-values (%return) (date:get-sunday-week-of-year self))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-weekday</title><informalexample><programlisting>(define-values (%return) (date:get-weekday self))
</programlisting></informalexample><para>Returns the day of the week for a <type>GDate</type>. The date must be valid.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-year</title><informalexample><programlisting>(define-values (%return) (date:get-year self))
</programlisting></informalexample><para>Returns the year of a <type>GDate</type>. The date must be valid.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-first-of-month?</title><informalexample><programlisting>(define-values (%return) (date:is-first-of-month? self))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the date is on the first of a month.
The date must be valid.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to check</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-last-of-month?</title><informalexample><programlisting>(define-values (%return) (date:is-last-of-month? self))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the date is the last day of the month.
The date must be valid.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to check</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>order</title><informalexample><programlisting>(define-values () (date:order self date2))
</programlisting></informalexample><para>Checks if <parameter>date1</parameter> is less than or equal to <parameter>date2</parameter>,
and swap the values if this is not the case.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date1</para></td><td class="parameter_description"><para>the first date</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>date2</para></td><td class="parameter_description"><para>the second date</para><para>Passed as <code>date2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-day</title><informalexample><programlisting>(define-values () (date:set-day self day))
</programlisting></informalexample><para>Sets the day of the month for a <type>GDate</type>. If the resulting
day-month-year triplet is invalid, the date will be invalid.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>day</para></td><td class="parameter_description"><para>day to set</para><para>Passed as <code>day</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-dmy</title><informalexample><programlisting>(define-values () (date:set-dmy self day month y))
</programlisting></informalexample><para>Sets the value of a <type>GDate</type> from a day, month, and year.
The day-month-year triplet must be valid; if you aren't
sure it is, call <function>g_date_valid_dmy()</function> to check before you
set it.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>day</para></td><td class="parameter_description"><para>day</para><para>Passed as <code>day</code></para></td></tr><tr><td class="parameter_name"><para>month</para></td><td class="parameter_description"><para>month</para><para>Passed as <code>month</code></para></td></tr><tr><td class="parameter_name"><para>y</para></td><td class="parameter_description"><para>year</para><para>Passed as <code>y</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-julian</title><informalexample><programlisting>(define-values () (date:set-julian self julian-date))
</programlisting></informalexample><para>Sets the value of a <type>GDate</type> from a Julian day number.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>julian_date</para></td><td class="parameter_description"><para>Julian day number (days since January 1, Year 1)</para><para>Passed as <code>julian-date</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-month</title><informalexample><programlisting>(define-values () (date:set-month self month))
</programlisting></informalexample><para>Sets the month of the year for a <type>GDate</type>.  If the resulting
day-month-year triplet is invalid, the date will be invalid.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>month</para></td><td class="parameter_description"><para>month to set</para><para>Passed as <code>month</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-parse</title><informalexample><programlisting>(define-values () (date:set-parse self str))
</programlisting></informalexample><para>Parses a user-inputted string <parameter>str</parameter>, 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 <function>g_date_valid()</function>
to see whether the parsing succeeded.
</para>
<para>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).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to fill in</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>string to parse</para><para>Passed as <code>str</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-time</title><informalexample><programlisting>(define-values () (date:set-time self time-))
</programlisting></informalexample><para>Sets the value of a date from a <type>GTime</type> value.
The time to date conversion is done using the user's current timezone.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type>.</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>time_</para></td><td class="parameter_description"><para><type>GTime</type> value to set.</para><para>Passed as <code>time-</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-time-t</title><informalexample><programlisting>(define-values () (date:set-time-t self timet))
</programlisting></informalexample><para>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.
</para>
<para>To set the value of a date to the current day, you could write:
<informalexample><programlisting>
 time_t now = time (NULL);
 if (now == (time_t) -1)
   // handle the error
 g_date_set_time_t (date, now);
</programlisting></informalexample></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>timet</para></td><td class="parameter_description"><para>time_t value to set</para><para>Passed as <code>timet</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-year</title><informalexample><programlisting>(define-values () (date:set-year self year))
</programlisting></informalexample><para>Sets the year for a <type>GDate</type>. If the resulting day-month-year
triplet is invalid, the date will be invalid.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para>year to set</para><para>Passed as <code>year</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>subtract-days</title><informalexample><programlisting>(define-values () (date:subtract-days self n-days))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to decrement</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>n_days</para></td><td class="parameter_description"><para>number of days to move</para><para>Passed as <code>n-days</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>subtract-months</title><informalexample><programlisting>(define-values () (date:subtract-months self n-months))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to decrement</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>n_months</para></td><td class="parameter_description"><para>number of months to move</para><para>Passed as <code>n-months</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>subtract-years</title><informalexample><programlisting>(define-values () (date:subtract-years self n-years))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to decrement</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>n_years</para></td><td class="parameter_description"><para>number of years to move</para><para>Passed as <code>n-years</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>to-struct-tm</title><informalexample><programlisting>(define-values () (date:to-struct-tm self tm))
</programlisting></informalexample><para>Fills in the date-related bits of a struct tm using the <parameter>date</parameter> value.
Initializes the non-date parts with something safe but meaningless.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to set the struct tm from</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>tm</para></td><td class="parameter_description"><para>struct tm to fill</para><para>Passed as <code>tm</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>valid?</title><informalexample><programlisting>(define-values (%return) (date:valid? self))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the <type>GDate</type> represents an existing day. The date must not
contain garbage; it should have been initialized with <function>g_date_clear()</function>
if it wasn't allocated by one of the <function>g_date_new()</function> variants.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>a <type>GDate</type> to check</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date:new-julian</title><informalexample><programlisting>(define-values (%return) (date:new-julian julian-day))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>julian_day</para></td><td class="parameter_description"><para></para><para>Passed as <code>julian-day</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date:new-dmy</title><informalexample><programlisting>(define-values (%return) (date:new-dmy day month year))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>day</para></td><td class="parameter_description"><para></para><para>Passed as <code>day</code></para></td></tr><tr><td class="parameter_name"><para>month</para></td><td class="parameter_description"><para></para><para>Passed as <code>month</code></para></td></tr><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para></para><para>Passed as <code>year</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date:new</title><informalexample><programlisting>(define-values (%return) (date:new))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>date:get-days-in-month</title><informalexample><programlisting>(define-values (%return) (date:get-days-in-month month year))
</programlisting></informalexample><para>Returns the number of days in a month, taking leap
years into account.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>month</para></td><td class="parameter_description"><para>month</para><para>Passed as <code>month</code></para></td></tr><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para>year</para><para>Passed as <code>year</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date:get-monday-weeks-in-year</title><informalexample><programlisting>(define-values (%return) (date:get-monday-weeks-in-year year))
</programlisting></informalexample><para>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.)</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para>a year</para><para>Passed as <code>year</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date:get-sunday-weeks-in-year</title><informalexample><programlisting>(define-values (%return) (date:get-sunday-weeks-in-year year))
</programlisting></informalexample><para>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.)</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para>year to count weeks in</para><para>Passed as <code>year</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date:is-leap-year?</title><informalexample><programlisting>(define-values (%return) (date:is-leap-year? year))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the year is a leap year.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para>year to check</para><para>Passed as <code>year</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date:strftime</title><informalexample><programlisting>(define-values (%return) (date:strftime s slen format date))
</programlisting></informalexample><para>Generates a printed representation of the date, in a
[locale][setlocale]-specific way.
Works just like the platform's C library <function>strftime()</function> function,
but only accepts date-related formats; time-related formats
give undefined results. Date must be valid. Unlike <function>strftime()</function>
(which uses the locale encoding), works on a UTF-8 format
string and stores a UTF-8 result.
</para>
<para>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 <function>g_date_strftime()</function> would
make the \%F provided by the C99 <function>strftime()</function> work on Windows
where the C library only complies to C89.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>s</para></td><td class="parameter_description"><para>destination buffer</para><para>Passed as <code>s</code></para></td></tr><tr><td class="parameter_name"><para>slen</para></td><td class="parameter_description"><para>buffer size</para><para>Passed as <code>slen</code></para></td></tr><tr><td class="parameter_name"><para>format</para></td><td class="parameter_description"><para>format string</para><para>Passed as <code>format</code></para></td></tr><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>valid <type>GDate</type></para><para>Passed as <code>date</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date:valid-day?</title><informalexample><programlisting>(define-values (%return) (date:valid-day? day))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the day of the month is valid (a day is valid if it's
between 1 and 31 inclusive).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>day</para></td><td class="parameter_description"><para>day to check</para><para>Passed as <code>day</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date:valid-dmy?</title><informalexample><programlisting>(define-values (%return) (date:valid-dmy? day month year))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the day-month-year triplet forms a valid, existing day
in the range of days <type>GDate</type> understands (Year 1 or later, no more than
a few thousand years in the future).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>day</para></td><td class="parameter_description"><para>day</para><para>Passed as <code>day</code></para></td></tr><tr><td class="parameter_name"><para>month</para></td><td class="parameter_description"><para>month</para><para>Passed as <code>month</code></para></td></tr><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para>year</para><para>Passed as <code>year</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date:valid-julian?</title><informalexample><programlisting>(define-values (%return) (date:valid-julian? julian-date))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the Julian day is valid. Anything greater than zero
is basically a valid Julian, though there is a 32-bit limit.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>julian_date</para></td><td class="parameter_description"><para>Julian day to check</para><para>Passed as <code>julian-date</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date:valid-month?</title><informalexample><programlisting>(define-values (%return) (date:valid-month? month))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the month value is valid. The 12 <type>GDateMonth</type>
enumeration values are the only valid months.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>month</para></td><td class="parameter_description"><para>month</para><para>Passed as <code>month</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date:valid-weekday?</title><informalexample><programlisting>(define-values (%return) (date:valid-weekday? weekday))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the weekday is valid. The seven <type>GDateWeekday</type> enumeration
values are the only valid weekdays.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>weekday</para></td><td class="parameter_description"><para>weekday</para><para>Passed as <code>weekday</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date:valid-year?</title><informalexample><programlisting>(define-values (%return) (date:valid-year? year))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the year is valid. Any year greater than 0 is valid,
though there is a 16-bit limit to what <type>GDate</type> will understand.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para>year</para><para>Passed as <code>year</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibDateDMY&gt;</refname></refnamediv><refsect1><title>Description</title><para>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.</para></refsect1><refsect1><title>Members</title><refsect2><title>day</title><remark>alias <code>G_DATE_DAY</code></remark><para>a day</para></refsect2><refsect2><title>month</title><remark>alias <code>G_DATE_MONTH</code></remark><para>a month</para></refsect2><refsect2><title>year</title><remark>alias <code>G_DATE_YEAR</code></remark><para>a year</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibDateMonth&gt;</refname></refnamediv><refsect1><title>Description</title><para>Enumeration representing a month; values are <type>G_DATE_JANUARY</type>,
<type>G_DATE_FEBRUARY</type>, etc. <type>G_DATE_BAD_MONTH</type> is the invalid value.</para></refsect1><refsect1><title>Members</title><refsect2><title>bad-month</title><remark>alias <code>G_DATE_BAD_MONTH</code></remark><para>invalid value</para></refsect2><refsect2><title>january</title><remark>alias <code>G_DATE_JANUARY</code></remark><para>January</para></refsect2><refsect2><title>february</title><remark>alias <code>G_DATE_FEBRUARY</code></remark><para>February</para></refsect2><refsect2><title>march</title><remark>alias <code>G_DATE_MARCH</code></remark><para>March</para></refsect2><refsect2><title>april</title><remark>alias <code>G_DATE_APRIL</code></remark><para>April</para></refsect2><refsect2><title>may</title><remark>alias <code>G_DATE_MAY</code></remark><para>May</para></refsect2><refsect2><title>june</title><remark>alias <code>G_DATE_JUNE</code></remark><para>June</para></refsect2><refsect2><title>july</title><remark>alias <code>G_DATE_JULY</code></remark><para>July</para></refsect2><refsect2><title>august</title><remark>alias <code>G_DATE_AUGUST</code></remark><para>August</para></refsect2><refsect2><title>september</title><remark>alias <code>G_DATE_SEPTEMBER</code></remark><para>September</para></refsect2><refsect2><title>october</title><remark>alias <code>G_DATE_OCTOBER</code></remark><para>October</para></refsect2><refsect2><title>november</title><remark>alias <code>G_DATE_NOVEMBER</code></remark><para>November</para></refsect2><refsect2><title>december</title><remark>alias <code>G_DATE_DECEMBER</code></remark><para>December</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GDateTime&gt;</refname></refnamediv><refsect1><title>Description</title><para>An opaque structure that represents a date and time, including a time zone.</para></refsect1><refsect1><title>Functions</title><refsect2><title>add</title><informalexample><programlisting>(define-values (%return) (date-time:add self timespan))
</programlisting></informalexample><para>Creates a copy of <parameter>datetime</parameter> and adds the specified timespan to the copy.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>timespan</para></td><td class="parameter_description"><para>a <type>GTimeSpan</type></para><para>Passed as <code>timespan</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>add-days</title><informalexample><programlisting>(define-values (%return) (date-time:add-days self days))
</programlisting></informalexample><para>Creates a copy of <parameter>datetime</parameter> and adds the specified number of days to the
copy. Add negative values to subtract days.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>days</para></td><td class="parameter_description"><para>the number of days</para><para>Passed as <code>days</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>add-full</title><informalexample><programlisting>(define-values
  (%return)
  (date-time:add-full self years months days hours minutes seconds))
</programlisting></informalexample><para>Creates a new <type>GDateTime</type> adding the specified values to the current date and
time in <parameter>datetime</parameter>. Add negative values to subtract.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>years</para></td><td class="parameter_description"><para>the number of years to add</para><para>Passed as <code>years</code></para></td></tr><tr><td class="parameter_name"><para>months</para></td><td class="parameter_description"><para>the number of months to add</para><para>Passed as <code>months</code></para></td></tr><tr><td class="parameter_name"><para>days</para></td><td class="parameter_description"><para>the number of days to add</para><para>Passed as <code>days</code></para></td></tr><tr><td class="parameter_name"><para>hours</para></td><td class="parameter_description"><para>the number of hours to add</para><para>Passed as <code>hours</code></para></td></tr><tr><td class="parameter_name"><para>minutes</para></td><td class="parameter_description"><para>the number of minutes to add</para><para>Passed as <code>minutes</code></para></td></tr><tr><td class="parameter_name"><para>seconds</para></td><td class="parameter_description"><para>the number of seconds to add</para><para>Passed as <code>seconds</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>add-hours</title><informalexample><programlisting>(define-values (%return) (date-time:add-hours self hours))
</programlisting></informalexample><para>Creates a copy of <parameter>datetime</parameter> and adds the specified number of hours.
Add negative values to subtract hours.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>hours</para></td><td class="parameter_description"><para>the number of hours to add</para><para>Passed as <code>hours</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>add-minutes</title><informalexample><programlisting>(define-values (%return) (date-time:add-minutes self minutes))
</programlisting></informalexample><para>Creates a copy of <parameter>datetime</parameter> adding the specified number of minutes.
Add negative values to subtract minutes.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>minutes</para></td><td class="parameter_description"><para>the number of minutes to add</para><para>Passed as <code>minutes</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>add-months</title><informalexample><programlisting>(define-values (%return) (date-time:add-months self months))
</programlisting></informalexample><para>Creates a copy of <parameter>datetime</parameter> and adds the specified number of months to the
copy. Add negative values to subtract months.
</para>
<para>The day of the month of the resulting <type>GDateTime</type> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>months</para></td><td class="parameter_description"><para>the number of months</para><para>Passed as <code>months</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>add-seconds</title><informalexample><programlisting>(define-values (%return) (date-time:add-seconds self seconds))
</programlisting></informalexample><para>Creates a copy of <parameter>datetime</parameter> and adds the specified number of seconds.
Add negative values to subtract seconds.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>seconds</para></td><td class="parameter_description"><para>the number of seconds to add</para><para>Passed as <code>seconds</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>add-weeks</title><informalexample><programlisting>(define-values (%return) (date-time:add-weeks self weeks))
</programlisting></informalexample><para>Creates a copy of <parameter>datetime</parameter> and adds the specified number of weeks to the
copy. Add negative values to subtract weeks.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>weeks</para></td><td class="parameter_description"><para>the number of weeks</para><para>Passed as <code>weeks</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>add-years</title><informalexample><programlisting>(define-values (%return) (date-time:add-years self years))
</programlisting></informalexample><para>Creates a copy of <parameter>datetime</parameter> and adds the specified number of years to the
copy. Add negative values to subtract years.
</para>
<para>As with <function>g_date_time_add_months()</function>, if the resulting date would be 29th
February on a non-leap year, the day will be clamped to 28th February.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>years</para></td><td class="parameter_description"><para>the number of years</para><para>Passed as <code>years</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>difference</title><informalexample><programlisting>(define-values (%return) (date-time:difference self begin))
</programlisting></informalexample><para>Calculates the difference in time between <parameter>end</parameter> and <parameter>begin</parameter>.  The
<type>GTimeSpan</type> that is returned is effectively <parameter>end</parameter> - <parameter>begin</parameter> (ie:
positive if the first parameter is larger).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>end</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>begin</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>begin</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>format</title><informalexample><programlisting>(define-values (%return) (date-time:format self format))
</programlisting></informalexample><para>Creates a newly allocated string representing the requested <parameter>format</parameter>.
</para>
<para>The format strings understood by this function are a subset of the
<function>strftime()</function> 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.
</para>
<para>In contrast to <function>strftime()</function>, 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 <function>strftime()</function>
output exactly.
</para>
<para>The following format specifiers are supported:
</para>
<para>- \%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 <code>%Y-%m-%d</code> (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 &quot;AM&quot; or &quot;PM&quot; according to the given time value, or the
  corresponding  strings for the current locale.  Noon is treated as
  &quot;PM&quot; and midnight as &quot;AM&quot;. 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: &quot;am&quot; or &quot;pm&quot; 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 <function>g_date_time_get_week_of_year()</function>.
  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 <function>strftime()</function> extension. Since: 2.38
- \%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a
  gnulib <function>strftime()</function> 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 <function>strftime()</function> extension. Since: 2.38
- \%Z: the time zone or name or abbreviation
- \%\%: a literal \% character
</para>
<para>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:
</para>
<para>- 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.
</para>
<para>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
<function>strftime()</function> extension expected to be added to the future POSIX specification,
\%Ob and \%Oh are GNU <function>strftime()</function> extensions. Since: 2.56</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>A <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>format</para></td><td class="parameter_description"><para>a valid UTF-8 string, containing the format for the
         <type>GDateTime</type></para><para>Passed as <code>format</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>format-iso8601</title><informalexample><programlisting>(define-values (%return) (date-time:format-iso8601 self))
</programlisting></informalexample><para>Format <parameter>datetime</parameter> 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.
</para>
<para>Since GLib 2.66, this will output to sub-second precision if needed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>A <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-day-of-month</title><informalexample><programlisting>(define-values (%return) (date-time:get-day-of-month self))
</programlisting></informalexample><para>Retrieves the day of the month represented by <parameter>datetime</parameter> in the gregorian
calendar.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-day-of-week</title><informalexample><programlisting>(define-values (%return) (date-time:get-day-of-week self))
</programlisting></informalexample><para>Retrieves the ISO 8601 day of the week on which <parameter>datetime</parameter> falls (1 is
Monday, 2 is Tuesday... 7 is Sunday).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-day-of-year</title><informalexample><programlisting>(define-values (%return) (date-time:get-day-of-year self))
</programlisting></informalexample><para>Retrieves the day of the year represented by <parameter>datetime</parameter> in the Gregorian
calendar.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-hour</title><informalexample><programlisting>(define-values (%return) (date-time:get-hour self))
</programlisting></informalexample><para>Retrieves the hour of the day represented by <parameter>datetime</parameter></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-microsecond</title><informalexample><programlisting>(define-values (%return) (date-time:get-microsecond self))
</programlisting></informalexample><para>Retrieves the microsecond of the date represented by <parameter>datetime</parameter></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-minute</title><informalexample><programlisting>(define-values (%return) (date-time:get-minute self))
</programlisting></informalexample><para>Retrieves the minute of the hour represented by <parameter>datetime</parameter></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-month</title><informalexample><programlisting>(define-values (%return) (date-time:get-month self))
</programlisting></informalexample><para>Retrieves the month of the year represented by <parameter>datetime</parameter> in the Gregorian
calendar.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-second</title><informalexample><programlisting>(define-values (%return) (date-time:get-second self))
</programlisting></informalexample><para>Retrieves the second of the minute represented by <parameter>datetime</parameter></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-seconds</title><informalexample><programlisting>(define-values (%return) (date-time:get-seconds self))
</programlisting></informalexample><para>Retrieves the number of seconds since the start of the last minute,
including the fractional part.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-timezone</title><informalexample><programlisting>(define-values (%return) (date-time:get-timezone self))
</programlisting></informalexample><para>Get the time zone for this <parameter>datetime</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-timezone-abbreviation</title><informalexample><programlisting>(define-values (%return) (date-time:get-timezone-abbreviation self))
</programlisting></informalexample><para>Determines the time zone abbreviation to be used at the time and in
the time zone of <parameter>datetime</parameter>.
</para>
<para>For example, in Toronto this is currently &quot;EST&quot; during the winter
months and &quot;EDT&quot; during the summer months when daylight savings
time is in effect.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-utc-offset</title><informalexample><programlisting>(define-values (%return) (date-time:get-utc-offset self))
</programlisting></informalexample><para>Determines the offset to UTC in effect at the time and in the time
zone of <parameter>datetime</parameter>.
</para>
<para>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).
</para>
<para>If <parameter>datetime</parameter> represents UTC time, then the offset is always zero.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-week-numbering-year</title><informalexample><programlisting>(define-values (%return) (date-time:get-week-numbering-year self))
</programlisting></informalexample><para>Returns the ISO 8601 week-numbering year in which the week containing
<parameter>datetime</parameter> falls.
</para>
<para>This function, taken together with <function>g_date_time_get_week_of_year()</function> and
<function>g_date_time_get_day_of_week()</function> can be used to determine the full ISO
week date on which <parameter>datetime</parameter> falls.
</para>
<para>This is usually equal to the normal Gregorian year (as returned by
<function>g_date_time_get_year()</function>), except as detailed below:
</para>
<para>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.
</para>
<para>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).
</para>
<para>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).
</para>
<para>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).
</para>
<para>Note that January 1 0001 in the proleptic Gregorian calendar is a
Monday, so this function never returns 0.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-week-of-year</title><informalexample><programlisting>(define-values (%return) (date-time:get-week-of-year self))
</programlisting></informalexample><para>Returns the ISO 8601 week number for the week containing <parameter>datetime</parameter>.
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).
</para>
<para>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.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-year</title><informalexample><programlisting>(define-values (%return) (date-time:get-year self))
</programlisting></informalexample><para>Retrieves the year represented by <parameter>datetime</parameter> in the Gregorian calendar.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>A <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-ymd</title><informalexample><programlisting>(define-values (year month day) (date-time:get-ymd self))
</programlisting></informalexample><para>Retrieves the Gregorian day, month, and year of a given <type>GDateTime</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type>.</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para>the return location for the gregorian year, or <constant>NULL</constant>.</para><para>Passed as <code>year</code></para></td></tr><tr><td class="parameter_name"><para>month</para></td><td class="parameter_description"><para>the return location for the month of the year, or <constant>NULL</constant>.</para><para>Passed as <code>month</code></para></td></tr><tr><td class="parameter_name"><para>day</para></td><td class="parameter_description"><para>the return location for the day of the month, or <constant>NULL</constant>.</para><para>Passed as <code>day</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-daylight-savings?</title><informalexample><programlisting>(define-values (%return) (date-time:is-daylight-savings? self))
</programlisting></informalexample><para>Determines if daylight savings time is in effect at the time and in
the time zone of <parameter>datetime</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref</title><informalexample><programlisting>(define-values (%return) (date-time:ref self))
</programlisting></informalexample><para>Atomically increments the reference count of <parameter>datetime</parameter> by one.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>to-local</title><informalexample><programlisting>(define-values (%return) (date-time:to-local self))
</programlisting></informalexample><para>Creates a new <type>GDateTime</type> corresponding to the same instant in time as
<parameter>datetime</parameter>, but in the local time zone.
</para>
<para>This call is equivalent to calling <function>g_date_time_to_timezone()</function> with the
time zone returned by <function>g_time_zone_new_local()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>to-timezone</title><informalexample><programlisting>(define-values (%return) (date-time:to-timezone self tz))
</programlisting></informalexample><para>Create a new <type>GDateTime</type> corresponding to the same instant in time as
<parameter>datetime</parameter>, but in the time zone <parameter>tz</parameter>.
</para>
<para>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).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>tz</para></td><td class="parameter_description"><para>the new <type>GTimeZone</type></para><para>Passed as <code>tz</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>to-unix</title><informalexample><programlisting>(define-values (%return) (date-time:to-unix self))
</programlisting></informalexample><para>Gives the Unix time corresponding to <parameter>datetime</parameter>, rounding down to the
nearest second.
</para>
<para>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 <parameter>datetime</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>to-utc</title><informalexample><programlisting>(define-values (%return) (date-time:to-utc self))
</programlisting></informalexample><para>Creates a new <type>GDateTime</type> corresponding to the same instant in time as
<parameter>datetime</parameter>, but in UTC.
</para>
<para>This call is equivalent to calling <function>g_date_time_to_timezone()</function> with the
time zone returned by <function>g_time_zone_new_utc()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (date-time:unref self))
</programlisting></informalexample><para>Atomically decrements the reference count of <parameter>datetime</parameter> by one.
</para>
<para>When the reference count reaches zero, the resources allocated by
<parameter>datetime</parameter> are freed</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-time:new-utc</title><informalexample><programlisting>(define-values
  (%return)
  (date-time:new-utc year month day hour minute seconds))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para></para><para>Passed as <code>year</code></para></td></tr><tr><td class="parameter_name"><para>month</para></td><td class="parameter_description"><para></para><para>Passed as <code>month</code></para></td></tr><tr><td class="parameter_name"><para>day</para></td><td class="parameter_description"><para></para><para>Passed as <code>day</code></para></td></tr><tr><td class="parameter_name"><para>hour</para></td><td class="parameter_description"><para></para><para>Passed as <code>hour</code></para></td></tr><tr><td class="parameter_name"><para>minute</para></td><td class="parameter_description"><para></para><para>Passed as <code>minute</code></para></td></tr><tr><td class="parameter_name"><para>seconds</para></td><td class="parameter_description"><para></para><para>Passed as <code>seconds</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-time:new-now-utc</title><informalexample><programlisting>(define-values (%return) (date-time:new-now-utc))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>date-time:new-now-local</title><informalexample><programlisting>(define-values (%return) (date-time:new-now-local))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>date-time:new-now</title><informalexample><programlisting>(define-values (%return) (date-time:new-now tz))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tz</para></td><td class="parameter_description"><para></para><para>Passed as <code>tz</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-time:new-local</title><informalexample><programlisting>(define-values
  (%return)
  (date-time:new-local year month day hour minute seconds))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para></para><para>Passed as <code>year</code></para></td></tr><tr><td class="parameter_name"><para>month</para></td><td class="parameter_description"><para></para><para>Passed as <code>month</code></para></td></tr><tr><td class="parameter_name"><para>day</para></td><td class="parameter_description"><para></para><para>Passed as <code>day</code></para></td></tr><tr><td class="parameter_name"><para>hour</para></td><td class="parameter_description"><para></para><para>Passed as <code>hour</code></para></td></tr><tr><td class="parameter_name"><para>minute</para></td><td class="parameter_description"><para></para><para>Passed as <code>minute</code></para></td></tr><tr><td class="parameter_name"><para>seconds</para></td><td class="parameter_description"><para></para><para>Passed as <code>seconds</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-time:new-from-unix-utc</title><informalexample><programlisting>(define-values (%return) (date-time:new-from-unix-utc t))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>t</para></td><td class="parameter_description"><para></para><para>Passed as <code>t</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-time:new-from-unix-local</title><informalexample><programlisting>(define-values (%return) (date-time:new-from-unix-local t))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>t</para></td><td class="parameter_description"><para></para><para>Passed as <code>t</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-time:new-from-iso8601</title><informalexample><programlisting>(define-values (%return) (date-time:new-from-iso8601 text default-tz))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>text</para></td><td class="parameter_description"><para></para><para>Passed as <code>text</code></para></td></tr><tr><td class="parameter_name"><para>default_tz</para></td><td class="parameter_description"><para></para><para>Passed as <code>default-tz</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-time:new</title><informalexample><programlisting>(define-values
  (%return)
  (date-time:new tz year month day hour minute seconds))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tz</para></td><td class="parameter_description"><para></para><para>Passed as <code>tz</code></para></td></tr><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para></para><para>Passed as <code>year</code></para></td></tr><tr><td class="parameter_name"><para>month</para></td><td class="parameter_description"><para></para><para>Passed as <code>month</code></para></td></tr><tr><td class="parameter_name"><para>day</para></td><td class="parameter_description"><para></para><para>Passed as <code>day</code></para></td></tr><tr><td class="parameter_name"><para>hour</para></td><td class="parameter_description"><para></para><para>Passed as <code>hour</code></para></td></tr><tr><td class="parameter_name"><para>minute</para></td><td class="parameter_description"><para></para><para>Passed as <code>minute</code></para></td></tr><tr><td class="parameter_name"><para>seconds</para></td><td class="parameter_description"><para></para><para>Passed as <code>seconds</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-time:compare</title><informalexample><programlisting>(define-values (%return) (date-time:compare dt1 dt2))
</programlisting></informalexample><para>A comparison function for <type>GDateTimes</type> that is suitable
as a <type>GCompareFunc</type>. Both <type>GDateTimes</type> must be non-<constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dt1</para></td><td class="parameter_description"><para>first <type>GDateTime</type> to compare</para><para>Passed as <code>dt1</code></para></td></tr><tr><td class="parameter_name"><para>dt2</para></td><td class="parameter_description"><para>second <type>GDateTime</type> to compare</para><para>Passed as <code>dt2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-time:equal?</title><informalexample><programlisting>(define-values (%return) (date-time:equal? dt1 dt2))
</programlisting></informalexample><para>Checks to see if <parameter>dt1</parameter> and <parameter>dt2</parameter> are equal.
</para>
<para>Equal here means that they represent the same moment after converting
them to the same time zone.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dt1</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>dt1</code></para></td></tr><tr><td class="parameter_name"><para>dt2</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>dt2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-time:hash</title><informalexample><programlisting>(define-values (%return) (date-time:hash datetime))
</programlisting></informalexample><para>Hashes <parameter>datetime</parameter> into a <type>guint</type>, suitable for use within <type>GHashTable</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>datetime</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibDateWeekday&gt;</refname></refnamediv><refsect1><title>Description</title><para>Enumeration representing a day of the week; <type>G_DATE_MONDAY</type>,
<type>G_DATE_TUESDAY</type>, etc. <type>G_DATE_BAD_WEEKDAY</type> is an invalid weekday.</para></refsect1><refsect1><title>Members</title><refsect2><title>bad-weekday</title><remark>alias <code>G_DATE_BAD_WEEKDAY</code></remark><para>invalid value</para></refsect2><refsect2><title>monday</title><remark>alias <code>G_DATE_MONDAY</code></remark><para>Monday</para></refsect2><refsect2><title>tuesday</title><remark>alias <code>G_DATE_TUESDAY</code></remark><para>Tuesday</para></refsect2><refsect2><title>wednesday</title><remark>alias <code>G_DATE_WEDNESDAY</code></remark><para>Wednesday</para></refsect2><refsect2><title>thursday</title><remark>alias <code>G_DATE_THURSDAY</code></remark><para>Thursday</para></refsect2><refsect2><title>friday</title><remark>alias <code>G_DATE_FRIDAY</code></remark><para>Friday</para></refsect2><refsect2><title>saturday</title><remark>alias <code>G_DATE_SATURDAY</code></remark><para>Saturday</para></refsect2><refsect2><title>sunday</title><remark>alias <code>G_DATE_SUNDAY</code></remark><para>Sunday</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GError&gt;</refname></refnamediv><refsect1><title>Description</title><para>The <code>GError</code> structure contains information about
an error that has occurred.</para></refsect1><refsect1><title>Functions</title><refsect2><title>copy</title><informalexample><programlisting>(define-values (%return) (error:copy self))
</programlisting></informalexample><para>Makes a copy of <parameter>error</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>error</para></td><td class="parameter_description"><para>a <type>GError</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>free</title><informalexample><programlisting>(define-values () (error:free self))
</programlisting></informalexample><para>Frees a <type>GError</type> and associated resources.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>error</para></td><td class="parameter_description"><para>a <type>GError</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>matches?</title><informalexample><programlisting>(define-values (%return) (error:matches? self domain code))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if <parameter>error</parameter> matches <parameter>domain</parameter> and <parameter>code</parameter>, <constant>FALSE</constant>
otherwise. In particular, when <parameter>error</parameter> is <constant>NULL</constant>, <constant>FALSE</constant> will
be returned.
</para>
<para>If <parameter>domain</parameter> contains a <code>FAILED</code> (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 <code>FAILED</code> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>error</para></td><td class="parameter_description"><para>a <type>GError</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>domain</para></td><td class="parameter_description"><para>an error domain</para><para>Passed as <code>domain</code></para></td></tr><tr><td class="parameter_name"><para>code</para></td><td class="parameter_description"><para>an error code</para><para>Passed as <code>code</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>error:new-literal</title><informalexample><programlisting>(define-values (%return) (error:new-literal domain code message))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>domain</para></td><td class="parameter_description"><para></para><para>Passed as <code>domain</code></para></td></tr><tr><td class="parameter_name"><para>code</para></td><td class="parameter_description"><para></para><para>Passed as <code>code</code></para></td></tr><tr><td class="parameter_name"><para>message</para></td><td class="parameter_description"><para></para><para>Passed as <code>message</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibErrorType&gt;</refname></refnamediv><refsect1><title>Description</title><para>The possible errors, used in the <parameter>v_error</parameter> field
of <type>GTokenValue</type>, when the token is a <constant>G_TOKEN_ERROR</constant>.</para></refsect1><refsect1><title>Members</title><refsect2><title>unknown</title><remark>alias <code>G_ERR_UNKNOWN</code></remark><para>unknown error</para></refsect2><refsect2><title>unexp-eof</title><remark>alias <code>G_ERR_UNEXP_EOF</code></remark><para>unexpected end of file</para></refsect2><refsect2><title>unexp-eof-in-string</title><remark>alias <code>G_ERR_UNEXP_EOF_IN_STRING</code></remark><para>unterminated string constant</para></refsect2><refsect2><title>unexp-eof-in-comment</title><remark>alias <code>G_ERR_UNEXP_EOF_IN_COMMENT</code></remark><para>unterminated comment</para></refsect2><refsect2><title>non-digit-in-const</title><remark>alias <code>G_ERR_NON_DIGIT_IN_CONST</code></remark><para>non-digit character in a number</para></refsect2><refsect2><title>digit-radix</title><remark>alias <code>G_ERR_DIGIT_RADIX</code></remark><para>digit beyond radix in a number</para></refsect2><refsect2><title>float-radix</title><remark>alias <code>G_ERR_FLOAT_RADIX</code></remark><para>non-decimal floating point number</para></refsect2><refsect2><title>float-malformed</title><remark>alias <code>G_ERR_FLOAT_MALFORMED</code></remark><para>malformed floating point number</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibFileError&gt;</refname></refnamediv><refsect1><title>Description</title><para>Values corresponding to <parameter>errno</parameter> codes returned from file operations
on UNIX. Unlike <parameter>errno</parameter> 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.
</para>
<para>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.</para></refsect1><refsect1><title>Members</title><refsect2><title>exist</title><remark>alias <code>G_FILE_ERROR_EXIST</code></remark><para>Operation not permitted; only the owner of
    the file (or other resource) or processes with special privileges
    can perform the operation.</para></refsect2><refsect2><title>isdir</title><remark>alias <code>G_FILE_ERROR_ISDIR</code></remark><para>File is a directory; you cannot open a directory
    for writing, or create or remove hard links to it.</para></refsect2><refsect2><title>acces</title><remark>alias <code>G_FILE_ERROR_ACCES</code></remark><para>Permission denied; the file permissions do not
    allow the attempted operation.</para></refsect2><refsect2><title>nametoolong</title><remark>alias <code>G_FILE_ERROR_NAMETOOLONG</code></remark><para>Filename too long.</para></refsect2><refsect2><title>noent</title><remark>alias <code>G_FILE_ERROR_NOENT</code></remark><para>No such file or directory. This is a &quot;file
    doesn't exist&quot; error for ordinary files that are referenced in
    contexts where they are expected to already exist.</para></refsect2><refsect2><title>notdir</title><remark>alias <code>G_FILE_ERROR_NOTDIR</code></remark><para>A file that isn't a directory was specified when
    a directory is required.</para></refsect2><refsect2><title>nxio</title><remark>alias <code>G_FILE_ERROR_NXIO</code></remark><para>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.</para></refsect2><refsect2><title>nodev</title><remark>alias <code>G_FILE_ERROR_NODEV</code></remark><para>The underlying file system of the specified file
    does not support memory mapping.</para></refsect2><refsect2><title>rofs</title><remark>alias <code>G_FILE_ERROR_ROFS</code></remark><para>The directory containing the new link can't be
    modified because it's on a read-only file system.</para></refsect2><refsect2><title>txtbsy</title><remark>alias <code>G_FILE_ERROR_TXTBSY</code></remark><para>Text file busy.</para></refsect2><refsect2><title>fault</title><remark>alias <code>G_FILE_ERROR_FAULT</code></remark><para>You passed in a pointer to bad memory.
    (GLib won't reliably return this, don't pass in pointers to bad
    memory.)</para></refsect2><refsect2><title>loop</title><remark>alias <code>G_FILE_ERROR_LOOP</code></remark><para>Too many levels of symbolic links were encountered
    in looking up a file name. This often indicates a cycle of symbolic
    links.</para></refsect2><refsect2><title>nospc</title><remark>alias <code>G_FILE_ERROR_NOSPC</code></remark><para>No space left on device; write operation on a
    file failed because the disk is full.</para></refsect2><refsect2><title>nomem</title><remark>alias <code>G_FILE_ERROR_NOMEM</code></remark><para>No memory available. The system cannot allocate
    more virtual memory because its capacity is full.</para></refsect2><refsect2><title>mfile</title><remark>alias <code>G_FILE_ERROR_MFILE</code></remark><para>The current process has too many files open and
    can't open any more. Duplicate descriptors do count toward this
    limit.</para></refsect2><refsect2><title>nfile</title><remark>alias <code>G_FILE_ERROR_NFILE</code></remark><para>There are too many distinct file openings in the
    entire system.</para></refsect2><refsect2><title>badf</title><remark>alias <code>G_FILE_ERROR_BADF</code></remark><para>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).</para></refsect2><refsect2><title>inval</title><remark>alias <code>G_FILE_ERROR_INVAL</code></remark><para>Invalid argument. This is used to indicate
    various kinds of problems with passing the wrong argument to a
    library function.</para></refsect2><refsect2><title>pipe</title><remark>alias <code>G_FILE_ERROR_PIPE</code></remark><para>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'.</para></refsect2><refsect2><title>again</title><remark>alias <code>G_FILE_ERROR_AGAIN</code></remark><para>Resource temporarily unavailable; the call might
    work if you try again later.</para></refsect2><refsect2><title>intr</title><remark>alias <code>G_FILE_ERROR_INTR</code></remark><para>Interrupted function call; an asynchronous signal
    occurred and prevented completion of the call. When this
    happens, you should try the call again.</para></refsect2><refsect2><title>io</title><remark>alias <code>G_FILE_ERROR_IO</code></remark><para>Input/output error; usually used for physical read
   or write errors. i.e. the disk or other physical device hardware
   is returning errors.</para></refsect2><refsect2><title>perm</title><remark>alias <code>G_FILE_ERROR_PERM</code></remark><para>Operation not permitted; only the owner of the
   file (or other resource) or processes with special privileges can
   perform the operation.</para></refsect2><refsect2><title>nosys</title><remark>alias <code>G_FILE_ERROR_NOSYS</code></remark><para>Function not implemented; this indicates that
   the system is missing some functionality.</para></refsect2><refsect2><title>failed</title><remark>alias <code>G_FILE_ERROR_FAILED</code></remark><para>Does not correspond to a UNIX error code; this
   is the standard &quot;failed for unspecified reason&quot; error code present
   in all <type>GError</type> error code enumerations. Returned if no specific
   code applies.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibFileSetContentsFlags&gt;</refname></refnamediv><refsect1><title>Description</title><para>Flags to pass to <function>g_file_set_contents_full()</function> to affect its safety and
performance.</para></refsect1><refsect1><title>Members</title><refsect2><title>none</title><remark>alias <code>G_FILE_SET_CONTENTS_NONE</code></remark><para>No guarantees about file consistency or durability.
  The most dangerous setting, which is slightly faster than other settings.</para></refsect2><refsect2><title>consistent</title><remark>alias <code>G_FILE_SET_CONTENTS_CONSISTENT</code></remark><para>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 <code>fsync()</code>
  on the file and use of an atomic <code>rename()</code> of the new version of the file
  over the old.</para></refsect2><refsect2><title>durable</title><remark>alias <code>G_FILE_SET_CONTENTS_DURABLE</code></remark><para>Guarantee file durability: after a crash, the
  new version of the file will be available. On Unix systems this equates to
  an <code>fsync()</code> on the file (if <constant>G_FILE_SET_CONTENTS_CONSISTENT</constant> is unset), or
  the effects of <constant>G_FILE_SET_CONTENTS_CONSISTENT</constant> plus an <code>fsync()</code> on the
  directory containing the file after calling <code>rename()</code>.</para></refsect2><refsect2><title>only-existing</title><remark>alias <code>G_FILE_SET_CONTENTS_ONLY_EXISTING</code></remark><para>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.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibFileTest&gt;</refname></refnamediv><refsect1><title>Description</title><para>A test to perform on a file using <function>g_file_test()</function>.</para></refsect1><refsect1><title>Members</title><refsect2><title>is-regular</title><remark>alias <code>G_FILE_TEST_IS_REGULAR</code></remark><para><constant>TRUE</constant> if the file is a regular file
    (not a directory). Note that this test will also return <constant>TRUE</constant>
    if the tested file is a symlink to a regular file.</para></refsect2><refsect2><title>is-symlink</title><remark>alias <code>G_FILE_TEST_IS_SYMLINK</code></remark><para><constant>TRUE</constant> if the file is a symlink.</para></refsect2><refsect2><title>is-dir</title><remark>alias <code>G_FILE_TEST_IS_DIR</code></remark><para><constant>TRUE</constant> if the file is a directory.</para></refsect2><refsect2><title>is-executable</title><remark>alias <code>G_FILE_TEST_IS_EXECUTABLE</code></remark><para><constant>TRUE</constant> if the file is executable.</para></refsect2><refsect2><title>exists</title><remark>alias <code>G_FILE_TEST_EXISTS</code></remark><para><constant>TRUE</constant> if the file exists. It may or may not
    be a regular file.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibFormatSizeFlags&gt;</refname></refnamediv><refsect1><title>Description</title><para>Flags to modify the format of the string returned by <function>g_format_size_full()</function>.</para></refsect1><refsect1><title>Members</title><refsect2><title>default</title><remark>alias <code>G_FORMAT_SIZE_DEFAULT</code></remark><para>behave the same as <function>g_format_size()</function></para></refsect2><refsect2><title>long-format</title><remark>alias <code>G_FORMAT_SIZE_LONG_FORMAT</code></remark><para>include the exact number of bytes as part
    of the returned string.  For example, &quot;45.6 kB (45,612 bytes)&quot;.</para></refsect2><refsect2><title>iec-units</title><remark>alias <code>G_FORMAT_SIZE_IEC_UNITS</code></remark><para>use IEC (base 1024) units with &quot;KiB&quot;-style
    suffixes. IEC units should only be used for reporting things with
    a strong &quot;power of 2&quot; basis, like RAM sizes or RAID stripe sizes.
    Network and storage sizes should be reported in the normal SI units.</para></refsect2><refsect2><title>bits</title><remark>alias <code>G_FORMAT_SIZE_BITS</code></remark><para>set the size as a quantity in bits, rather than
    bytes, and return units in bits. For example, ‘Mb’ rather than ‘MB’.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GHashTable&gt;</refname></refnamediv><refsect1><title>Description</title><para>The <type>GHashTable</type> struct is an opaque data structure to represent a
[Hash Table][glib-Hash-Tables]. It should only be accessed via the
following functions.</para></refsect1><refsect1><title>Functions</title><refsect2><title>hash-table:add?</title><informalexample><programlisting>(define-values (%return) (hash-table:add? hash-table key))
</programlisting></informalexample><para>This is a convenience function for using a <type>GHashTable</type> as a set.  It
is equivalent to calling <function>g_hash_table_replace()</function> with <parameter>key</parameter> as both the
key and the value.
</para>
<para>In particular, this means that if <parameter>key</parameter> already exists in the hash table, then
the old copy of <parameter>key</parameter> in the hash table is freed and <parameter>key</parameter> replaces it in the
table.
</para>
<para>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.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key to insert</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table:contains?</title><informalexample><programlisting>(define-values (%return) (hash-table:contains? hash-table key))
</programlisting></informalexample><para>Checks if <parameter>key</parameter> is in <parameter>hash_table</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key to check</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table:destroy</title><informalexample><programlisting>(define-values () (hash-table:destroy hash-table))
</programlisting></informalexample><para>Destroys all keys and values in the <type>GHashTable</type> and decrements its
reference count by 1. If keys and/or values are dynamically allocated,
you should either free them first or create the <type>GHashTable</type> with destroy
notifiers using <function>g_hash_table_new_full()</function>. In the latter case the destroy
functions you supplied will be called on all keys and values during the
destruction phase.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table:insert?</title><informalexample><programlisting>(define-values (%return) (hash-table:insert? hash-table key value))
</programlisting></informalexample><para>Inserts a new key and value into a <type>GHashTable</type>.
</para>
<para>If the key already exists in the <type>GHashTable</type> its current
value is replaced with the new value. If you supplied a
<parameter>value_destroy_func</parameter> when creating the <type>GHashTable</type>, the old
value is freed using that function. If you supplied a
<parameter>key_destroy_func</parameter> when creating the <type>GHashTable</type>, the passed
key is freed using that function.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key to insert</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>the value to associate with the key</para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table:lookup</title><informalexample><programlisting>(define-values (%return) (hash-table:lookup hash-table key))
</programlisting></informalexample><para>Looks up a key in a <type>GHashTable</type>. Note that this function cannot
distinguish between a key that is not present and one which is present
and has the value <constant>NULL</constant>. If you need this distinction, use
<function>g_hash_table_lookup_extended()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to look up</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table:lookup-extended</title><informalexample><programlisting>(define-values
  (%return orig-key value)
  (hash-table:lookup-extended hash-table lookup-key))
</programlisting></informalexample><para>Looks up a key in the <type>GHashTable</type>, returning the original key and the
associated value and a <type>gboolean</type> which is <constant>TRUE</constant> if the key was found. This
is useful if you need to free the memory allocated for the original key,
for example before calling <function>g_hash_table_remove()</function>.
</para>
<para>You can actually pass <constant>NULL</constant> for <parameter>lookup_key</parameter> to test
whether the <constant>NULL</constant> key exists, provided the hash and equal functions
of <parameter>hash_table</parameter> are <constant>NULL</constant>-safe.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>lookup_key</para></td><td class="parameter_description"><para>the key to look up</para><para>Passed as <code>lookup-key</code></para></td></tr><tr><td class="parameter_name"><para>orig_key</para></td><td class="parameter_description"><para>return location for the original key</para><para>Passed as <code>orig-key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>return location for the value associated
with the key</para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table:remove?</title><informalexample><programlisting>(define-values (%return) (hash-table:remove? hash-table key))
</programlisting></informalexample><para>Removes a key and its associated value from a <type>GHashTable</type>.
</para>
<para>If the <type>GHashTable</type> was created using <function>g_hash_table_new_full()</function>, 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to remove</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table:remove-all</title><informalexample><programlisting>(define-values () (hash-table:remove-all hash-table))
</programlisting></informalexample><para>Removes all keys and their associated values from a <type>GHashTable</type>.
</para>
<para>If the <type>GHashTable</type> was created using <function>g_hash_table_new_full()</function>,
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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table:replace?</title><informalexample><programlisting>(define-values (%return) (hash-table:replace? hash-table key value))
</programlisting></informalexample><para>Inserts a new key and value into a <type>GHashTable</type> similar to
<function>g_hash_table_insert()</function>. The difference is that if the key
already exists in the <type>GHashTable</type>, it gets replaced by the
new key. If you supplied a <parameter>value_destroy_func</parameter> when creating
the <type>GHashTable</type>, the old value is freed using that function.
If you supplied a <parameter>key_destroy_func</parameter> when creating the
<type>GHashTable</type>, the old key is freed using that function.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key to insert</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>the value to associate with the key</para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table:size</title><informalexample><programlisting>(define-values (%return) (hash-table:size hash-table))
</programlisting></informalexample><para>Returns the number of elements contained in the <type>GHashTable</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table:steal?</title><informalexample><programlisting>(define-values (%return) (hash-table:steal? hash-table key))
</programlisting></informalexample><para>Removes a key and its associated value from a <type>GHashTable</type> without
calling the key and value destroy functions.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to remove</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table:steal-all</title><informalexample><programlisting>(define-values () (hash-table:steal-all hash-table))
</programlisting></informalexample><para>Removes all keys and their associated values from a <type>GHashTable</type>
without calling the key and value destroy functions.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table:steal-extended</title><informalexample><programlisting>(define-values
  (%return stolen-key stolen-value)
  (hash-table:steal-extended hash-table lookup-key))
</programlisting></informalexample><para>Looks up a key in the <type>GHashTable</type>, stealing the original key and the
associated value and returning <constant>TRUE</constant> if the key was found. If the key was
not found, <constant>FALSE</constant> is returned.
</para>
<para>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 <function>g_hash_table_steal()</function>.
</para>
<para>You can pass <constant>NULL</constant> for <parameter>lookup_key</parameter>, provided the hash and equal functions
of <parameter>hash_table</parameter> are <constant>NULL</constant>-safe.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>lookup_key</para></td><td class="parameter_description"><para>the key to look up</para><para>Passed as <code>lookup-key</code></para></td></tr><tr><td class="parameter_name"><para>stolen_key</para></td><td class="parameter_description"><para>return location for the
   original key</para><para>Passed as <code>stolen-key</code></para></td></tr><tr><td class="parameter_name"><para>stolen_value</para></td><td class="parameter_description"><para>return location
   for the value associated with the key</para><para>Passed as <code>stolen-value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table:unref</title><informalexample><programlisting>(define-values () (hash-table:unref hash-table))
</programlisting></informalexample><para>Atomically decrements the reference count of <parameter>hash_table</parameter> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a valid <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibHookFlagMask&gt;</refname></refnamediv><refsect1><title>Description</title><para>Flags used internally in the <type>GHook</type> implementation.</para></refsect1><refsect1><title>Members</title><refsect2><title>active</title><remark>alias <code>G_HOOK_FLAG_ACTIVE</code></remark><para>set if the hook has not been destroyed</para></refsect2><refsect2><title>in-call</title><remark>alias <code>G_HOOK_FLAG_IN_CALL</code></remark><para>set if the hook is currently being run</para></refsect2><refsect2><title>mask</title><remark>alias <code>G_HOOK_FLAG_MASK</code></remark><para>A mask covering all bits reserved for
  hook flags; see <constant>G_HOOK_FLAG_USER_SHIFT</constant></para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GIOChannel&gt;</refname></refnamediv><refsect1><title>Description</title><para>A data structure representing an IO Channel. The fields should be
considered private and should only be accessed with the following
functions.</para></refsect1><refsect1><title>Functions</title><refsect2><title>close</title><informalexample><programlisting>(define-values () (iochannel:close self))
</programlisting></informalexample><para>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 <function>g_io_channel_unref()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>A <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>flush</title><informalexample><programlisting>(define-values (%return) (iochannel:flush self))
</programlisting></informalexample><para>Flushes the write buffer for the GIOChannel.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-buffer-condition</title><informalexample><programlisting>(define-values (%return) (iochannel:get-buffer-condition self))
</programlisting></informalexample><para>This function returns a <type>GIOCondition</type> depending on whether there
is data to be read/space to write data in the internal buffers in
the <type>GIOChannel</type>. Only the flags <constant>G_IO_IN</constant> and <constant>G_IO_OUT</constant> may be set.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>A <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-buffer-size</title><informalexample><programlisting>(define-values (%return) (iochannel:get-buffer-size self))
</programlisting></informalexample><para>Gets the buffer size.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-buffered?</title><informalexample><programlisting>(define-values (%return) (iochannel:get-buffered? self))
</programlisting></informalexample><para>Returns whether <parameter>channel</parameter> is buffered.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-close-on-unref?</title><informalexample><programlisting>(define-values (%return) (iochannel:get-close-on-unref? self))
</programlisting></informalexample><para>Returns whether the file/socket/whatever associated with <parameter>channel</parameter>
will be closed when <parameter>channel</parameter> receives its final unref and is
destroyed. The default value of this is <constant>TRUE</constant> for channels created
by g_io_channel_new_file (), and <constant>FALSE</constant> for all other channels.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type>.</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-encoding</title><informalexample><programlisting>(define-values (%return) (iochannel:get-encoding self))
</programlisting></informalexample><para>Gets the encoding for the input/output of the channel.
The internal encoding is always UTF-8. The encoding <constant>NULL</constant>
makes the channel safe for binary data.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-flags</title><informalexample><programlisting>(define-values (%return) (iochannel:get-flags self))
</programlisting></informalexample><para>Gets the current flags for a <type>GIOChannel</type>, including read-only
flags such as <constant>G_IO_FLAG_IS_READABLE</constant>.
</para>
<para>The values of the flags <constant>G_IO_FLAG_IS_READABLE</constant> and <constant>G_IO_FLAG_IS_WRITABLE</constant>
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 <function>shutdown()</function> function), the user
should immediately call <function>g_io_channel_get_flags()</function> to update
the internal values of these flags.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-line-term</title><informalexample><programlisting>(define-values (%return) (iochannel:get-line-term self length))
</programlisting></informalexample><para>This returns the string that <type>GIOChannel</type> uses to determine
where in the file a line break occurs. A value of <constant>NULL</constant>
indicates autodetection.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>a location to return the length of the line terminator</para><para>Passed as <code>length</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>init</title><informalexample><programlisting>(define-values () (iochannel:init self))
</programlisting></informalexample><para>Initializes a <type>GIOChannel</type> struct.
</para>
<para>This is called by each of the above functions when creating a
<type>GIOChannel</type>, and so is not often needed by the application
programmer (unless you are creating a new type of <type>GIOChannel</type>).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>read</title><informalexample><programlisting>(define-values (%return) (iochannel:read self buf count bytes-read))
</programlisting></informalexample><para>Reads data from a <type>GIOChannel</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>buf</para></td><td class="parameter_description"><para>a buffer to read the data into (which should be at least
      count bytes long)</para><para>Passed as <code>buf</code></para></td></tr><tr><td class="parameter_name"><para>count</para></td><td class="parameter_description"><para>the number of bytes to read from the <type>GIOChannel</type></para><para>Passed as <code>count</code></para></td></tr><tr><td class="parameter_name"><para>bytes_read</para></td><td class="parameter_description"><para>returns the number of bytes actually read</para><para>Passed as <code>bytes-read</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>read-chars!</title><informalexample><programlisting>(define-values (%return buf bytes-read) (iochannel:read-chars! self buf))
</programlisting></informalexample><para>Replacement for <function>g_io_channel_read()</function> with the new API.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>buf</para></td><td class="parameter_description"><para>
    <para>a buffer to read data into</para></para><para>Passed as <code>buf</code></para></td></tr><tr><td class="parameter_name"><para>count</para></td><td class="parameter_description"><para>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.</para><para>Inferred from <code>buf</code></para></td></tr><tr><td class="parameter_name"><para>bytes_read</para></td><td class="parameter_description"><para>The number of bytes read. This may be
    zero even on success if count &lt; 6 and the channel's encoding
    is non-<constant>NULL</constant>. This indicates that the next UTF-8 character is
    too wide for the buffer.</para><para>Passed as <code>bytes-read</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>read-line</title><informalexample><programlisting>(define-values
  (%return str-return length terminator-pos)
  (iochannel:read-line self))
</programlisting></informalexample><para>Reads a line, including the terminating character(s),
from a <type>GIOChannel</type> into a newly-allocated string.
<parameter>str_return</parameter> will contain allocated memory if the return
is <constant>G_IO_STATUS_NORMAL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>str_return</para></td><td class="parameter_description"><para>The line read from the <type>GIOChannel</type>, including the
             line terminator. This data should be freed with <function>g_free()</function>
             when no longer needed. This is a nul-terminated string.
             If a <parameter>length</parameter> of zero is returned, this will be <constant>NULL</constant> instead.</para><para>Passed as <code>str-return</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>location to store length of the read data, or <constant>NULL</constant></para><para>Passed as <code>length</code></para></td></tr><tr><td class="parameter_name"><para>terminator_pos</para></td><td class="parameter_description"><para>location to store position of line terminator, or <constant>NULL</constant></para><para>Passed as <code>terminator-pos</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>read-line-string</title><informalexample><programlisting>(define-values
  (%return)
  (iochannel:read-line-string self buffer terminator-pos))
</programlisting></informalexample><para>Reads a line from a <type>GIOChannel</type>, using a <type>GString</type> as a buffer.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>buffer</para></td><td class="parameter_description"><para>a <type>GString</type> into which the line will be written.
         If <parameter>buffer</parameter> already contains data, the old data will
         be overwritten.</para><para>Passed as <code>buffer</code></para></td></tr><tr><td class="parameter_name"><para>terminator_pos</para></td><td class="parameter_description"><para>location to store position of line terminator, or <constant>NULL</constant></para><para>Passed as <code>terminator-pos</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>read-to-end</title><informalexample><programlisting>(define-values (%return str-return length) (iochannel:read-to-end self))
</programlisting></informalexample><para>Reads all the remaining data from the file.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>str_return</para></td><td class="parameter_description"><para>Location to
             store a pointer to a string holding the remaining data in the
             <type>GIOChannel</type>. This data should be freed with <function>g_free()</function> when no
             longer needed. This data is terminated by an extra nul
             character, but there may be other nuls in the intervening data.</para><para>Passed as <code>str-return</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>location to store length of the data</para><para>Inferred from <code>str-return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>read-unichar</title><informalexample><programlisting>(define-values (%return thechar) (iochannel:read-unichar self))
</programlisting></informalexample><para>Reads a Unicode character from <parameter>channel</parameter>.
This function cannot be called on a channel with <constant>NULL</constant> encoding.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>thechar</para></td><td class="parameter_description"><para>a location to return a character</para><para>Passed as <code>thechar</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref</title><informalexample><programlisting>(define-values (%return) (iochannel:ref self))
</programlisting></informalexample><para>Increments the reference count of a <type>GIOChannel</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>seek</title><informalexample><programlisting>(define-values (%return) (iochannel:seek self offset type))
</programlisting></informalexample><para>Sets the current position in the <type>GIOChannel</type>, similar to the standard
library function <function>fseek()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>offset</para></td><td class="parameter_description"><para>an offset, in bytes, which is added to the position specified
         by <parameter>type</parameter></para><para>Passed as <code>offset</code></para></td></tr><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>the position in the file, which can be <constant>G_SEEK_CUR</constant> (the current
       position), <constant>G_SEEK_SET</constant> (the start of the file), or <constant>G_SEEK_END</constant>
       (the end of the file)</para><para>Passed as <code>type</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>seek-position</title><informalexample><programlisting>(define-values (%return) (iochannel:seek-position self offset type))
</programlisting></informalexample><para>Replacement for <function>g_io_channel_seek()</function> with the new API.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>offset</para></td><td class="parameter_description"><para>The offset in bytes from the position specified by <parameter>type</parameter></para><para>Passed as <code>offset</code></para></td></tr><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GSeekType</type>. The type <constant>G_SEEK_CUR</constant> 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.</para><para>Passed as <code>type</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-buffer-size</title><informalexample><programlisting>(define-values () (iochannel:set-buffer-size self size))
</programlisting></informalexample><para>Sets the buffer size.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>size</para></td><td class="parameter_description"><para>the size of the buffer, or 0 to let GLib pick a good size</para><para>Passed as <code>size</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-buffered</title><informalexample><programlisting>(define-values () (iochannel:set-buffered self buffered))
</programlisting></informalexample><para>The buffering state can only be set if the channel's encoding
is <constant>NULL</constant>. For any other encoding, the channel must be buffered.
</para>
<para>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 <constant>G_IO_STATUS_EOF</constant>
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 <constant>G_SEEK_CUR</constant>
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.
</para>
<para>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.
</para>
<para>The default state of the channel is buffered.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>buffered</para></td><td class="parameter_description"><para>whether to set the channel buffered or unbuffered</para><para>Passed as <code>buffered</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-close-on-unref</title><informalexample><programlisting>(define-values () (iochannel:set-close-on-unref self do-close))
</programlisting></informalexample><para>Whether to close the channel on the final unref of the <type>GIOChannel</type>
data structure. The default value of this is <constant>TRUE</constant> for channels
created by g_io_channel_new_file (), and <constant>FALSE</constant> for all other channels.
</para>
<para>Setting this flag to <constant>TRUE</constant> for a channel you have already closed
can cause problems when the final reference to the <type>GIOChannel</type> is dropped.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>do_close</para></td><td class="parameter_description"><para>Whether to close the channel on the final unref of
           the GIOChannel data structure.</para><para>Passed as <code>do-close</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-encoding</title><informalexample><programlisting>(define-values (%return) (iochannel:set-encoding self encoding))
</programlisting></informalexample><para>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.
</para>
<para>The encoding <constant>NULL</constant> is safe to use with binary data.
</para>
<para>The encoding can only be set if one of the following conditions
is true:
</para>
<para>- The channel was just created, and has not been written to or read from yet.
</para>
<para>- The channel is write-only.
</para>
<para>- The channel is a file, and the file pointer was just repositioned
  by a call to <function>g_io_channel_seek_position()</function>. (This flushes all the
  internal buffers.)
</para>
<para>- The current encoding is <constant>NULL</constant> or UTF-8.
</para>
<para>- One of the (new API) read functions has just returned <constant>G_IO_STATUS_EOF</constant>
  (or, in the case of <function>g_io_channel_read_to_end()</function>, <constant>G_IO_STATUS_NORMAL</constant>).
</para>
<para>-  One of the functions <function>g_io_channel_read_chars()</function> or
   <function>g_io_channel_read_unichar()</function> has returned <constant>G_IO_STATUS_AGAIN</constant> or
   <constant>G_IO_STATUS_ERROR</constant>. This may be useful in the case of
   <constant>G_CONVERT_ERROR_ILLEGAL_SEQUENCE</constant>.
   Returning one of these statuses from <function>g_io_channel_read_line()</function>,
   <function>g_io_channel_read_line_string()</function>, or <function>g_io_channel_read_to_end()</function>
   does not guarantee that the encoding can be changed.
</para>
<para>Channels which do not meet one of the above conditions cannot call
<function>g_io_channel_seek_position()</function> with an offset of <constant>G_SEEK_CUR</constant>, and, if
they are &quot;seekable&quot;, cannot call <function>g_io_channel_write_chars()</function> after
calling one of the API &quot;read&quot; functions.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>encoding</para></td><td class="parameter_description"><para>the encoding type</para><para>Passed as <code>encoding</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-flags</title><informalexample><programlisting>(define-values (%return) (iochannel:set-flags self flags))
</programlisting></informalexample><para>Sets the (writeable) flags in <parameter>channel</parameter> to (<parameter>flags</parameter> &amp; <constant>G_IO_FLAG_SET_MASK</constant>).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>the flags to set on the IO channel</para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-line-term</title><informalexample><programlisting>(define-values () (iochannel:set-line-term self line-term length))
</programlisting></informalexample><para>This sets the string that <type>GIOChannel</type> uses to determine
where in the file a line break occurs.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>line_term</para></td><td class="parameter_description"><para>The line termination string. Use <constant>NULL</constant> for
            autodetect.  Autodetection breaks on &quot;\n&quot;, &quot;\r\n&quot;, &quot;\r&quot;, &quot;\0&quot;,
            and the Unicode paragraph separator. Autodetection should not be
            used for anything other than file-based channels.</para><para>Passed as <code>line-term</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>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.</para><para>Passed as <code>length</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>shutdown</title><informalexample><programlisting>(define-values (%return) (iochannel:shutdown self flush))
</programlisting></informalexample><para>Close an IO channel. Any pending data to be written will be
flushed if <parameter>flush</parameter> is <constant>TRUE</constant>. The channel will not be freed until the
last reference is dropped using <function>g_io_channel_unref()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>flush</para></td><td class="parameter_description"><para>if <constant>TRUE</constant>, flush pending</para><para>Passed as <code>flush</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unix-get-fd</title><informalexample><programlisting>(define-values (%return) (iochannel:unix-get-fd self))
</programlisting></informalexample><para>Returns the file descriptor of the <type>GIOChannel</type>.
</para>
<para>On Windows this function returns the file descriptor or socket of
the <type>GIOChannel</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type>, created with <function>g_io_channel_unix_new()</function>.</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (iochannel:unref self))
</programlisting></informalexample><para>Decrements the reference count of a <type>GIOChannel</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>write</title><informalexample><programlisting>(define-values (%return) (iochannel:write self buf count bytes-written))
</programlisting></informalexample><para>Writes data to a <type>GIOChannel</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>buf</para></td><td class="parameter_description"><para>the buffer containing the data to write</para><para>Passed as <code>buf</code></para></td></tr><tr><td class="parameter_name"><para>count</para></td><td class="parameter_description"><para>the number of bytes to write</para><para>Passed as <code>count</code></para></td></tr><tr><td class="parameter_name"><para>bytes_written</para></td><td class="parameter_description"><para>the number of bytes actually written</para><para>Passed as <code>bytes-written</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>write-chars</title><informalexample><programlisting>(define-values (%return bytes-written) (iochannel:write-chars self buf count))
</programlisting></informalexample><para>Replacement for <function>g_io_channel_write()</function> with the new API.
</para>
<para>On seekable channels with encodings other than <constant>NULL</constant> 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 ().</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>buf</para></td><td class="parameter_description"><para>a buffer to write data from</para><para>Passed as <code>buf</code></para></td></tr><tr><td class="parameter_name"><para>count</para></td><td class="parameter_description"><para>the size of the buffer. If -1, the buffer
        is taken to be a nul-terminated string.</para><para>Passed as <code>count</code></para></td></tr><tr><td class="parameter_name"><para>bytes_written</para></td><td class="parameter_description"><para>The number of bytes written. This can be nonzero
                even if the return value is not <constant>G_IO_STATUS_NORMAL</constant>.
                If the return value is <constant>G_IO_STATUS_NORMAL</constant> and the
                channel is blocking, this will always be equal
                to <parameter>count</parameter> if <parameter>count</parameter> &gt;= 0.</para><para>Passed as <code>bytes-written</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>write-unichar</title><informalexample><programlisting>(define-values (%return) (iochannel:write-unichar self thechar))
</programlisting></informalexample><para>Writes a Unicode character to <parameter>channel</parameter>.
This function cannot be called on a channel with <constant>NULL</constant> encoding.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>thechar</para></td><td class="parameter_description"><para>a character</para><para>Passed as <code>thechar</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>iochannel:unix-new</title><informalexample><programlisting>(define-values (%return) (iochannel:unix-new fd))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>fd</para></td><td class="parameter_description"><para></para><para>Passed as <code>fd</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>iochannel:new-file</title><informalexample><programlisting>(define-values (%return) (iochannel:new-file filename mode))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>filename</para></td><td class="parameter_description"><para></para><para>Passed as <code>filename</code></para></td></tr><tr><td class="parameter_name"><para>mode</para></td><td class="parameter_description"><para></para><para>Passed as <code>mode</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>iochannel:error-from-errno</title><informalexample><programlisting>(define-values (%return) (iochannel:error-from-errno en))
</programlisting></informalexample><para>Converts an <code>errno</code> error number to a <type>GIOChannelError</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>en</para></td><td class="parameter_description"><para>an <code>errno</code> error number, e.g. <code>EINVAL</code></para><para>Passed as <code>en</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>iochannel:error-quark</title><informalexample><programlisting>(define-values (%return) (iochannel:error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibIOChannelError&gt;</refname></refnamediv><refsect1><title>Description</title><para>Error codes returned by <type>GIOChannel</type> operations.</para></refsect1><refsect1><title>Members</title><refsect2><title>fbig</title><remark>alias <code>G_IO_CHANNEL_ERROR_FBIG</code></remark><para>File too large.</para></refsect2><refsect2><title>inval</title><remark>alias <code>G_IO_CHANNEL_ERROR_INVAL</code></remark><para>Invalid argument.</para></refsect2><refsect2><title>io</title><remark>alias <code>G_IO_CHANNEL_ERROR_IO</code></remark><para>IO error.</para></refsect2><refsect2><title>isdir</title><remark>alias <code>G_IO_CHANNEL_ERROR_ISDIR</code></remark><para>File is a directory.</para></refsect2><refsect2><title>nospc</title><remark>alias <code>G_IO_CHANNEL_ERROR_NOSPC</code></remark><para>No space left on device.</para></refsect2><refsect2><title>nxio</title><remark>alias <code>G_IO_CHANNEL_ERROR_NXIO</code></remark><para>No such device or address.</para></refsect2><refsect2><title>overflow</title><remark>alias <code>G_IO_CHANNEL_ERROR_OVERFLOW</code></remark><para>Value too large for defined datatype.</para></refsect2><refsect2><title>pipe</title><remark>alias <code>G_IO_CHANNEL_ERROR_PIPE</code></remark><para>Broken pipe.</para></refsect2><refsect2><title>failed</title><remark>alias <code>G_IO_CHANNEL_ERROR_FAILED</code></remark><para>Some other error.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GIOCondition&gt;</refname></refnamediv><refsect1><title>Description</title><para>A bitwise combination representing a condition to watch for on an
event source.</para></refsect1><refsect1><title>Members</title><refsect2><title>in</title><remark>alias <code>G_IO_IN</code></remark><para>There is data to read.</para></refsect2><refsect2><title>out</title><remark>alias <code>G_IO_OUT</code></remark><para>Data can be written (without blocking).</para></refsect2><refsect2><title>pri</title><remark>alias <code>G_IO_PRI</code></remark><para>There is urgent data to read.</para></refsect2><refsect2><title>err</title><remark>alias <code>G_IO_ERR</code></remark><para>Error condition.</para></refsect2><refsect2><title>hup</title><remark>alias <code>G_IO_HUP</code></remark><para>Hung up (the connection has been broken, usually for
           pipes and sockets).</para></refsect2><refsect2><title>nval</title><remark>alias <code>G_IO_NVAL</code></remark><para>Invalid request. The file descriptor is not open.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibIOError&gt;</refname></refnamediv><refsect1><title>Description</title><para><type>GIOError</type> is only used by the deprecated functions
<function>g_io_channel_read()</function>, <function>g_io_channel_write()</function>, and <function>g_io_channel_seek()</function>.</para></refsect1><refsect1><title>Members</title><refsect2><title>none</title><remark>alias <code>G_IO_ERROR_NONE</code></remark><para>no error</para></refsect2><refsect2><title>again</title><remark>alias <code>G_IO_ERROR_AGAIN</code></remark><para>an EAGAIN error occurred</para></refsect2><refsect2><title>inval</title><remark>alias <code>G_IO_ERROR_INVAL</code></remark><para>an EINVAL error occurred</para></refsect2><refsect2><title>unknown</title><remark>alias <code>G_IO_ERROR_UNKNOWN</code></remark><para>another error occurred</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibIOFlags&gt;</refname></refnamediv><refsect1><title>Description</title><para>Specifies properties of a <type>GIOChannel</type>. Some of the flags can only be
read with <function>g_io_channel_get_flags()</function>, but not changed with
<function>g_io_channel_set_flags()</function>.</para></refsect1><refsect1><title>Members</title><refsect2><title>append</title><remark>alias <code>G_IO_FLAG_APPEND</code></remark><para>turns on append mode, corresponds to <constant>O_APPEND</constant>
    (see the documentation of the UNIX <function>open()</function> syscall)</para></refsect2><refsect2><title>nonblock</title><remark>alias <code>G_IO_FLAG_NONBLOCK</code></remark><para>turns on nonblocking mode, corresponds to
    <constant>O_NONBLOCK</constant>/<constant>O_NDELAY</constant> (see the documentation of the UNIX <function>open()</function>
    syscall)</para></refsect2><refsect2><title>is-readable</title><remark>alias <code>G_IO_FLAG_IS_READABLE</code></remark><para>indicates that the io channel is readable.
    This flag cannot be changed.</para></refsect2><refsect2><title>is-writable</title><remark>alias <code>G_IO_FLAG_IS_WRITABLE</code></remark><para>indicates that the io channel is writable.
    This flag cannot be changed.</para></refsect2><refsect2><title>is-writeable</title><remark>alias <code>G_IO_FLAG_IS_WRITEABLE</code></remark><para>a misspelled version of <parameter>G_IO_FLAG_IS_WRITABLE</parameter>
    that existed before the spelling was fixed in GLib 2.30. It is kept
    here for compatibility reasons. Deprecated since 2.30</para></refsect2><refsect2><title>is-seekable</title><remark>alias <code>G_IO_FLAG_IS_SEEKABLE</code></remark><para>indicates that the io channel is seekable,
    i.e. that <function>g_io_channel_seek_position()</function> can be used on it.
    This flag cannot be changed.</para></refsect2><refsect2><title>mask</title><remark>alias <code>G_IO_FLAG_MASK</code></remark><para>the mask that specifies all the valid flags.</para></refsect2><refsect2><title>get-mask</title><remark>alias <code>G_IO_FLAG_GET_MASK</code></remark><para>the mask of the flags that are returned from
    <function>g_io_channel_get_flags()</function></para></refsect2><refsect2><title>set-mask</title><remark>alias <code>G_IO_FLAG_SET_MASK</code></remark><para>the mask of the flags that the user can modify
    with <function>g_io_channel_set_flags()</function></para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibIOStatus&gt;</refname></refnamediv><refsect1><title>Description</title><para>Statuses returned by most of the <type>GIOFuncs</type> functions.</para></refsect1><refsect1><title>Members</title><refsect2><title>error</title><remark>alias <code>G_IO_STATUS_ERROR</code></remark><para>An error occurred.</para></refsect2><refsect2><title>normal</title><remark>alias <code>G_IO_STATUS_NORMAL</code></remark><para>Success.</para></refsect2><refsect2><title>eof</title><remark>alias <code>G_IO_STATUS_EOF</code></remark><para>End of file.</para></refsect2><refsect2><title>again</title><remark>alias <code>G_IO_STATUS_AGAIN</code></remark><para>Resource temporarily unavailable.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GKeyFile&gt;</refname></refnamediv><refsect1><title>Description</title><para>The GKeyFile struct contains only private data
and should not be accessed directly.</para></refsect1><refsect1><title>Functions</title><refsect2><title>get-boolean?</title><informalexample><programlisting>(define-values (%return) (key-file:get-boolean? self group-name key))
</programlisting></informalexample><para>Returns the value associated with <parameter>key</parameter> under <parameter>group_name</parameter> as a
boolean.
</para>
<para>If <parameter>key</parameter> cannot be found then <constant>FALSE</constant> is returned and <parameter>error</parameter> is set
to <type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type>. Likewise, if the value
associated with <parameter>key</parameter> cannot be interpreted as a boolean then <constant>FALSE</constant>
is returned and <parameter>error</parameter> is set to <type>G_KEY_FILE_ERROR_INVALID_VALUE</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-boolean-list</title><informalexample><programlisting>(define-values
  (%return length)
  (key-file:get-boolean-list self group-name key))
</programlisting></informalexample><para>Returns the values associated with <parameter>key</parameter> under <parameter>group_name</parameter> as
booleans.
</para>
<para>If <parameter>key</parameter> cannot be found then <constant>NULL</constant> is returned and <parameter>error</parameter> is set to
<type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type>. Likewise, if the values associated
with <parameter>key</parameter> cannot be interpreted as booleans then <constant>NULL</constant> is returned
and <parameter>error</parameter> is set to <type>G_KEY_FILE_ERROR_INVALID_VALUE</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the number of booleans returned</para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-comment</title><informalexample><programlisting>(define-values (%return) (key-file:get-comment self group-name key))
</programlisting></informalexample><para>Retrieves a comment above <parameter>key</parameter> from <parameter>group_name</parameter>.
If <parameter>key</parameter> is <constant>NULL</constant> then <parameter>comment</parameter> will be read from above
<parameter>group_name</parameter>. If both <parameter>key</parameter> and <parameter>group_name</parameter> are <constant>NULL</constant>, then
<parameter>comment</parameter> will be read from above the first group in the file.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name, or <constant>NULL</constant></para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-double</title><informalexample><programlisting>(define-values (%return) (key-file:get-double self group-name key))
</programlisting></informalexample><para>Returns the value associated with <parameter>key</parameter> under <parameter>group_name</parameter> as a
double. If <parameter>group_name</parameter> is <constant>NULL</constant>, the start_group is used.
</para>
<para>If <parameter>key</parameter> cannot be found then 0.0 is returned and <parameter>error</parameter> is set to
<type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type>. Likewise, if the value associated
with <parameter>key</parameter> cannot be interpreted as a double then 0.0 is returned
and <parameter>error</parameter> is set to <type>G_KEY_FILE_ERROR_INVALID_VALUE</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-double-list</title><informalexample><programlisting>(define-values
  (%return length)
  (key-file:get-double-list self group-name key))
</programlisting></informalexample><para>Returns the values associated with <parameter>key</parameter> under <parameter>group_name</parameter> as
doubles.
</para>
<para>If <parameter>key</parameter> cannot be found then <constant>NULL</constant> is returned and <parameter>error</parameter> is set to
<type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type>. Likewise, if the values associated
with <parameter>key</parameter> cannot be interpreted as doubles then <constant>NULL</constant> is returned
and <parameter>error</parameter> is set to <type>G_KEY_FILE_ERROR_INVALID_VALUE</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the number of doubles returned</para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-groups</title><informalexample><programlisting>(define-values (%return length) (key-file:get-groups self))
</programlisting></informalexample><para>Returns all groups in the key file loaded with <parameter>key_file</parameter>.
The array of returned groups will be <constant>NULL</constant>-terminated, so
<parameter>length</parameter> may optionally be <constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>return location for the number of returned groups, or <constant>NULL</constant></para><para>Passed as <code>length</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-int64</title><informalexample><programlisting>(define-values (%return) (key-file:get-int64 self group-name key))
</programlisting></informalexample><para>Returns the value associated with <parameter>key</parameter> under <parameter>group_name</parameter> as a signed
64-bit integer. This is similar to <function>g_key_file_get_integer()</function> but can return
64-bit results without truncation.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a non-<constant>NULL</constant> <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a non-<constant>NULL</constant> group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a non-<constant>NULL</constant> key</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-integer</title><informalexample><programlisting>(define-values (%return) (key-file:get-integer self group-name key))
</programlisting></informalexample><para>Returns the value associated with <parameter>key</parameter> under <parameter>group_name</parameter> as an
integer.
</para>
<para>If <parameter>key</parameter> cannot be found then 0 is returned and <parameter>error</parameter> is set to
<type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type>. Likewise, if the value associated
with <parameter>key</parameter> cannot be interpreted as an integer, or is out of range
for a <type>gint</type>, then 0 is returned
and <parameter>error</parameter> is set to <type>G_KEY_FILE_ERROR_INVALID_VALUE</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-integer-list</title><informalexample><programlisting>(define-values
  (%return length)
  (key-file:get-integer-list self group-name key))
</programlisting></informalexample><para>Returns the values associated with <parameter>key</parameter> under <parameter>group_name</parameter> as
integers.
</para>
<para>If <parameter>key</parameter> cannot be found then <constant>NULL</constant> is returned and <parameter>error</parameter> is set to
<type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type>. Likewise, if the values associated
with <parameter>key</parameter> cannot be interpreted as integers, or are out of range for
<type>gint</type>, then <constant>NULL</constant> is returned
and <parameter>error</parameter> is set to <type>G_KEY_FILE_ERROR_INVALID_VALUE</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the number of integers returned</para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-keys</title><informalexample><programlisting>(define-values (%return length) (key-file:get-keys self group-name))
</programlisting></informalexample><para>Returns all keys for the group name <parameter>group_name</parameter>.  The array of
returned keys will be <constant>NULL</constant>-terminated, so <parameter>length</parameter> may
optionally be <constant>NULL</constant>. In the event that the <parameter>group_name</parameter> cannot
be found, <constant>NULL</constant> is returned and <parameter>error</parameter> is set to
<type>G_KEY_FILE_ERROR_GROUP_NOT_FOUND</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>return location for the number of keys returned, or <constant>NULL</constant></para><para>Passed as <code>length</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-locale-for-key</title><informalexample><programlisting>(define-values
  (%return)
  (key-file:get-locale-for-key self group-name key locale))
</programlisting></informalexample><para>Returns the actual locale which the result of
<function>g_key_file_get_locale_string()</function> or <function>g_key_file_get_locale_string_list()</function>
came from.
</para>
<para>If calling <function>g_key_file_get_locale_string()</function> or
<function>g_key_file_get_locale_string_list()</function> with exactly the same <parameter>key_file</parameter>,
<parameter>group_name</parameter>, <parameter>key</parameter> and <parameter>locale</parameter>, the result of those functions will
have originally been tagged with the locale that is the result of
this function.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>locale</para></td><td class="parameter_description"><para>a locale identifier or <constant>NULL</constant></para><para>Passed as <code>locale</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-locale-string</title><informalexample><programlisting>(define-values
  (%return)
  (key-file:get-locale-string self group-name key locale))
</programlisting></informalexample><para>Returns the value associated with <parameter>key</parameter> under <parameter>group_name</parameter>
translated in the given <parameter>locale</parameter> if available.  If <parameter>locale</parameter> is
<constant>NULL</constant> then the current locale is assumed.
</para>
<para>If <parameter>locale</parameter> is to be non-<constant>NULL</constant>, or if the current locale will change over
the lifetime of the <type>GKeyFile</type>, it must be loaded with
<constant>G_KEY_FILE_KEEP_TRANSLATIONS</constant> in order to load strings for all locales.
</para>
<para>If <parameter>key</parameter> cannot be found then <constant>NULL</constant> is returned and <parameter>error</parameter> is set
to <type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type>. If the value associated
with <parameter>key</parameter> cannot be interpreted or no suitable translation can
be found then the untranslated value is returned.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>locale</para></td><td class="parameter_description"><para>a locale identifier or <constant>NULL</constant></para><para>Passed as <code>locale</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-locale-string-list</title><informalexample><programlisting>(define-values
  (%return length)
  (key-file:get-locale-string-list self group-name key locale))
</programlisting></informalexample><para>Returns the values associated with <parameter>key</parameter> under <parameter>group_name</parameter>
translated in the given <parameter>locale</parameter> if available.  If <parameter>locale</parameter> is
<constant>NULL</constant> then the current locale is assumed.
</para>
<para>If <parameter>locale</parameter> is to be non-<constant>NULL</constant>, or if the current locale will change over
the lifetime of the <type>GKeyFile</type>, it must be loaded with
<constant>G_KEY_FILE_KEEP_TRANSLATIONS</constant> in order to load strings for all locales.
</para>
<para>If <parameter>key</parameter> cannot be found then <constant>NULL</constant> is returned and <parameter>error</parameter> is set
to <type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type>. If the values associated
with <parameter>key</parameter> cannot be interpreted or no suitable translations
can be found then the untranslated values are returned. The
returned array is <constant>NULL</constant>-terminated, so <parameter>length</parameter> may optionally
be <constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>locale</para></td><td class="parameter_description"><para>a locale identifier or <constant>NULL</constant></para><para>Passed as <code>locale</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>return location for the number of returned strings or <constant>NULL</constant></para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-start-group</title><informalexample><programlisting>(define-values (%return) (key-file:get-start-group self))
</programlisting></informalexample><para>Returns the name of the start group of the file.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-string</title><informalexample><programlisting>(define-values (%return) (key-file:get-string self group-name key))
</programlisting></informalexample><para>Returns the string value associated with <parameter>key</parameter> under <parameter>group_name</parameter>.
Unlike <function>g_key_file_get_value()</function>, this function handles escape sequences
like \s.
</para>
<para>In the event the key cannot be found, <constant>NULL</constant> is returned and
<parameter>error</parameter> is set to <type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type>.  In the
event that the <parameter>group_name</parameter> cannot be found, <constant>NULL</constant> is returned
and <parameter>error</parameter> is set to <type>G_KEY_FILE_ERROR_GROUP_NOT_FOUND</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-string-list</title><informalexample><programlisting>(define-values
  (%return length)
  (key-file:get-string-list self group-name key))
</programlisting></informalexample><para>Returns the values associated with <parameter>key</parameter> under <parameter>group_name</parameter>.
</para>
<para>In the event the key cannot be found, <constant>NULL</constant> is returned and
<parameter>error</parameter> is set to <type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type>.  In the
event that the <parameter>group_name</parameter> cannot be found, <constant>NULL</constant> is returned
and <parameter>error</parameter> is set to <type>G_KEY_FILE_ERROR_GROUP_NOT_FOUND</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>return location for the number of returned strings, or <constant>NULL</constant></para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-uint64</title><informalexample><programlisting>(define-values (%return) (key-file:get-uint64 self group-name key))
</programlisting></informalexample><para>Returns the value associated with <parameter>key</parameter> under <parameter>group_name</parameter> as an unsigned
64-bit integer. This is similar to <function>g_key_file_get_integer()</function> but can return
large positive results without truncation.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a non-<constant>NULL</constant> <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a non-<constant>NULL</constant> group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a non-<constant>NULL</constant> key</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-value</title><informalexample><programlisting>(define-values (%return) (key-file:get-value self group-name key))
</programlisting></informalexample><para>Returns the raw value associated with <parameter>key</parameter> under <parameter>group_name</parameter>.
Use <function>g_key_file_get_string()</function> to retrieve an unescaped UTF-8 string.
</para>
<para>In the event the key cannot be found, <constant>NULL</constant> is returned and
<parameter>error</parameter> is set to <type>G_KEY_FILE_ERROR_KEY_NOT_FOUND</type>.  In the
event that the <parameter>group_name</parameter> cannot be found, <constant>NULL</constant> is returned
and <parameter>error</parameter> is set to <type>G_KEY_FILE_ERROR_GROUP_NOT_FOUND</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>has-group?</title><informalexample><programlisting>(define-values (%return) (key-file:has-group? self group-name))
</programlisting></informalexample><para>Looks whether the key file has the group <parameter>group_name</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>load-from-bytes?</title><informalexample><programlisting>(define-values (%return) (key-file:load-from-bytes? self bytes flags))
</programlisting></informalexample><para>Loads a key file from the data in <parameter>bytes</parameter> into an empty <type>GKeyFile</type> structure.
If the object cannot be created then <constant>error</constant> is set to a <type>GKeyFileError</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>an empty <type>GKeyFile</type> struct</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>bytes</para></td><td class="parameter_description"><para>a <type>GBytes</type></para><para>Passed as <code>bytes</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags from <type>GKeyFileFlags</type></para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>load-from-data?</title><informalexample><programlisting>(define-values (%return) (key-file:load-from-data? self data length flags))
</programlisting></informalexample><para>Loads a key file from memory into an empty <type>GKeyFile</type> structure.
If the object cannot be created then <constant>error</constant> is set to a <type>GKeyFileError</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>an empty <type>GKeyFile</type> struct</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>key file loaded in memory</para><para>Passed as <code>data</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of <parameter>data</parameter> in bytes (or (gsize)-1 if data is nul-terminated)</para><para>Passed as <code>length</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags from <type>GKeyFileFlags</type></para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>load-from-data-dirs</title><informalexample><programlisting>(define-values
  (%return full-path)
  (key-file:load-from-data-dirs self file flags))
</programlisting></informalexample><para>This function looks for a key file named <parameter>file</parameter> in the paths
returned from <function>g_get_user_data_dir()</function> and <function>g_get_system_data_dirs()</function>,
loads the file into <parameter>key_file</parameter> and returns the file's full path in
<parameter>full_path</parameter>.  If the file could not be loaded then an <constant>error</constant> is
set to either a <type>GFileError</type> or <type>GKeyFileError</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>an empty <type>GKeyFile</type> struct</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>file</para></td><td class="parameter_description"><para>a relative path to a filename to open and parse</para><para>Passed as <code>file</code></para></td></tr><tr><td class="parameter_name"><para>full_path</para></td><td class="parameter_description"><para>return location for a string containing the full path
  of the file, or <constant>NULL</constant></para><para>Passed as <code>full-path</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags from <type>GKeyFileFlags</type></para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>load-from-dirs</title><informalexample><programlisting>(define-values
  (%return full-path)
  (key-file:load-from-dirs self file search-dirs flags))
</programlisting></informalexample><para>This function looks for a key file named <parameter>file</parameter> in the paths
specified in <parameter>search_dirs</parameter>, loads the file into <parameter>key_file</parameter> and
returns the file's full path in <parameter>full_path</parameter>.
</para>
<para>If the file could not be found in any of the <parameter>search_dirs</parameter>,
<constant>G_KEY_FILE_ERROR_NOT_FOUND</constant> is returned. If
the file is found but the OS returns an error when opening or reading the
file, a <constant>G_FILE_ERROR</constant> is returned. If there is a problem parsing the file, a
<constant>G_KEY_FILE_ERROR</constant> is returned.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>an empty <type>GKeyFile</type> struct</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>file</para></td><td class="parameter_description"><para>a relative path to a filename to open and parse</para><para>Passed as <code>file</code></para></td></tr><tr><td class="parameter_name"><para>search_dirs</para></td><td class="parameter_description"><para><constant>NULL</constant>-terminated array of directories to search</para><para>Passed as <code>search-dirs</code></para></td></tr><tr><td class="parameter_name"><para>full_path</para></td><td class="parameter_description"><para>return location for a string containing the full path
  of the file, or <constant>NULL</constant></para><para>Passed as <code>full-path</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags from <type>GKeyFileFlags</type></para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>load-from-file?</title><informalexample><programlisting>(define-values (%return) (key-file:load-from-file? self file flags))
</programlisting></informalexample><para>Loads a key file into an empty <type>GKeyFile</type> structure.
</para>
<para>If the OS returns an error when opening or reading the file, a
<constant>G_FILE_ERROR</constant> is returned. If there is a problem parsing the file, a
<constant>G_KEY_FILE_ERROR</constant> is returned.
</para>
<para>This function will never return a <constant>G_KEY_FILE_ERROR_NOT_FOUND</constant> error. If the
<parameter>file</parameter> is not found, <constant>G_FILE_ERROR_NOENT</constant> is returned.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>an empty <type>GKeyFile</type> struct</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>file</para></td><td class="parameter_description"><para>the path of a filename to load, in the GLib filename encoding</para><para>Passed as <code>file</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags from <type>GKeyFileFlags</type></para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>remove-comment?</title><informalexample><programlisting>(define-values (%return) (key-file:remove-comment? self group-name key))
</programlisting></informalexample><para>Removes a comment above <parameter>key</parameter> from <parameter>group_name</parameter>.
If <parameter>key</parameter> is <constant>NULL</constant> then <parameter>comment</parameter> will be removed above <parameter>group_name</parameter>.
If both <parameter>key</parameter> and <parameter>group_name</parameter> are <constant>NULL</constant>, then <parameter>comment</parameter> will
be removed above the first group in the file.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name, or <constant>NULL</constant></para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>remove-group?</title><informalexample><programlisting>(define-values (%return) (key-file:remove-group? self group-name))
</programlisting></informalexample><para>Removes the specified group, <parameter>group_name</parameter>,
from the key file.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>remove-key?</title><informalexample><programlisting>(define-values (%return) (key-file:remove-key? self group-name key))
</programlisting></informalexample><para>Removes <parameter>key</parameter> in <parameter>group_name</parameter> from the key file.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key name to remove</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>save-to-file?</title><informalexample><programlisting>(define-values (%return) (key-file:save-to-file? self filename))
</programlisting></informalexample><para>Writes the contents of <parameter>key_file</parameter> to <parameter>filename</parameter> using
<function>g_file_set_contents()</function>. If you need stricter guarantees about durability of
the written file than are provided by <function>g_file_set_contents()</function>, use
<function>g_file_set_contents_full()</function> with the return value of <function>g_key_file_to_data()</function>.
</para>
<para>This function can fail for any of the reasons that
<function>g_file_set_contents()</function> may fail.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>filename</para></td><td class="parameter_description"><para>the name of the file to write to</para><para>Passed as <code>filename</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-boolean</title><informalexample><programlisting>(define-values () (key-file:set-boolean self group-name key value))
</programlisting></informalexample><para>Associates a new boolean value with <parameter>key</parameter> under <parameter>group_name</parameter>.
If <parameter>key</parameter> cannot be found then it is created.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para><constant>TRUE</constant> or <constant>FALSE</constant></para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-boolean-list</title><informalexample><programlisting>(define-values () (key-file:set-boolean-list self group-name key list))
</programlisting></informalexample><para>Associates a list of boolean values with <parameter>key</parameter> under <parameter>group_name</parameter>.
If <parameter>key</parameter> cannot be found then it is created.
If <parameter>group_name</parameter> is <constant>NULL</constant>, the start_group is used.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>list</para></td><td class="parameter_description"><para>an array of boolean values</para><para>Passed as <code>list</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>length of <parameter>list</parameter></para><para>Inferred from <code>list</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-comment?</title><informalexample><programlisting>(define-values (%return) (key-file:set-comment? self group-name key comment))
</programlisting></informalexample><para>Places a comment above <parameter>key</parameter> from <parameter>group_name</parameter>.
</para>
<para>If <parameter>key</parameter> is <constant>NULL</constant> then <parameter>comment</parameter> will be written above <parameter>group_name</parameter>.
If both <parameter>key</parameter> and <parameter>group_name</parameter>  are <constant>NULL</constant>, then <parameter>comment</parameter> will be
written above the first group in the file.
</para>
<para>Note that this function prepends a '#' comment marker to
each line of <parameter>comment</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name, or <constant>NULL</constant></para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>comment</para></td><td class="parameter_description"><para>a comment</para><para>Passed as <code>comment</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-double</title><informalexample><programlisting>(define-values () (key-file:set-double self group-name key value))
</programlisting></informalexample><para>Associates a new double value with <parameter>key</parameter> under <parameter>group_name</parameter>.
If <parameter>key</parameter> cannot be found then it is created.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a double value</para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-double-list</title><informalexample><programlisting>(define-values () (key-file:set-double-list self group-name key list))
</programlisting></informalexample><para>Associates a list of double values with <parameter>key</parameter> under
<parameter>group_name</parameter>.  If <parameter>key</parameter> cannot be found then it is created.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>list</para></td><td class="parameter_description"><para>an array of double values</para><para>Passed as <code>list</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>number of double values in <parameter>list</parameter></para><para>Inferred from <code>list</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-int64</title><informalexample><programlisting>(define-values () (key-file:set-int64 self group-name key value))
</programlisting></informalexample><para>Associates a new integer value with <parameter>key</parameter> under <parameter>group_name</parameter>.
If <parameter>key</parameter> cannot be found then it is created.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>an integer value</para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-integer</title><informalexample><programlisting>(define-values () (key-file:set-integer self group-name key value))
</programlisting></informalexample><para>Associates a new integer value with <parameter>key</parameter> under <parameter>group_name</parameter>.
If <parameter>key</parameter> cannot be found then it is created.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>an integer value</para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-integer-list</title><informalexample><programlisting>(define-values () (key-file:set-integer-list self group-name key list))
</programlisting></informalexample><para>Associates a list of integer values with <parameter>key</parameter> under <parameter>group_name</parameter>.
If <parameter>key</parameter> cannot be found then it is created.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>list</para></td><td class="parameter_description"><para>an array of integer values</para><para>Passed as <code>list</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>number of integer values in <parameter>list</parameter></para><para>Inferred from <code>list</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-list-separator</title><informalexample><programlisting>(define-values () (key-file:set-list-separator self separator))
</programlisting></informalexample><para>Sets the character which is used to separate
values in lists. Typically ';' or ',' are used
as separators. The default list separator is ';'.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>separator</para></td><td class="parameter_description"><para>the separator</para><para>Passed as <code>separator</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-locale-string</title><informalexample><programlisting>(define-values
  ()
  (key-file:set-locale-string self group-name key locale string))
</programlisting></informalexample><para>Associates a string value for <parameter>key</parameter> and <parameter>locale</parameter> under <parameter>group_name</parameter>.
If the translation for <parameter>key</parameter> cannot be found then it is created.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>locale</para></td><td class="parameter_description"><para>a locale identifier</para><para>Passed as <code>locale</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-locale-string-list</title><informalexample><programlisting>(define-values
  ()
  (key-file:set-locale-string-list self group-name key locale list))
</programlisting></informalexample><para>Associates a list of string values for <parameter>key</parameter> and <parameter>locale</parameter> under
<parameter>group_name</parameter>.  If the translation for <parameter>key</parameter> cannot be found then
it is created.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>locale</para></td><td class="parameter_description"><para>a locale identifier</para><para>Passed as <code>locale</code></para></td></tr><tr><td class="parameter_name"><para>list</para></td><td class="parameter_description"><para>a <constant>NULL</constant>-terminated array of locale string values</para><para>Passed as <code>list</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of <parameter>list</parameter></para><para>Inferred from <code>list</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-string</title><informalexample><programlisting>(define-values () (key-file:set-string self group-name key string))
</programlisting></informalexample><para>Associates a new string value with <parameter>key</parameter> under <parameter>group_name</parameter>.
If <parameter>key</parameter> cannot be found then it is created.
If <parameter>group_name</parameter> cannot be found then it is created.
Unlike <function>g_key_file_set_value()</function>, this function handles characters
that need escaping, such as newlines.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-string-list</title><informalexample><programlisting>(define-values () (key-file:set-string-list self group-name key list))
</programlisting></informalexample><para>Associates a list of string values for <parameter>key</parameter> under <parameter>group_name</parameter>.
If <parameter>key</parameter> cannot be found then it is created.
If <parameter>group_name</parameter> cannot be found then it is created.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>list</para></td><td class="parameter_description"><para>an array of string values</para><para>Passed as <code>list</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>number of string values in <parameter>list</parameter></para><para>Inferred from <code>list</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-uint64</title><informalexample><programlisting>(define-values () (key-file:set-uint64 self group-name key value))
</programlisting></informalexample><para>Associates a new integer value with <parameter>key</parameter> under <parameter>group_name</parameter>.
If <parameter>key</parameter> cannot be found then it is created.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>an integer value</para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-value</title><informalexample><programlisting>(define-values () (key-file:set-value self group-name key value))
</programlisting></informalexample><para>Associates a new value with <parameter>key</parameter> under <parameter>group_name</parameter>.
</para>
<para>If <parameter>key</parameter> cannot be found then it is created. If <parameter>group_name</parameter> 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
<function>g_key_file_set_string()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>group_name</para></td><td class="parameter_description"><para>a group name</para><para>Passed as <code>group-name</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>to-data</title><informalexample><programlisting>(define-values (%return length) (key-file:to-data self))
</programlisting></informalexample><para>This function outputs <parameter>key_file</parameter> as a string.
</para>
<para>Note that this function never reports an error,
so it is safe to pass <constant>NULL</constant> as <parameter>error</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>return location for the length of the
  returned string, or <constant>NULL</constant></para><para>Passed as <code>length</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (key-file:unref self))
</programlisting></informalexample><para>Decreases the reference count of <parameter>key_file</parameter> by 1. If the reference count
reaches zero, frees the key file and all its allocated memory.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_file</para></td><td class="parameter_description"><para>a <type>GKeyFile</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>key-file:new</title><informalexample><programlisting>(define-values (%return) (key-file:new))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>key-file:error-quark</title><informalexample><programlisting>(define-values (%return) (key-file:error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibKeyFileError&gt;</refname></refnamediv><refsect1><title>Description</title><para>Error codes returned by key file parsing.</para></refsect1><refsect1><title>Members</title><refsect2><title>unknown-encoding</title><remark>alias <code>G_KEY_FILE_ERROR_UNKNOWN_ENCODING</code></remark><para>the text being parsed was in
    an unknown encoding</para></refsect2><refsect2><title>parse</title><remark>alias <code>G_KEY_FILE_ERROR_PARSE</code></remark><para>document was ill-formed</para></refsect2><refsect2><title>not-found</title><remark>alias <code>G_KEY_FILE_ERROR_NOT_FOUND</code></remark><para>the file was not found</para></refsect2><refsect2><title>key-not-found</title><remark>alias <code>G_KEY_FILE_ERROR_KEY_NOT_FOUND</code></remark><para>a requested key was not found</para></refsect2><refsect2><title>group-not-found</title><remark>alias <code>G_KEY_FILE_ERROR_GROUP_NOT_FOUND</code></remark><para>a requested group was not found</para></refsect2><refsect2><title>invalid-value</title><remark>alias <code>G_KEY_FILE_ERROR_INVALID_VALUE</code></remark><para>a value could not be parsed</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibKeyFileFlags&gt;</refname></refnamediv><refsect1><title>Description</title><para>Flags which influence the parsing.</para></refsect1><refsect1><title>Members</title><refsect2><title>none</title><remark>alias <code>G_KEY_FILE_NONE</code></remark><para>No flags, default behaviour</para></refsect2><refsect2><title>keep-comments</title><remark>alias <code>G_KEY_FILE_KEEP_COMMENTS</code></remark><para>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.</para></refsect2><refsect2><title>keep-translations</title><remark>alias <code>G_KEY_FILE_KEEP_TRANSLATIONS</code></remark><para>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.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibLogLevelFlags&gt;</refname></refnamediv><refsect1><title>Description</title><para>Flags specifying the level of log messages.
</para>
<para>It is possible to change how GLib treats messages of the various
levels using <function>g_log_set_handler()</function> and <function>g_log_set_fatal_mask()</function>.</para></refsect1><refsect1><title>Members</title><refsect2><title>flag-recursion</title><remark>alias <code>G_LOG_FLAG_RECURSION</code></remark><para>internal flag</para></refsect2><refsect2><title>flag-fatal</title><remark>alias <code>G_LOG_FLAG_FATAL</code></remark><para>internal flag</para></refsect2><refsect2><title>level-error</title><remark>alias <code>G_LOG_LEVEL_ERROR</code></remark><para>log level for errors, see <function>g_error()</function>.
    This level is also used for messages produced by <function>g_assert()</function>.</para></refsect2><refsect2><title>level-critical</title><remark>alias <code>G_LOG_LEVEL_CRITICAL</code></remark><para>log level for critical warning messages, see
    <function>g_critical()</function>.
    This level is also used for messages produced by <function>g_return_if_fail()</function>
    and <function>g_return_val_if_fail()</function>.</para></refsect2><refsect2><title>level-warning</title><remark>alias <code>G_LOG_LEVEL_WARNING</code></remark><para>log level for warnings, see <function>g_warning()</function></para></refsect2><refsect2><title>level-message</title><remark>alias <code>G_LOG_LEVEL_MESSAGE</code></remark><para>log level for messages, see <function>g_message()</function></para></refsect2><refsect2><title>level-info</title><remark>alias <code>G_LOG_LEVEL_INFO</code></remark><para>log level for informational messages, see <function>g_info()</function></para></refsect2><refsect2><title>level-debug</title><remark>alias <code>G_LOG_LEVEL_DEBUG</code></remark><para>log level for debug messages, see <function>g_debug()</function></para></refsect2><refsect2><title>level-mask</title><remark>alias <code>G_LOG_LEVEL_MASK</code></remark><para>a mask including all log levels</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibLogWriterOutput&gt;</refname></refnamediv><refsect1><title>Description</title><para>Return values from <type>GLogWriterFuncs</type> 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).
</para>
<para>If a <type>GLogWriterFunc</type> ignores a log entry, it should return
<constant>G_LOG_WRITER_HANDLED</constant>.</para></refsect1><refsect1><title>Members</title><refsect2><title>handled</title><remark>alias <code>G_LOG_WRITER_HANDLED</code></remark><para>Log writer has handled the log entry.</para></refsect2><refsect2><title>unhandled</title><remark>alias <code>G_LOG_WRITER_UNHANDLED</code></remark><para>Log writer could not handle the log entry.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GMainContext&gt;</refname></refnamediv><refsect1><title>Description</title><para>The <code>GMainContext</code> struct is an opaque data
type representing a set of sources to be handled in a main loop.</para></refsect1><refsect1><title>Functions</title><refsect2><title>acquire?</title><informalexample><programlisting>(define-values (%return) (main-context:acquire? self))
</programlisting></informalexample><para>Tries to become the owner of the specified context.
If some other thread is the owner of the context,
returns <constant>FALSE</constant> immediately. Ownership is properly
recursive: the owner can require ownership again
and will release ownership when <function>g_main_context_release()</function>
is called as many times as <function>g_main_context_acquire()</function>.
</para>
<para>You must be the owner of a context before you
can call <function>g_main_context_prepare()</function>, <function>g_main_context_query()</function>,
<function>g_main_context_check()</function>, <function>g_main_context_dispatch()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>add-poll</title><informalexample><programlisting>(define-values () (main-context:add-poll self fd priority))
</programlisting></informalexample><para>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 <function>g_source_add_unix_fd()</function> instead.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type> (or <constant>NULL</constant> for the default context)</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>fd</para></td><td class="parameter_description"><para>a <type>GPollFD</type> structure holding information about a file
     descriptor to watch.</para><para>Passed as <code>fd</code></para></td></tr><tr><td class="parameter_name"><para>priority</para></td><td class="parameter_description"><para>the priority for this file descriptor which should be
     the same as the priority used for <function>g_source_attach()</function> to ensure that the
     file descriptor is polled whenever the results may be needed.</para><para>Passed as <code>priority</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>check?</title><informalexample><programlisting>(define-values (%return) (main-context:check? self max-priority fds))
</programlisting></informalexample><para>Passes the results of polling back to the main loop.
</para>
<para>You must have successfully acquired the context with
<function>g_main_context_acquire()</function> before you may call this function.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>max_priority</para></td><td class="parameter_description"><para>the maximum numerical priority of sources to check</para><para>Passed as <code>max-priority</code></para></td></tr><tr><td class="parameter_name"><para>fds</para></td><td class="parameter_description"><para>array of <type>GPollFD</type>'s that was passed to
      the last call to <function>g_main_context_query()</function></para><para>Passed as <code>fds</code></para></td></tr><tr><td class="parameter_name"><para>n_fds</para></td><td class="parameter_description"><para>return value of <function>g_main_context_query()</function></para><para>Inferred from <code>fds</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>dispatch</title><informalexample><programlisting>(define-values () (main-context:dispatch self))
</programlisting></informalexample><para>Dispatches all pending sources.
</para>
<para>You must have successfully acquired the context with
<function>g_main_context_acquire()</function> before you may call this function.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>find-source-by-id</title><informalexample><programlisting>(define-values (%return) (main-context:find-source-by-id self source-id))
</programlisting></informalexample><para>Finds a <type>GSource</type> given a pair of context and ID.
</para>
<para>It is a programmer error to attempt to look up a non-existent source.
</para>
<para>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 <function>g_idle_add()</function>: 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type> (if <constant>NULL</constant>, the default context will be used)</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>source_id</para></td><td class="parameter_description"><para>the source ID, as returned by <function>g_source_get_id()</function>.</para><para>Passed as <code>source-id</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>find-source-by-user-data</title><informalexample><programlisting>(define-values
  (%return)
  (main-context:find-source-by-user-data self user-data))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>user_data</para></td><td class="parameter_description"><para>the user_data for the callback.</para><para>Passed as <code>user-data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>invoke-full</title><informalexample><programlisting>(define-values
  ()
  (main-context:invoke-full self priority function data notify))
</programlisting></informalexample><para>Invokes a function in such a way that <parameter>context</parameter> is owned during the
invocation of <parameter>function</parameter>.
</para>
<para>This function is the same as <function>g_main_context_invoke()</function> except that it
lets you specify the priority in case <parameter>function</parameter> ends up being
scheduled as an idle and also lets you give a <type>GDestroyNotify</type> for <parameter>data</parameter>.
</para>
<para><parameter>notify</parameter> should not assume that it is called from any particular
thread or with any particular context acquired.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type>, or <constant>NULL</constant></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>priority</para></td><td class="parameter_description"><para>the priority at which to run <parameter>function</parameter></para><para>Passed as <code>priority</code></para></td></tr><tr><td class="parameter_name"><para>function</para></td><td class="parameter_description"><para>function to call</para><para>Passed as <code>function</code></para></td></tr><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>data to pass to <parameter>function</parameter></para><para>Passed as <code>data</code></para></td></tr><tr><td class="parameter_name"><para>notify</para></td><td class="parameter_description"><para>a function to call when <parameter>data</parameter> is no longer in use, or <constant>NULL</constant>.</para><para>Passed as <code>notify</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-owner?</title><informalexample><programlisting>(define-values (%return) (main-context:is-owner? self))
</programlisting></informalexample><para>Determines whether this thread holds the (recursive)
ownership of this <type>GMainContext</type>. This is useful to
know before waiting on another thread that may be
blocking to get ownership of <parameter>context</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>iteration?</title><informalexample><programlisting>(define-values (%return) (main-context:iteration? self may-block))
</programlisting></informalexample><para>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 <parameter>may_block</parameter> is <constant>TRUE</constant>, waiting
for a source to become ready, then dispatching the highest priority
events sources that are ready. Otherwise, if <parameter>may_block</parameter> is <constant>FALSE</constant>
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.
</para>
<para>Note that even when <parameter>may_block</parameter> is <constant>TRUE</constant>, it is still possible for
<function>g_main_context_iteration()</function> to return <constant>FALSE</constant>, since the wait may
be interrupted for other reasons than an event source becoming ready.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type> (if <constant>NULL</constant>, the default context will be used)</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>may_block</para></td><td class="parameter_description"><para>whether the call may block.</para><para>Passed as <code>may-block</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>pending?</title><informalexample><programlisting>(define-values (%return) (main-context:pending? self))
</programlisting></informalexample><para>Checks if any sources have pending events for the given context.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type> (if <constant>NULL</constant>, the default context will be used)</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>pop-thread-default</title><informalexample><programlisting>(define-values () (main-context:pop-thread-default self))
</programlisting></informalexample><para>Pops <parameter>context</parameter> off the thread-default context stack (verifying that
it was on the top of the stack).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type> object, or <constant>NULL</constant></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>prepare</title><informalexample><programlisting>(define-values (%return priority) (main-context:prepare self))
</programlisting></informalexample><para>Prepares to poll sources within a main loop. The resulting information
for polling is determined by calling g_main_context_query ().
</para>
<para>You must have successfully acquired the context with
<function>g_main_context_acquire()</function> before you may call this function.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>priority</para></td><td class="parameter_description"><para>location to store priority of highest priority
           source already ready.</para><para>Passed as <code>priority</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>push-thread-default</title><informalexample><programlisting>(define-values () (main-context:push-thread-default self))
</programlisting></informalexample><para>Acquires <parameter>context</parameter> 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 <parameter>context</parameter> 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 <function>g_main_context_get_thread_default()</function>,
not the one returned by <function>g_main_context_default()</function>, so it does not affect
the context used by functions like <function>g_idle_add()</function>.
</para>
<para>Normally you would call this function shortly after creating a new
thread, passing it a <type>GMainContext</type> which will be run by a
<type>GMainLoop</type> 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 <function>g_main_context_pop_thread_default()</function>, assuming you want the
new <type>GMainContext</type> to be the default for the whole lifecycle of the
thread.
</para>
<para>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 <type>GThreadPool</type>), it is always suggested to wrap
the logic that needs to use the new <type>GMainContext</type> inside a
<function>g_main_context_push_thread_default()</function> / <function>g_main_context_pop_thread_default()</function>
pair, otherwise threads that are re-used will end up never explicitly
releasing the <type>GMainContext</type> reference they hold.
</para>
<para>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
<function>g_main_context_push_thread_default()</function> /
<function>g_main_context_pop_thread_default()</function> pair, but it is up to you to
ensure that no other asynchronous operations accidentally get
started while the non-default context is active.
</para>
<para>Beware that libraries that predate this function may not correctly
handle being used from a thread with a thread-default context. Eg,
see <function>g_file_supports_thread_contexts()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type>, or <constant>NULL</constant> for the global default context</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>query!</title><informalexample><programlisting>(define-values
  (%return timeout- fds)
  (main-context:query! self max-priority fds))
</programlisting></informalexample><para>Determines information necessary to poll this main loop.
</para>
<para>You must have successfully acquired the context with
<function>g_main_context_acquire()</function> before you may call this function.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>max_priority</para></td><td class="parameter_description"><para>maximum priority source to check</para><para>Passed as <code>max-priority</code></para></td></tr><tr><td class="parameter_name"><para>timeout_</para></td><td class="parameter_description"><para>location to store timeout to be used in polling</para><para>Passed as <code>timeout-</code></para></td></tr><tr><td class="parameter_name"><para>fds</para></td><td class="parameter_description"><para>location to
      store <type>GPollFD</type> records that need to be polled.</para><para>Passed as <code>fds</code></para></td></tr><tr><td class="parameter_name"><para>n_fds</para></td><td class="parameter_description"><para>length of <parameter>fds</parameter>.</para><para>Inferred from <code>fds</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref</title><informalexample><programlisting>(define-values (%return) (main-context:ref self))
</programlisting></informalexample><para>Increases the reference count on a <type>GMainContext</type> object by one.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>release</title><informalexample><programlisting>(define-values () (main-context:release self))
</programlisting></informalexample><para>Releases ownership of a context previously acquired by this thread
with <function>g_main_context_acquire()</function>. If the context was acquired multiple
times, the ownership will be released only when <function>g_main_context_release()</function>
is called as many times as it was acquired.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>remove-poll</title><informalexample><programlisting>(define-values () (main-context:remove-poll self fd))
</programlisting></informalexample><para>Removes file descriptor from the set of file descriptors to be
polled for a particular context.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>fd</para></td><td class="parameter_description"><para>a <type>GPollFD</type> descriptor previously added with <function>g_main_context_add_poll()</function></para><para>Passed as <code>fd</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (main-context:unref self))
</programlisting></informalexample><para>Decreases the reference count on a <type>GMainContext</type> object by one. If
the result is zero, free the context and free all associated memory.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>wakeup</title><informalexample><programlisting>(define-values () (main-context:wakeup self))
</programlisting></informalexample><para>If <parameter>context</parameter> is currently blocking in <function>g_main_context_iteration()</function>
waiting for a source to become ready, cause it to stop blocking
and return.  Otherwise, cause the next invocation of
<function>g_main_context_iteration()</function> to return without blocking.
</para>
<para>This API is useful for low-level control over <type>GMainContext</type>; for
example, integrating it with main loop implementations such as
<type>GMainLoop</type>.
</para>
<para>Another related use for this function is when implementing a main
loop with a termination condition, computed from multiple threads:
</para>
<para><informalexample><programlisting>
  #define NUM_TASKS 10
  static volatile gint tasks_remaining = NUM_TASKS;
  ...
 
  while (g_atomic_int_get (&amp;tasks_remaining) != 0)
    g_main_context_iteration (NULL, TRUE);
</programlisting></informalexample></para>
 
<para>Then in a thread:
<informalexample><programlisting>
  perform_work();

  if (g_atomic_int_dec_and_test (&amp;tasks_remaining))
    g_main_context_wakeup (NULL);
</programlisting></informalexample></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>main-context:new</title><informalexample><programlisting>(define-values (%return) (main-context:new))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>main-context:default</title><informalexample><programlisting>(define-values (%return) (main-context:default))
</programlisting></informalexample><para>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 &quot;main&quot; main loop. See also
<function>g_main_context_get_thread_default()</function>.</para></refsect2><refsect2><title>main-context:get-thread-default</title><informalexample><programlisting>(define-values (%return) (main-context:get-thread-default))
</programlisting></informalexample><para>Gets the thread-default <type>GMainContext</type> 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
<function>g_main_context_ref_thread_default()</function> to get a <type>GMainContext</type> to add
their <type>GSources</type> 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 <constant>NULL</constant> if you are running in the default thread.)
</para>
<para>If you need to hold a reference on the context, use
<function>g_main_context_ref_thread_default()</function> instead.</para></refsect2><refsect2><title>main-context:ref-thread-default</title><informalexample><programlisting>(define-values (%return) (main-context:ref-thread-default))
</programlisting></informalexample><para>Gets the thread-default <type>GMainContext</type> for this thread, as with
<function>g_main_context_get_thread_default()</function>, but also adds a reference to
it with <function>g_main_context_ref()</function>. In addition, unlike
<function>g_main_context_get_thread_default()</function>, if the thread-default context
is the global default context, this will return that <type>GMainContext</type>
(with a ref added to it) rather than returning <constant>NULL</constant>.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GMainLoop&gt;</refname></refnamediv><refsect1><title>Description</title><para>The <code>GMainLoop</code> struct is an opaque data type
representing the main event loop of a GLib or GTK+ application.</para></refsect1><refsect1><title>Functions</title><refsect2><title>get-context</title><informalexample><programlisting>(define-values (%return) (main-loop:get-context self))
</programlisting></informalexample><para>Returns the <type>GMainContext</type> of <parameter>loop</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>loop</para></td><td class="parameter_description"><para>a <type>GMainLoop</type>.</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-running?</title><informalexample><programlisting>(define-values (%return) (main-loop:is-running? self))
</programlisting></informalexample><para>Checks to see if the main loop is currently being run via <function>g_main_loop_run()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>loop</para></td><td class="parameter_description"><para>a <type>GMainLoop</type>.</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>quit</title><informalexample><programlisting>(define-values () (main-loop:quit self))
</programlisting></informalexample><para>Stops a <type>GMainLoop</type> from running. Any calls to <function>g_main_loop_run()</function>
for the loop will return.
</para>
<para>Note that sources that have already been dispatched when
<function>g_main_loop_quit()</function> is called will still be executed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>loop</para></td><td class="parameter_description"><para>a <type>GMainLoop</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref</title><informalexample><programlisting>(define-values (%return) (main-loop:ref self))
</programlisting></informalexample><para>Increases the reference count on a <type>GMainLoop</type> object by one.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>loop</para></td><td class="parameter_description"><para>a <type>GMainLoop</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>run</title><informalexample><programlisting>(define-values () (main-loop:run self))
</programlisting></informalexample><para>Runs a main loop until <function>g_main_loop_quit()</function> is called on the loop.
If this is called for the thread of the loop's <type>GMainContext</type>,
it will process events from the loop, otherwise it will
simply wait.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>loop</para></td><td class="parameter_description"><para>a <type>GMainLoop</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (main-loop:unref self))
</programlisting></informalexample><para>Decreases the reference count on a <type>GMainLoop</type> object by one. If
the result is zero, free the loop and free all associated memory.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>loop</para></td><td class="parameter_description"><para>a <type>GMainLoop</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>main-loop:new</title><informalexample><programlisting>(define-values (%return) (main-loop:new context is-running))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para></para><para>Passed as <code>context</code></para></td></tr><tr><td class="parameter_name"><para>is_running</para></td><td class="parameter_description"><para></para><para>Passed as <code>is-running</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GMappedFile&gt;</refname></refnamediv><refsect1><title>Description</title><para>The <type>GMappedFile</type> represents a file mapping created with
<function>g_mapped_file_new()</function>. It has only private members and should
not be accessed directly.</para></refsect1><refsect1><title>Functions</title><refsect2><title>free</title><informalexample><programlisting>(define-values () (mapped-file:free self))
</programlisting></informalexample><para>This call existed before <type>GMappedFile</type> had refcounting and is currently
exactly the same as <function>g_mapped_file_unref()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>file</para></td><td class="parameter_description"><para>a <type>GMappedFile</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-bytes</title><informalexample><programlisting>(define-values (%return) (mapped-file:get-bytes self))
</programlisting></informalexample><para>Creates a new <type>GBytes</type> which references the data mapped from <parameter>file</parameter>.
The mapped contents of the file must not be modified after creating this
bytes object, because a <type>GBytes</type> should be immutable.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>file</para></td><td class="parameter_description"><para>a <type>GMappedFile</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-contents</title><informalexample><programlisting>(define-values (%return) (mapped-file:get-contents self))
</programlisting></informalexample><para>Returns the contents of a <type>GMappedFile</type>.
</para>
<para>Note that the contents may not be zero-terminated,
even if the <type>GMappedFile</type> is backed by a text file.
</para>
<para>If the file is empty then <constant>NULL</constant> is returned.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>file</para></td><td class="parameter_description"><para>a <type>GMappedFile</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-length</title><informalexample><programlisting>(define-values (%return) (mapped-file:get-length self))
</programlisting></informalexample><para>Returns the length of the contents of a <type>GMappedFile</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>file</para></td><td class="parameter_description"><para>a <type>GMappedFile</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref</title><informalexample><programlisting>(define-values (%return) (mapped-file:ref self))
</programlisting></informalexample><para>Increments the reference count of <parameter>file</parameter> by one.  It is safe to call
this function from any thread.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>file</para></td><td class="parameter_description"><para>a <type>GMappedFile</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (mapped-file:unref self))
</programlisting></informalexample><para>Decrements the reference count of <parameter>file</parameter> by one.  If the reference count
drops to 0, unmaps the buffer of <parameter>file</parameter> and frees it.
</para>
<para>It is safe to call this function from any thread.
</para>
<para>Since 2.22</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>file</para></td><td class="parameter_description"><para>a <type>GMappedFile</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>mapped-file:new-from-fd</title><informalexample><programlisting>(define-values (%return) (mapped-file:new-from-fd fd writable))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>fd</para></td><td class="parameter_description"><para></para><para>Passed as <code>fd</code></para></td></tr><tr><td class="parameter_name"><para>writable</para></td><td class="parameter_description"><para></para><para>Passed as <code>writable</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>mapped-file:new</title><informalexample><programlisting>(define-values (%return) (mapped-file:new filename writable))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>filename</para></td><td class="parameter_description"><para></para><para>Passed as <code>filename</code></para></td></tr><tr><td class="parameter_name"><para>writable</para></td><td class="parameter_description"><para></para><para>Passed as <code>writable</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibMarkupCollectType&gt;</refname></refnamediv><refsect1><title>Description</title><para>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 <constant>G_MARKUP_COLLECT_OPTIONAL</constant>.
</para>
<para>It is likely that this enum will be extended in the future to
support other types.</para></refsect1><refsect1><title>Members</title><refsect2><title>invalid</title><remark>alias <code>G_MARKUP_COLLECT_INVALID</code></remark><para>used to terminate the list of attributes
    to collect</para></refsect2><refsect2><title>string</title><remark>alias <code>G_MARKUP_COLLECT_STRING</code></remark><para>collect the string pointer directly from
    the attribute_values[] array. Expects a parameter of type (const
    char **). If <constant>G_MARKUP_COLLECT_OPTIONAL</constant> is specified and the
    attribute isn't present then the pointer will be set to <constant>NULL</constant></para></refsect2><refsect2><title>strdup</title><remark>alias <code>G_MARKUP_COLLECT_STRDUP</code></remark><para>as with <constant>G_MARKUP_COLLECT_STRING</constant>, but
    expects a parameter of type (char **) and <function>g_strdup()</function>s the
    returned pointer. The pointer must be freed with <function>g_free()</function></para></refsect2><refsect2><title>boolean</title><remark>alias <code>G_MARKUP_COLLECT_BOOLEAN</code></remark><para>expects a parameter of type (gboolean *)
    and parses the attribute value as a boolean. Sets <constant>FALSE</constant> if the
    attribute isn't present. Valid boolean values consist of
    (case-insensitive) &quot;false&quot;, &quot;f&quot;, &quot;no&quot;, &quot;n&quot;, &quot;0&quot; and &quot;true&quot;, &quot;t&quot;,
    &quot;yes&quot;, &quot;y&quot;, &quot;1&quot;</para></refsect2><refsect2><title>tristate</title><remark>alias <code>G_MARKUP_COLLECT_TRISTATE</code></remark><para>as with <constant>G_MARKUP_COLLECT_BOOLEAN</constant>, but
    in the case of a missing attribute a value is set that compares
    equal to neither <constant>FALSE</constant> nor <constant>TRUE</constant> G_MARKUP_COLLECT_OPTIONAL is
    implied</para></refsect2><refsect2><title>optional</title><remark>alias <code>G_MARKUP_COLLECT_OPTIONAL</code></remark><para>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</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibMarkupError&gt;</refname></refnamediv><refsect1><title>Description</title><para>Error codes returned by markup parsing.</para></refsect1><refsect1><title>Members</title><refsect2><title>bad-utf8</title><remark>alias <code>G_MARKUP_ERROR_BAD_UTF8</code></remark><para>text being parsed was not valid UTF-8</para></refsect2><refsect2><title>empty</title><remark>alias <code>G_MARKUP_ERROR_EMPTY</code></remark><para>document contained nothing, or only whitespace</para></refsect2><refsect2><title>parse</title><remark>alias <code>G_MARKUP_ERROR_PARSE</code></remark><para>document was ill-formed</para></refsect2><refsect2><title>unknown-element</title><remark>alias <code>G_MARKUP_ERROR_UNKNOWN_ELEMENT</code></remark><para>error should be set by <type>GMarkupParser</type>
    functions; element wasn't known</para></refsect2><refsect2><title>unknown-attribute</title><remark>alias <code>G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE</code></remark><para>error should be set by <type>GMarkupParser</type>
    functions; attribute wasn't known</para></refsect2><refsect2><title>invalid-content</title><remark>alias <code>G_MARKUP_ERROR_INVALID_CONTENT</code></remark><para>error should be set by <type>GMarkupParser</type>
    functions; content was invalid</para></refsect2><refsect2><title>missing-attribute</title><remark>alias <code>G_MARKUP_ERROR_MISSING_ATTRIBUTE</code></remark><para>error should be set by <type>GMarkupParser</type>
    functions; a required attribute was missing</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GMarkupParseContext&gt;</refname></refnamediv><refsect1><title>Description</title><para>A parse context is used to parse a stream of bytes that
you expect to contain marked-up text.
</para>
<para>See <function>g_markup_parse_context_new()</function>, <type>GMarkupParser</type>, and so
on for more details.</para></refsect1><refsect1><title>Functions</title><refsect2><title>end-parse?</title><informalexample><programlisting>(define-values (%return) (markup-parse-context:end-parse? self))
</programlisting></informalexample><para>Signals to the <type>GMarkupParseContext</type> that all data has been
fed into the parse context with <function>g_markup_parse_context_parse()</function>.
</para>
<para>This function reports an error if the document isn't complete,
for example if elements are still open.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMarkupParseContext</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>free</title><informalexample><programlisting>(define-values () (markup-parse-context:free self))
</programlisting></informalexample><para>Frees a <type>GMarkupParseContext</type>.
</para>
<para>This function can't be called from inside one of the
<type>GMarkupParser</type> functions or while a subparser is pushed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMarkupParseContext</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-element</title><informalexample><programlisting>(define-values (%return) (markup-parse-context:get-element self))
</programlisting></informalexample><para>Retrieves the name of the currently open element.
</para>
<para>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 <function>g_markup_parse_context_get_element_stack()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMarkupParseContext</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-position</title><informalexample><programlisting>(define-values
  (line-number char-number)
  (markup-parse-context:get-position self))
</programlisting></informalexample><para>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 &quot;current&quot; line number other than
&quot;the best number we could come up with for error messages.&quot;</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMarkupParseContext</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>line_number</para></td><td class="parameter_description"><para>return location for a line number, or <constant>NULL</constant></para><para>Passed as <code>line-number</code></para></td></tr><tr><td class="parameter_name"><para>char_number</para></td><td class="parameter_description"><para>return location for a char-on-line number, or <constant>NULL</constant></para><para>Passed as <code>char-number</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-user-data</title><informalexample><programlisting>(define-values (%return) (markup-parse-context:get-user-data self))
</programlisting></informalexample><para>Returns the user_data associated with <parameter>context</parameter>.
</para>
<para>This will either be the user_data that was provided to
<function>g_markup_parse_context_new()</function> or to the most recent call
of <function>g_markup_parse_context_push()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMarkupParseContext</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>parse?</title><informalexample><programlisting>(define-values (%return) (markup-parse-context:parse? self text text-len))
</programlisting></informalexample><para>Feed some data to the <type>GMarkupParseContext</type>.
</para>
<para>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 <type>GMarkupParseContext</type>;
all errors are fatal.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMarkupParseContext</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>text</para></td><td class="parameter_description"><para>chunk of text to parse</para><para>Passed as <code>text</code></para></td></tr><tr><td class="parameter_name"><para>text_len</para></td><td class="parameter_description"><para>length of <parameter>text</parameter> in bytes</para><para>Passed as <code>text-len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>pop</title><informalexample><programlisting>(define-values (%return) (markup-parse-context:pop self))
</programlisting></informalexample><para>Completes the process of a temporary sub-parser redirection.
</para>
<para>This function exists to collect the user_data allocated by a
matching call to <function>g_markup_parse_context_push()</function>. It must be called
in the end_element handler corresponding to the start_element
handler during which <function>g_markup_parse_context_push()</function> was called.
You must not call this function from the error callback -- the
<parameter>user_data</parameter> is provided directly to the callback in that case.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMarkupParseContext</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref</title><informalexample><programlisting>(define-values (%return) (markup-parse-context:ref self))
</programlisting></informalexample><para>Increases the reference count of <parameter>context</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMarkupParseContext</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (markup-parse-context:unref self))
</programlisting></informalexample><para>Decreases the reference count of <parameter>context</parameter>.  When its reference count
drops to 0, it is freed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMarkupParseContext</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibMarkupParseFlags&gt;</refname></refnamediv><refsect1><title>Description</title><para>Flags that affect the behaviour of the parser.</para></refsect1><refsect1><title>Members</title><refsect2><title>do-not-use-this-unsupported-flag</title><remark>alias <code>G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG</code></remark><para>flag you should not use</para></refsect2><refsect2><title>treat-cdata-as-text</title><remark>alias <code>G_MARKUP_TREAT_CDATA_AS_TEXT</code></remark><para>When this flag is set, CDATA marked
    sections are not passed literally to the <parameter>passthrough</parameter> function of
    the parser. Instead, the content of the section (without the
    <code>&lt;![CDATA[</code> and <code>]]&gt;</code>) is
    passed to the <parameter>text</parameter> function. This flag was added in GLib 2.12</para></refsect2><refsect2><title>prefix-error-position</title><remark>alias <code>G_MARKUP_PREFIX_ERROR_POSITION</code></remark><para>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
    <type>GMarkupParser</type> implementation functions</para></refsect2><refsect2><title>ignore-qualified</title><remark>alias <code>G_MARKUP_IGNORE_QUALIFIED</code></remark><para>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.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GMatchInfo&gt;</refname></refnamediv><refsect1><title>Description</title><para>A GMatchInfo is an opaque struct used to return information about
matches.</para></refsect1><refsect1><title>Functions</title><refsect2><title>expand-references</title><informalexample><programlisting>(define-values (%return) (match-info:expand-references self string-to-expand))
</programlisting></informalexample><para>Returns a new string containing the text in <parameter>string_to_expand</parameter> with
references and escape sequences expanded. References refer to the last
match done with <parameter>string</parameter> against <parameter>regex</parameter> and have the same syntax used by
<function>g_regex_replace()</function>.
</para>
<para>The <parameter>string_to_expand</parameter> must be UTF-8 encoded even if <type>G_REGEX_RAW</type> was
passed to <function>g_regex_new()</function>.
</para>
<para>The backreferences are extracted from the string passed to the match
function, so you cannot call this function after freeing the string.
</para>
<para><parameter>match_info</parameter> may be <constant>NULL</constant> in which case <parameter>string_to_expand</parameter> must not
contain references. For instance &quot;foo\n&quot; does not refer to an actual
pattern and '\n' merely will be replaced with \n character,
while to expand &quot;\0&quot; (whole match) one needs the result of a match.
Use <function>g_regex_check_replacement()</function> to find out whether <parameter>string_to_expand</parameter>
contains references.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para>a <type>GMatchInfo</type> or <constant>NULL</constant></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>string_to_expand</para></td><td class="parameter_description"><para>the string to expand</para><para>Passed as <code>string-to-expand</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>fetch</title><informalexample><programlisting>(define-values (%return) (match-info:fetch self match-num))
</programlisting></informalexample><para>Retrieves the text matching the <parameter>match_num</parameter>'th capturing
parentheses. 0 is the full text of the match, 1 is the first paren
set, 2 the second, and so on.
</para>
<para>If <parameter>match_num</parameter> is a valid sub pattern but it didn't match anything
(e.g. sub pattern 1, matching &quot;b&quot; against &quot;(a)?b&quot;) then an empty
string is returned.
</para>
<para>If the match was obtained using the DFA algorithm, that is using
<function>g_regex_match_all()</function> or <function>g_regex_match_all_full()</function>, 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.
</para>
<para>The string is fetched from the string passed to the match function,
so you cannot call this function after freeing the string.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para><type>GMatchInfo</type> structure</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>match_num</para></td><td class="parameter_description"><para>number of the sub expression</para><para>Passed as <code>match-num</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>fetch-all</title><informalexample><programlisting>(define-values (%return) (match-info:fetch-all self))
</programlisting></informalexample><para>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.
</para>
<para>If a sub pattern didn't match anything (e.g. sub pattern 1, matching
&quot;b&quot; against &quot;(a)?b&quot;) then an empty string is inserted.
</para>
<para>If the last match was obtained using the DFA algorithm, that is using
<function>g_regex_match_all()</function> or <function>g_regex_match_all_full()</function>, 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.
</para>
<para>The strings are fetched from the string passed to the match function,
so you cannot call this function after freeing the string.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para>a <type>GMatchInfo</type> structure</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>fetch-named</title><informalexample><programlisting>(define-values (%return) (match-info:fetch-named self name))
</programlisting></informalexample><para>Retrieves the text matching the capturing parentheses named <parameter>name</parameter>.
</para>
<para>If <parameter>name</parameter> is a valid sub pattern name but it didn't match anything
(e.g. sub pattern &quot;X&quot;, matching &quot;b&quot; against &quot;(?P&lt;X&gt;a)?b&quot;)
then an empty string is returned.
</para>
<para>The string is fetched from the string passed to the match function,
so you cannot call this function after freeing the string.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para><type>GMatchInfo</type> structure</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>name</para></td><td class="parameter_description"><para>name of the subexpression</para><para>Passed as <code>name</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>fetch-named-pos</title><informalexample><programlisting>(define-values
  (%return start-pos end-pos)
  (match-info:fetch-named-pos self name))
</programlisting></informalexample><para>Retrieves the position in bytes of the capturing parentheses named <parameter>name</parameter>.
</para>
<para>If <parameter>name</parameter> is a valid sub pattern name but it didn't match anything
(e.g. sub pattern &quot;X&quot;, matching &quot;b&quot; against &quot;(?P&lt;X&gt;a)?b&quot;)
then <parameter>start_pos</parameter> and <parameter>end_pos</parameter> are set to -1 and <constant>TRUE</constant> is returned.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para><type>GMatchInfo</type> structure</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>name</para></td><td class="parameter_description"><para>name of the subexpression</para><para>Passed as <code>name</code></para></td></tr><tr><td class="parameter_name"><para>start_pos</para></td><td class="parameter_description"><para>pointer to location where to store
    the start position, or <constant>NULL</constant></para><para>Passed as <code>start-pos</code></para></td></tr><tr><td class="parameter_name"><para>end_pos</para></td><td class="parameter_description"><para>pointer to location where to store
    the end position, or <constant>NULL</constant></para><para>Passed as <code>end-pos</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>fetch-pos</title><informalexample><programlisting>(define-values
  (%return start-pos end-pos)
  (match-info:fetch-pos self match-num))
</programlisting></informalexample><para>Retrieves the position in bytes of the <parameter>match_num</parameter>'th capturing
parentheses. 0 is the full text of the match, 1 is the first
paren set, 2 the second, and so on.
</para>
<para>If <parameter>match_num</parameter> is a valid sub pattern but it didn't match anything
(e.g. sub pattern 1, matching &quot;b&quot; against &quot;(a)?b&quot;) then <parameter>start_pos</parameter>
and <parameter>end_pos</parameter> are set to -1 and <constant>TRUE</constant> is returned.
</para>
<para>If the match was obtained using the DFA algorithm, that is using
<function>g_regex_match_all()</function> or <function>g_regex_match_all_full()</function>, 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para><type>GMatchInfo</type> structure</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>match_num</para></td><td class="parameter_description"><para>number of the sub expression</para><para>Passed as <code>match-num</code></para></td></tr><tr><td class="parameter_name"><para>start_pos</para></td><td class="parameter_description"><para>pointer to location where to store
    the start position, or <constant>NULL</constant></para><para>Passed as <code>start-pos</code></para></td></tr><tr><td class="parameter_name"><para>end_pos</para></td><td class="parameter_description"><para>pointer to location where to store
    the end position, or <constant>NULL</constant></para><para>Passed as <code>end-pos</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>free</title><informalexample><programlisting>(define-values () (match-info:free self))
</programlisting></informalexample><para>If <parameter>match_info</parameter> is not <constant>NULL</constant>, calls <function>g_match_info_unref()</function>; otherwise does
nothing.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para>a <type>GMatchInfo</type>, or <constant>NULL</constant></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-match-count</title><informalexample><programlisting>(define-values (%return) (match-info:get-match-count self))
</programlisting></informalexample><para>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.
</para>
<para>If the last match was obtained using the DFA algorithm, that is
using <function>g_regex_match_all()</function> or <function>g_regex_match_all_full()</function>, the retrieved
count is not that of the number of capturing parentheses but that of
the number of matched substrings.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para>a <type>GMatchInfo</type> structure</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-regex</title><informalexample><programlisting>(define-values (%return) (match-info:get-regex self))
</programlisting></informalexample><para>Returns <type>GRegex</type> object used in <parameter>match_info</parameter>. It belongs to Glib
and must not be freed. Use <function>g_regex_ref()</function> if you need to keep it
after you free <parameter>match_info</parameter> object.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para>a <type>GMatchInfo</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-string</title><informalexample><programlisting>(define-values (%return) (match-info:get-string self))
</programlisting></informalexample><para>Returns the string searched with <parameter>match_info</parameter>. This is the
string passed to <function>g_regex_match()</function> or <function>g_regex_replace()</function> so
you may not free it before calling this function.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para>a <type>GMatchInfo</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-partial-match?</title><informalexample><programlisting>(define-values (%return) (match-info:is-partial-match? self))
</programlisting></informalexample><para>Usually if the string passed to g_regex_match*() matches as far as
it goes, but is too short to match the entire pattern, <constant>FALSE</constant> is
returned. There are circumstances where it might be helpful to
distinguish this case from other cases in which there is no match.
</para>
<para>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
&quot;^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$&quot;.
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.
</para>
<para>GRegex supports the concept of partial matching by means of the
<type>G_REGEX_MATCH_PARTIAL_SOFT</type> and <type>G_REGEX_MATCH_PARTIAL_HARD</type> flags.
When they are used, the return code for
<function>g_regex_match()</function> or <function>g_regex_match_full()</function> is, as usual, <constant>TRUE</constant>
for a complete match, <constant>FALSE</constant> otherwise. But, when these functions
return <constant>FALSE</constant>, you can check if the match was partial calling
<function>g_match_info_is_partial_match()</function>.
</para>
<para>The difference between <type>G_REGEX_MATCH_PARTIAL_SOFT</type> and
<type>G_REGEX_MATCH_PARTIAL_HARD</type> is that when a partial match is encountered
with <type>G_REGEX_MATCH_PARTIAL_SOFT</type>, matching continues to search for a
possible complete match, while with <type>G_REGEX_MATCH_PARTIAL_HARD</type> matching
stops at the partial match.
When both <type>G_REGEX_MATCH_PARTIAL_SOFT</type> and <type>G_REGEX_MATCH_PARTIAL_HARD</type>
are set, the latter takes precedence.
</para>
<para>There were formerly some restrictions on the pattern for partial matching.
The restrictions no longer apply.
</para>
<para>See pcrepartial(3) for more information on partial matching.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para>a <type>GMatchInfo</type> structure</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>matches?</title><informalexample><programlisting>(define-values (%return) (match-info:matches? self))
</programlisting></informalexample><para>Returns whether the previous match operation succeeded.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para>a <type>GMatchInfo</type> structure</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>next?</title><informalexample><programlisting>(define-values (%return) (match-info:next? self))
</programlisting></informalexample><para>Scans for the next match using the same parameters of the previous
call to <function>g_regex_match_full()</function> or <function>g_regex_match()</function> that returned
<parameter>match_info</parameter>.
</para>
<para>The match is done on the string passed to the match function, so you
cannot free it before calling this function.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para>a <type>GMatchInfo</type> structure</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref</title><informalexample><programlisting>(define-values (%return) (match-info:ref self))
</programlisting></informalexample><para>Increases reference count of <parameter>match_info</parameter> by 1.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para>a <type>GMatchInfo</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (match-info:unref self))
</programlisting></informalexample><para>Decreases reference count of <parameter>match_info</parameter> by 1. When reference count drops
to zero, it frees all the memory associated with the match_info structure.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para>a <type>GMatchInfo</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibNormalizeMode&gt;</refname></refnamediv><refsect1><title>Description</title><para>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.</para></refsect1><refsect1><title>Members</title><refsect2><title>default</title><remark>alias <code>G_NORMALIZE_DEFAULT</code></remark><para>standardize differences that do not affect the
    text content, such as the above-mentioned accent representation</para></refsect2><refsect2><title>nfd</title><remark>alias <code>G_NORMALIZE_NFD</code></remark><para>another name for <constant>G_NORMALIZE_DEFAULT</constant></para></refsect2><refsect2><title>default-compose</title><remark>alias <code>G_NORMALIZE_DEFAULT_COMPOSE</code></remark><para>like <constant>G_NORMALIZE_DEFAULT</constant>, but with
    composed forms rather than a maximally decomposed form</para></refsect2><refsect2><title>nfc</title><remark>alias <code>G_NORMALIZE_NFC</code></remark><para>another name for <constant>G_NORMALIZE_DEFAULT_COMPOSE</constant></para></refsect2><refsect2><title>all</title><remark>alias <code>G_NORMALIZE_ALL</code></remark><para>beyond <constant>G_NORMALIZE_DEFAULT</constant> also standardize the
    &quot;compatibility&quot; 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</para></refsect2><refsect2><title>nfkd</title><remark>alias <code>G_NORMALIZE_NFKD</code></remark><para>another name for <constant>G_NORMALIZE_ALL</constant></para></refsect2><refsect2><title>all-compose</title><remark>alias <code>G_NORMALIZE_ALL_COMPOSE</code></remark><para>like <constant>G_NORMALIZE_ALL</constant>, but with composed
    forms rather than a maximally decomposed form</para></refsect2><refsect2><title>nfkc</title><remark>alias <code>G_NORMALIZE_NFKC</code></remark><para>another name for <constant>G_NORMALIZE_ALL_COMPOSE</constant></para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibNumberParserError&gt;</refname></refnamediv><refsect1><title>Description</title><para>Error codes returned by functions converting a string to a number.</para></refsect1><refsect1><title>Members</title><refsect2><title>invalid</title><remark>alias <code>G_NUMBER_PARSER_ERROR_INVALID</code></remark><para>String was not a valid number.</para></refsect2><refsect2><title>out-of-bounds</title><remark>alias <code>G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS</code></remark><para>String was a number, but out of bounds.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibOnceStatus&gt;</refname></refnamediv><refsect1><title>Description</title><para>The possible statuses of a one-time initialization function
controlled by a <type>GOnce</type> struct.</para></refsect1><refsect1><title>Members</title><refsect2><title>notcalled</title><remark>alias <code>G_ONCE_STATUS_NOTCALLED</code></remark><para>the function has not been called yet.</para></refsect2><refsect2><title>progress</title><remark>alias <code>G_ONCE_STATUS_PROGRESS</code></remark><para>the function call is currently in progress.</para></refsect2><refsect2><title>ready</title><remark>alias <code>G_ONCE_STATUS_READY</code></remark><para>the function has been called.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibOptionArg&gt;</refname></refnamediv><refsect1><title>Description</title><para>The <type>GOptionArg</type> 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: <code>-x arg</code>, with a long
option: <code>--name arg</code> or combined in a single argument: <code>--name=arg</code>.</para></refsect1><refsect1><title>Members</title><refsect2><title>none</title><remark>alias <code>G_OPTION_ARG_NONE</code></remark><para>No extra argument. This is useful for simple flags.</para></refsect2><refsect2><title>string</title><remark>alias <code>G_OPTION_ARG_STRING</code></remark><para>The option takes a UTF-8 string argument.</para></refsect2><refsect2><title>int</title><remark>alias <code>G_OPTION_ARG_INT</code></remark><para>The option takes an integer argument.</para></refsect2><refsect2><title>callback</title><remark>alias <code>G_OPTION_ARG_CALLBACK</code></remark><para>The option provides a callback (of type
    <type>GOptionArgFunc</type>) to parse the extra argument.</para></refsect2><refsect2><title>filename</title><remark>alias <code>G_OPTION_ARG_FILENAME</code></remark><para>The option takes a filename as argument, which will
       be in the GLib filename encoding rather than UTF-8.</para></refsect2><refsect2><title>string-array</title><remark>alias <code>G_OPTION_ARG_STRING_ARRAY</code></remark><para>The option takes a string argument, multiple
    uses of the option are collected into an array of strings.</para></refsect2><refsect2><title>filename-array</title><remark>alias <code>G_OPTION_ARG_FILENAME_ARRAY</code></remark><para>The option takes a filename as argument,
    multiple uses of the option are collected into an array of strings.</para></refsect2><refsect2><title>double</title><remark>alias <code>G_OPTION_ARG_DOUBLE</code></remark><para>The option takes a double argument. The argument
    can be formatted either for the user's locale or for the &quot;C&quot; locale.
    Since 2.12</para></refsect2><refsect2><title>int64</title><remark>alias <code>G_OPTION_ARG_INT64</code></remark><para>The option takes a 64-bit integer. Like
    <constant>G_OPTION_ARG_INT</constant> but for larger numbers. The number can be in
    decimal base, or in hexadecimal (when prefixed with <code>0x</code>, for
    example, <code>0xffffffff</code>). Since 2.12</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibOptionError&gt;</refname></refnamediv><refsect1><title>Description</title><para>Error codes returned by option parsing.</para></refsect1><refsect1><title>Members</title><refsect2><title>unknown-option</title><remark>alias <code>G_OPTION_ERROR_UNKNOWN_OPTION</code></remark><para>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 <function>g_option_context_set_ignore_unknown_options()</function>.</para></refsect2><refsect2><title>bad-value</title><remark>alias <code>G_OPTION_ERROR_BAD_VALUE</code></remark><para>A value couldn't be parsed.</para></refsect2><refsect2><title>failed</title><remark>alias <code>G_OPTION_ERROR_FAILED</code></remark><para>A <type>GOptionArgFunc</type> callback failed.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibOptionFlags&gt;</refname></refnamediv><refsect1><title>Description</title><para>Flags which modify individual options.</para></refsect1><refsect1><title>Members</title><refsect2><title>none</title><remark>alias <code>G_OPTION_FLAG_NONE</code></remark><para>No flags. Since: 2.42.</para></refsect2><refsect2><title>hidden</title><remark>alias <code>G_OPTION_FLAG_HIDDEN</code></remark><para>The option doesn't appear in <code>--help</code> output.</para></refsect2><refsect2><title>in-main</title><remark>alias <code>G_OPTION_FLAG_IN_MAIN</code></remark><para>The option appears in the main section of the
    <code>--help</code> output, even if it is defined in a group.</para></refsect2><refsect2><title>reverse</title><remark>alias <code>G_OPTION_FLAG_REVERSE</code></remark><para>For options of the <constant>G_OPTION_ARG_NONE</constant> kind, this
    flag indicates that the sense of the option is reversed.</para></refsect2><refsect2><title>no-arg</title><remark>alias <code>G_OPTION_FLAG_NO_ARG</code></remark><para>For options of the <constant>G_OPTION_ARG_CALLBACK</constant> kind,
    this flag indicates that the callback does not take any argument
    (like a <constant>G_OPTION_ARG_NONE</constant> option). Since 2.8</para></refsect2><refsect2><title>filename</title><remark>alias <code>G_OPTION_FLAG_FILENAME</code></remark><para>For options of the <constant>G_OPTION_ARG_CALLBACK</constant>
    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</para></refsect2><refsect2><title>optional-arg</title><remark>alias <code>G_OPTION_FLAG_OPTIONAL_ARG</code></remark><para>For options of the <constant>G_OPTION_ARG_CALLBACK</constant>
    kind, this flag indicates that the argument supply is optional.
    If no argument is given then data of <constant>GOptionParseFunc</constant> will be
    set to NULL. Since 2.8</para></refsect2><refsect2><title>noalias</title><remark>alias <code>G_OPTION_FLAG_NOALIAS</code></remark><para>This flag turns off the automatic conflict
    resolution which prefixes long option names with <code>groupname-</code> 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.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GOptionGroup&gt;</refname></refnamediv><refsect1><title>Description</title><para>A <code>GOptionGroup</code> struct defines the options in a single
group. The struct has only private fields and should not be directly accessed.
</para>
<para>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 <code>GOptionGroup</code> holding their options, which
the application can then add to its <type>GOptionContext</type>.</para></refsect1><refsect1><title>Functions</title><refsect2><title>free</title><informalexample><programlisting>(define-values () (option-group:free self))
</programlisting></informalexample><para>Frees a <type>GOptionGroup</type>. Note that you must not free groups
which have been added to a <type>GOptionContext</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>group</para></td><td class="parameter_description"><para>a <type>GOptionGroup</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref</title><informalexample><programlisting>(define-values (%return) (option-group:ref self))
</programlisting></informalexample><para>Increments the reference count of <parameter>group</parameter> by one.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>group</para></td><td class="parameter_description"><para>a <type>GOptionGroup</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-translate-func</title><informalexample><programlisting>(define-values
  ()
  (option-group:set-translate-func self func data destroy-notify))
</programlisting></informalexample><para>Sets the function which is used to translate user-visible strings,
for <code>--help</code> output. Different groups can use different
<type>GTranslateFuncs</type>. If <parameter>func</parameter> is <constant>NULL</constant>, strings are not translated.
</para>
<para>If you are using <function>gettext()</function>, you only need to set the translation
domain, see <function>g_option_group_set_translation_domain()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>group</para></td><td class="parameter_description"><para>a <type>GOptionGroup</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>func</para></td><td class="parameter_description"><para>the <type>GTranslateFunc</type>, or <constant>NULL</constant></para><para>Passed as <code>func</code></para></td></tr><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>user data to pass to <parameter>func</parameter>, or <constant>NULL</constant></para><para>Passed as <code>data</code></para></td></tr><tr><td class="parameter_name"><para>destroy_notify</para></td><td class="parameter_description"><para>a function which gets called to free <parameter>data</parameter>, or <constant>NULL</constant></para><para>Passed as <code>destroy-notify</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-translation-domain</title><informalexample><programlisting>(define-values () (option-group:set-translation-domain self domain))
</programlisting></informalexample><para>A convenience function to use <function>gettext()</function> for translating
user-visible strings.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>group</para></td><td class="parameter_description"><para>a <type>GOptionGroup</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>domain</para></td><td class="parameter_description"><para>the domain to use</para><para>Passed as <code>domain</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (option-group:unref self))
</programlisting></informalexample><para>Decrements the reference count of <parameter>group</parameter> by one.
If the reference count drops to 0, the <parameter>group</parameter> will be freed.
and all memory allocated by the <parameter>group</parameter> is released.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>group</para></td><td class="parameter_description"><para>a <type>GOptionGroup</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>option-group:new</title><informalexample><programlisting>(define-values
  (%return)
  (option-group:new name description help-description user-data destroy))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>name</para></td><td class="parameter_description"><para></para><para>Passed as <code>name</code></para></td></tr><tr><td class="parameter_name"><para>description</para></td><td class="parameter_description"><para></para><para>Passed as <code>description</code></para></td></tr><tr><td class="parameter_name"><para>help_description</para></td><td class="parameter_description"><para></para><para>Passed as <code>help-description</code></para></td></tr><tr><td class="parameter_name"><para>user_data</para></td><td class="parameter_description"><para></para><para>Passed as <code>user-data</code></para></td></tr><tr><td class="parameter_name"><para>destroy</para></td><td class="parameter_description"><para></para><para>Passed as <code>destroy</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GPatternSpec&gt;</refname></refnamediv><refsect1><title>Description</title><para>A GPatternSpec struct is the 'compiled' form of a pattern. This
structure is opaque and its fields cannot be accessed directly.</para></refsect1><refsect1><title>Functions</title><refsect2><title>copy</title><informalexample><programlisting>(define-values (%return) (pattern-spec:copy self))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>pspec</para></td><td class="parameter_description"><para></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>equal?</title><informalexample><programlisting>(define-values (%return) (pattern-spec:equal? self pspec2))
</programlisting></informalexample><para>Compares two compiled pattern specs and returns whether they will
match the same set of strings.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>pspec1</para></td><td class="parameter_description"><para>a <type>GPatternSpec</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>pspec2</para></td><td class="parameter_description"><para>another <type>GPatternSpec</type></para><para>Passed as <code>pspec2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>free</title><informalexample><programlisting>(define-values () (pattern-spec:free self))
</programlisting></informalexample><para>Frees the memory allocated for the <type>GPatternSpec</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>pspec</para></td><td class="parameter_description"><para>a <type>GPatternSpec</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>match?</title><informalexample><programlisting>(define-values
  (%return)
  (pattern-spec:match? self string-length string string-reversed))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>pspec</para></td><td class="parameter_description"><para></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>string_length</para></td><td class="parameter_description"><para></para><para>Passed as <code>string-length</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para></para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>string_reversed</para></td><td class="parameter_description"><para></para><para>Passed as <code>string-reversed</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>match-string?</title><informalexample><programlisting>(define-values (%return) (pattern-spec:match-string? self string))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>pspec</para></td><td class="parameter_description"><para></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para></para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>pattern-spec:new</title><informalexample><programlisting>(define-values (%return) (pattern-spec:new pattern))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>pattern</para></td><td class="parameter_description"><para></para><para>Passed as <code>pattern</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GPollFD&gt;</refname></refnamediv><refsect1><title>Description</title><para>Represents a file descriptor, which events to poll for, and which events
occurred.</para></refsect1></refentry><refentry><refnamediv><refname>&lt;GPtrArray&gt;</refname></refnamediv><refsect1><title>Description</title><para>Contains the public fields of a pointer array.</para></refsect1></refentry><refentry><refnamediv><refname>&lt;GRegex&gt;</refname></refnamediv><refsect1><title>Description</title><para>The g_regex_*() functions implement regular
expression pattern matching using syntax and semantics similar to
Perl regular expression.
</para>
<para>Some functions accept a <parameter>start_position</parameter> argument, setting it differs
from just passing over a shortened string and setting <type>G_REGEX_MATCH_NOTBOL</type>
in the case of a pattern that begins with any kind of lookbehind assertion.
For example, consider the pattern &quot;\Biss\B&quot; which finds occurrences of &quot;iss&quot;
in the middle of words. (&quot;\B&quot; matches only if the current position in the
subject is not a word boundary.) When applied to the string &quot;Mississipi&quot;
from the fourth byte, namely &quot;issipi&quot;, it does not match, because &quot;\B&quot; 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
<parameter>start_position</parameter> set to 4, it finds the second occurrence of &quot;iss&quot; because
it is able to look behind the starting point to discover that it is
preceded by a letter.
</para>
<para>Note that, unless you set the <type>G_REGEX_RAW</type> 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,
&quot;\xc3\xa0&quot; (i.e. &quot;à&quot;) is two bytes long but it is treated as a
single character. If you set <type>G_REGEX_RAW</type> the strings can be non-valid
UTF-8 strings and a byte is treated as a character, so &quot;\xc3\xa0&quot; is two
bytes and two characters long.
</para>
<para>When matching a pattern, &quot;\n&quot; matches only against a &quot;\n&quot; character in
the string, and &quot;\r&quot; matches only a &quot;\r&quot; character. To match any newline
sequence use &quot;\R&quot;. This particular group matches either the two-character
sequence CR + LF (&quot;\r\n&quot;), or one of the single characters LF (linefeed,
U+000A, &quot;\n&quot;), VT vertical tab, U+000B, &quot;\v&quot;), FF (formfeed, U+000C, &quot;\f&quot;),
CR (carriage return, U+000D, &quot;\r&quot;), NEL (next line, U+0085), LS (line
separator, U+2028), or PS (paragraph separator, U+2029).
</para>
<para>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 &quot;\R&quot;). This can be changed
with <type>G_REGEX_NEWLINE_CR</type>, <type>G_REGEX_NEWLINE_LF</type> and <type>G_REGEX_NEWLINE_CRLF</type>
compile options, and with <type>G_REGEX_MATCH_NEWLINE_ANY</type>,
<type>G_REGEX_MATCH_NEWLINE_CR</type>, <type>G_REGEX_MATCH_NEWLINE_LF</type> and
<type>G_REGEX_MATCH_NEWLINE_CRLF</type> match options. These settings are also
relevant when compiling a pattern if <type>G_REGEX_EXTENDED</type> is set, and an
unescaped &quot;#&quot; outside a character class is encountered. This indicates
a comment that lasts until after the next newline.
</para>
<para>When setting the <constant>G_REGEX_JAVASCRIPT_COMPAT</constant> 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.
</para>
<para>Creating and manipulating the same <type>GRegex</type> structure from different
threads is not a problem as <type>GRegex</type> does not modify its internal
state between creation and destruction, on the other hand <type>GMatchInfo</type>
is not threadsafe.
</para>
<para>The regular expressions low-level functionalities are obtained through
the excellent
[PCRE](http://www.pcre.org/)
library written by Philip Hazel.</para></refsect1><refsect1><title>Functions</title><refsect2><title>get-capture-count</title><informalexample><programlisting>(define-values (%return) (regex:get-capture-count self))
</programlisting></informalexample><para>Returns the number of capturing subpatterns in the pattern.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para>a <type>GRegex</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-compile-flags</title><informalexample><programlisting>(define-values (%return) (regex:get-compile-flags self))
</programlisting></informalexample><para>Returns the compile options that <parameter>regex</parameter> was created with.
</para>
<para>Depending on the version of PCRE that is used, this may or may not
include flags set by option expressions such as <code>(?i)</code> found at the
top-level within the compiled pattern.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para>a <type>GRegex</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-has-cr-or-lf?</title><informalexample><programlisting>(define-values (%return) (regex:get-has-cr-or-lf? self))
</programlisting></informalexample><para>Checks whether the pattern contains explicit CR or LF references.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para>a <type>GRegex</type> structure</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-match-flags</title><informalexample><programlisting>(define-values (%return) (regex:get-match-flags self))
</programlisting></informalexample><para>Returns the match options that <parameter>regex</parameter> was created with.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para>a <type>GRegex</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-max-backref</title><informalexample><programlisting>(define-values (%return) (regex:get-max-backref self))
</programlisting></informalexample><para>Returns the number of the highest back reference
in the pattern, or 0 if the pattern does not contain
back references.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para>a <type>GRegex</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-max-lookbehind</title><informalexample><programlisting>(define-values (%return) (regex:get-max-lookbehind self))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para>a <type>GRegex</type> structure</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-pattern</title><informalexample><programlisting>(define-values (%return) (regex:get-pattern self))
</programlisting></informalexample><para>Gets the pattern string associated with <parameter>regex</parameter>, i.e. a copy of
the string passed to <function>g_regex_new()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para>a <type>GRegex</type> structure</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-string-number</title><informalexample><programlisting>(define-values (%return) (regex:get-string-number self name))
</programlisting></informalexample><para>Retrieves the number of the subexpression named <parameter>name</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para><type>GRegex</type> structure</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>name</para></td><td class="parameter_description"><para>name of the subexpression</para><para>Passed as <code>name</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>match</title><informalexample><programlisting>(define-values (%return match-info) (regex:match self string match-options))
</programlisting></informalexample><para>Scans for a match in <parameter>string</parameter> for the pattern in <parameter>regex</parameter>.
The <parameter>match_options</parameter> are combined with the match options specified
when the <parameter>regex</parameter> structure was created, letting you have more
flexibility in reusing <type>GRegex</type> structures.
</para>
<para>Unless <constant>G_REGEX_RAW</constant> is specified in the options, <parameter>string</parameter> must be valid UTF-8.
</para>
<para>A <type>GMatchInfo</type> structure, used to get information on the match,
is stored in <parameter>match_info</parameter> if not <constant>NULL</constant>. Note that if <parameter>match_info</parameter>
is not <constant>NULL</constant> then it is created even if the function returns <constant>FALSE</constant>,
i.e. you must free it regardless if regular expression actually matched.
</para>
<para>To retrieve all the non-overlapping matches of the pattern in
string you can use <function>g_match_info_next()</function>.
</para>
<para><informalexample><programlisting>
static void
print_uppercase_words (const gchar *string)
{
  // Print all uppercase-only words.
  GRegex *regex;
  GMatchInfo *match_info;
 
  regex = g_regex_new (&quot;[A-Z]+&quot;, 0, 0, NULL);
  g_regex_match (regex, string, 0, &amp;match_info);
  while (g_match_info_matches (match_info))
    {
      gchar *word = g_match_info_fetch (match_info, 0);
      g_print (&quot;Found: %s\n&quot;, word);
      g_free (word);
      g_match_info_next (match_info, NULL);
    }
  g_match_info_free (match_info);
  g_regex_unref (regex);
}
</programlisting></informalexample></para>

<para><parameter>string</parameter> is not copied and is used in <type>GMatchInfo</type> internally. If
you use any <type>GMatchInfo</type> method (except <function>g_match_info_free()</function>) after
freeing or modifying <parameter>string</parameter> then the behaviour is undefined.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para>a <type>GRegex</type> structure from <function>g_regex_new()</function></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to scan for matches</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>match_options</para></td><td class="parameter_description"><para>match options</para><para>Passed as <code>match-options</code></para></td></tr><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para>pointer to location where to store
    the <type>GMatchInfo</type>, or <constant>NULL</constant> if you do not need it</para><para>Passed as <code>match-info</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>match-all</title><informalexample><programlisting>(define-values
  (%return match-info)
  (regex:match-all self string match-options))
</programlisting></informalexample><para>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 <function>g_regex_match_all_full()</function>.
</para>
<para>A <type>GMatchInfo</type> structure, used to get information on the match, is
stored in <parameter>match_info</parameter> if not <constant>NULL</constant>. Note that if <parameter>match_info</parameter> is
not <constant>NULL</constant> then it is created even if the function returns <constant>FALSE</constant>,
i.e. you must free it regardless if regular expression actually
matched.
</para>
<para><parameter>string</parameter> is not copied and is used in <type>GMatchInfo</type> internally. If
you use any <type>GMatchInfo</type> method (except <function>g_match_info_free()</function>) after
freeing or modifying <parameter>string</parameter> then the behaviour is undefined.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para>a <type>GRegex</type> structure from <function>g_regex_new()</function></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to scan for matches</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>match_options</para></td><td class="parameter_description"><para>match options</para><para>Passed as <code>match-options</code></para></td></tr><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para>pointer to location where to store
    the <type>GMatchInfo</type>, or <constant>NULL</constant> if you do not need it</para><para>Passed as <code>match-info</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>match-all-full</title><informalexample><programlisting>(define-values
  (%return match-info)
  (regex:match-all-full self string start-position match-options))
</programlisting></informalexample><para>Using the standard algorithm for regular expression matching only
the longest match in the <parameter>string</parameter> is retrieved, it is not possible
to obtain all the available matches. For instance matching
&quot;&lt;a&gt; &lt;b&gt; &lt;c&gt;&quot; against the pattern &quot;&lt;.*&gt;&quot;
you get &quot;&lt;a&gt; &lt;b&gt; &lt;c&gt;&quot;.
</para>
<para>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
&quot;&lt;a&gt; &lt;b&gt; &lt;c&gt;&quot; against the pattern &quot;&lt;.*&gt;;&quot;
you would obtain three matches: &quot;&lt;a&gt; &lt;b&gt; &lt;c&gt;&quot;,
&quot;&lt;a&gt; &lt;b&gt;&quot; and &quot;&lt;a&gt;&quot;.
</para>
<para>The number of matched strings is retrieved using
<function>g_match_info_get_match_count()</function>. To obtain the matched strings and
their position you can use, respectively, <function>g_match_info_fetch()</function> and
<function>g_match_info_fetch_pos()</function>. Note that the strings are returned in
reverse order of length; that is, the longest matching string is
given first.
</para>
<para>Note that the DFA algorithm is slower than the standard one and it
is not able to capture substrings, so backreferences do not work.
</para>
<para>Setting <parameter>start_position</parameter> differs from just passing over a shortened
string and setting <type>G_REGEX_MATCH_NOTBOL</type> in the case of a pattern
that begins with any kind of lookbehind assertion, such as &quot;\b&quot;.
</para>
<para>Unless <constant>G_REGEX_RAW</constant> is specified in the options, <parameter>string</parameter> must be valid UTF-8.
</para>
<para>A <type>GMatchInfo</type> structure, used to get information on the match, is
stored in <parameter>match_info</parameter> if not <constant>NULL</constant>. Note that if <parameter>match_info</parameter> is
not <constant>NULL</constant> then it is created even if the function returns <constant>FALSE</constant>,
i.e. you must free it regardless if regular expression actually
matched.
</para>
<para><parameter>string</parameter> is not copied and is used in <type>GMatchInfo</type> internally. If
you use any <type>GMatchInfo</type> method (except <function>g_match_info_free()</function>) after
freeing or modifying <parameter>string</parameter> then the behaviour is undefined.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para>a <type>GRegex</type> structure from <function>g_regex_new()</function></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to scan for matches</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>string_len</para></td><td class="parameter_description"><para>the length of <parameter>string</parameter>, in bytes, or -1 if <parameter>string</parameter> is nul-terminated</para><para>Inferred from <code>string</code></para></td></tr><tr><td class="parameter_name"><para>start_position</para></td><td class="parameter_description"><para>starting index of the string to match, in bytes</para><para>Passed as <code>start-position</code></para></td></tr><tr><td class="parameter_name"><para>match_options</para></td><td class="parameter_description"><para>match options</para><para>Passed as <code>match-options</code></para></td></tr><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para>pointer to location where to store
    the <type>GMatchInfo</type>, or <constant>NULL</constant> if you do not need it</para><para>Passed as <code>match-info</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>match-full</title><informalexample><programlisting>(define-values
  (%return match-info)
  (regex:match-full self string start-position match-options))
</programlisting></informalexample><para>Scans for a match in <parameter>string</parameter> for the pattern in <parameter>regex</parameter>.
The <parameter>match_options</parameter> are combined with the match options specified
when the <parameter>regex</parameter> structure was created, letting you have more
flexibility in reusing <type>GRegex</type> structures.
</para>
<para>Setting <parameter>start_position</parameter> differs from just passing over a shortened
string and setting <type>G_REGEX_MATCH_NOTBOL</type> in the case of a pattern
that begins with any kind of lookbehind assertion, such as &quot;\b&quot;.
</para>
<para>Unless <constant>G_REGEX_RAW</constant> is specified in the options, <parameter>string</parameter> must be valid UTF-8.
</para>
<para>A <type>GMatchInfo</type> structure, used to get information on the match, is
stored in <parameter>match_info</parameter> if not <constant>NULL</constant>. Note that if <parameter>match_info</parameter> is
not <constant>NULL</constant> then it is created even if the function returns <constant>FALSE</constant>,
i.e. you must free it regardless if regular expression actually
matched.
</para>
<para><parameter>string</parameter> is not copied and is used in <type>GMatchInfo</type> internally. If
you use any <type>GMatchInfo</type> method (except <function>g_match_info_free()</function>) after
freeing or modifying <parameter>string</parameter> then the behaviour is undefined.
</para>
<para>To retrieve all the non-overlapping matches of the pattern in
string you can use <function>g_match_info_next()</function>.
</para>
<para><informalexample><programlisting>
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 (&quot;[A-Z]+&quot;, 0, 0, NULL);
  g_regex_match_full (regex, string, -1, 0, 0, &amp;match_info, &amp;error);
  while (g_match_info_matches (match_info))
    {
      gchar *word = g_match_info_fetch (match_info, 0);
      g_print (&quot;Found: %s\n&quot;, word);
      g_free (word);
      g_match_info_next (match_info, &amp;error);
    }
  g_match_info_free (match_info);
  g_regex_unref (regex);
  if (error != NULL)
    {
      g_printerr (&quot;Error while matching: %s\n&quot;, error-&gt;message);
      g_error_free (error);
    }
}
</programlisting></informalexample></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para>a <type>GRegex</type> structure from <function>g_regex_new()</function></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to scan for matches</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>string_len</para></td><td class="parameter_description"><para>the length of <parameter>string</parameter>, in bytes, or -1 if <parameter>string</parameter> is nul-terminated</para><para>Inferred from <code>string</code></para></td></tr><tr><td class="parameter_name"><para>start_position</para></td><td class="parameter_description"><para>starting index of the string to match, in bytes</para><para>Passed as <code>start-position</code></para></td></tr><tr><td class="parameter_name"><para>match_options</para></td><td class="parameter_description"><para>match options</para><para>Passed as <code>match-options</code></para></td></tr><tr><td class="parameter_name"><para>match_info</para></td><td class="parameter_description"><para>pointer to location where to store
    the <type>GMatchInfo</type>, or <constant>NULL</constant> if you do not need it</para><para>Passed as <code>match-info</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref</title><informalexample><programlisting>(define-values (%return) (regex:ref self))
</programlisting></informalexample><para>Increases reference count of <parameter>regex</parameter> by 1.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para>a <type>GRegex</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>replace</title><informalexample><programlisting>(define-values
  (%return)
  (regex:replace self string start-position replacement match-options))
</programlisting></informalexample><para>Replaces all occurrences of the pattern in <parameter>regex</parameter> with the
replacement text. Backreferences of the form '\number' or
'\g&lt;number&gt;' in the replacement text are interpolated by the
number-th captured subexpression of the match, '\g&lt;name&gt;' 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 '\\\\'.
</para>
<para>There are also escapes that changes the case of the following text:
</para>
<para>- \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
</para>
<para>If you do not need to use backreferences use <function>g_regex_replace_literal()</function>.
</para>
<para>The <parameter>replacement</parameter> string must be UTF-8 encoded even if <type>G_REGEX_RAW</type> was
passed to <function>g_regex_new()</function>. If you want to use not UTF-8 encoded strings
you can use <function>g_regex_replace_literal()</function>.
</para>
<para>Setting <parameter>start_position</parameter> differs from just passing over a shortened
string and setting <type>G_REGEX_MATCH_NOTBOL</type> in the case of a pattern that
begins with any kind of lookbehind assertion, such as &quot;\b&quot;.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para>a <type>GRegex</type> structure</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to perform matches against</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>string_len</para></td><td class="parameter_description"><para>the length of <parameter>string</parameter>, in bytes, or -1 if <parameter>string</parameter> is nul-terminated</para><para>Inferred from <code>string</code></para></td></tr><tr><td class="parameter_name"><para>start_position</para></td><td class="parameter_description"><para>starting index of the string to match, in bytes</para><para>Passed as <code>start-position</code></para></td></tr><tr><td class="parameter_name"><para>replacement</para></td><td class="parameter_description"><para>text to replace each match with</para><para>Passed as <code>replacement</code></para></td></tr><tr><td class="parameter_name"><para>match_options</para></td><td class="parameter_description"><para>options for the match</para><para>Passed as <code>match-options</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>replace-literal</title><informalexample><programlisting>(define-values
  (%return)
  (regex:replace-literal self string start-position replacement match-options))
</programlisting></informalexample><para>Replaces all occurrences of the pattern in <parameter>regex</parameter> with the
replacement text. <parameter>replacement</parameter> is replaced literally, to
include backreferences use <function>g_regex_replace()</function>.
</para>
<para>Setting <parameter>start_position</parameter> differs from just passing over a
shortened string and setting <type>G_REGEX_MATCH_NOTBOL</type> in the
case of a pattern that begins with any kind of lookbehind
assertion, such as &quot;\b&quot;.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para>a <type>GRegex</type> structure</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to perform matches against</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>string_len</para></td><td class="parameter_description"><para>the length of <parameter>string</parameter>, in bytes, or -1 if <parameter>string</parameter> is nul-terminated</para><para>Inferred from <code>string</code></para></td></tr><tr><td class="parameter_name"><para>start_position</para></td><td class="parameter_description"><para>starting index of the string to match, in bytes</para><para>Passed as <code>start-position</code></para></td></tr><tr><td class="parameter_name"><para>replacement</para></td><td class="parameter_description"><para>text to replace each match with</para><para>Passed as <code>replacement</code></para></td></tr><tr><td class="parameter_name"><para>match_options</para></td><td class="parameter_description"><para>options for the match</para><para>Passed as <code>match-options</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>split</title><informalexample><programlisting>(define-values (%return) (regex:split self string match-options))
</programlisting></informalexample><para>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.
</para>
<para>As a special case, the result of splitting the empty string &quot;&quot; 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.
</para>
<para>A pattern that can match empty strings splits <parameter>string</parameter> into separate
characters wherever it matches the empty string between characters.
For example splitting &quot;ab c&quot; using as a separator &quot;\s*&quot;, you will get
&quot;a&quot;, &quot;b&quot; and &quot;c&quot;.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para>a <type>GRegex</type> structure</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to split with the pattern</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>match_options</para></td><td class="parameter_description"><para>match time option flags</para><para>Passed as <code>match-options</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>split-full</title><informalexample><programlisting>(define-values
  (%return)
  (regex:split-full self string start-position match-options max-tokens))
</programlisting></informalexample><para>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.
</para>
<para>As a special case, the result of splitting the empty string &quot;&quot; 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.
</para>
<para>A pattern that can match empty strings splits <parameter>string</parameter> into separate
characters wherever it matches the empty string between characters.
For example splitting &quot;ab c&quot; using as a separator &quot;\s*&quot;, you will get
&quot;a&quot;, &quot;b&quot; and &quot;c&quot;.
</para>
<para>Setting <parameter>start_position</parameter> differs from just passing over a shortened
string and setting <type>G_REGEX_MATCH_NOTBOL</type> in the case of a pattern
that begins with any kind of lookbehind assertion, such as &quot;\b&quot;.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para>a <type>GRegex</type> structure</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to split with the pattern</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>string_len</para></td><td class="parameter_description"><para>the length of <parameter>string</parameter>, in bytes, or -1 if <parameter>string</parameter> is nul-terminated</para><para>Inferred from <code>string</code></para></td></tr><tr><td class="parameter_name"><para>start_position</para></td><td class="parameter_description"><para>starting index of the string to match, in bytes</para><para>Passed as <code>start-position</code></para></td></tr><tr><td class="parameter_name"><para>match_options</para></td><td class="parameter_description"><para>match time option flags</para><para>Passed as <code>match-options</code></para></td></tr><tr><td class="parameter_name"><para>max_tokens</para></td><td class="parameter_description"><para>the maximum number of tokens to split <parameter>string</parameter> into.
  If this is less than 1, the string is split completely</para><para>Passed as <code>max-tokens</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (regex:unref self))
</programlisting></informalexample><para>Decreases reference count of <parameter>regex</parameter> by 1. When reference count drops
to zero, it frees all the memory associated with the regex structure.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>regex</para></td><td class="parameter_description"><para>a <type>GRegex</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>regex:new</title><informalexample><programlisting>(define-values (%return) (regex:new pattern compile-options match-options))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>pattern</para></td><td class="parameter_description"><para></para><para>Passed as <code>pattern</code></para></td></tr><tr><td class="parameter_name"><para>compile_options</para></td><td class="parameter_description"><para></para><para>Passed as <code>compile-options</code></para></td></tr><tr><td class="parameter_name"><para>match_options</para></td><td class="parameter_description"><para></para><para>Passed as <code>match-options</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>regex:check-replacement</title><informalexample><programlisting>(define-values (%return has-references) (regex:check-replacement replacement))
</programlisting></informalexample><para>Checks whether <parameter>replacement</parameter> is a valid replacement string
(see <function>g_regex_replace()</function>), i.e. that all escape sequences in
it are valid.
</para>
<para>If <parameter>has_references</parameter> is not <constant>NULL</constant> then <parameter>replacement</parameter> 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 <type>GMatchInfo</type> object.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>replacement</para></td><td class="parameter_description"><para>the replacement string</para><para>Passed as <code>replacement</code></para></td></tr><tr><td class="parameter_name"><para>has_references</para></td><td class="parameter_description"><para>location to store information about
  references in <parameter>replacement</parameter> or <constant>NULL</constant></para><para>Passed as <code>has-references</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>regex:error-quark</title><informalexample><programlisting>(define-values (%return) (regex:error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>regex:escape-nul</title><informalexample><programlisting>(define-values (%return) (regex:escape-nul string length))
</programlisting></informalexample><para>Escapes the nul characters in <parameter>string</parameter> to &quot;\x00&quot;.  It can be used
to compile a regex with embedded nul characters.
</para>
<para>For completeness, <parameter>length</parameter> can be -1 for a nul-terminated string.
In this case the output string will be of course equal to <parameter>string</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to escape</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of <parameter>string</parameter></para><para>Passed as <code>length</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>regex:escape-string</title><informalexample><programlisting>(define-values (%return) (regex:escape-string string))
</programlisting></informalexample><para>Escapes the special characters used for regular expressions
in <parameter>string</parameter>, for instance &quot;a.b*c&quot; becomes &quot;a\.b\*c&quot;. This
function is useful to dynamically generate regular expressions.
</para>
<para><parameter>string</parameter> can contain nul characters that are replaced with &quot;\0&quot;,
in this case remember to specify the correct length of <parameter>string</parameter>
in <parameter>length</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to escape</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of <parameter>string</parameter>, in bytes, or -1 if <parameter>string</parameter> is nul-terminated</para><para>Inferred from <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>regex:match-simple?</title><informalexample><programlisting>(define-values
  (%return)
  (regex:match-simple? pattern string compile-options match-options))
</programlisting></informalexample><para>Scans for a match in <parameter>string</parameter> for <parameter>pattern</parameter>.
</para>
<para>This function is equivalent to <function>g_regex_match()</function> but it does not
require to compile the pattern with <function>g_regex_new()</function>, avoiding some
lines of code when you need just to do a match without extracting
substrings, capture counts, and so on.
</para>
<para>If this function is to be called on the same <parameter>pattern</parameter> more than
once, it's more efficient to compile the pattern once with
<function>g_regex_new()</function> and then use <function>g_regex_match()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>pattern</para></td><td class="parameter_description"><para>the regular expression</para><para>Passed as <code>pattern</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to scan for matches</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>compile_options</para></td><td class="parameter_description"><para>compile options for the regular expression, or 0</para><para>Passed as <code>compile-options</code></para></td></tr><tr><td class="parameter_name"><para>match_options</para></td><td class="parameter_description"><para>match options, or 0</para><para>Passed as <code>match-options</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>regex:split-simple</title><informalexample><programlisting>(define-values
  (%return)
  (regex:split-simple pattern string compile-options match-options))
</programlisting></informalexample><para>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.
</para>
<para>This function is equivalent to <function>g_regex_split()</function> but it does
not require to compile the pattern with <function>g_regex_new()</function>, avoiding
some lines of code when you need just to do a split without
extracting substrings, capture counts, and so on.
</para>
<para>If this function is to be called on the same <parameter>pattern</parameter> more than
once, it's more efficient to compile the pattern once with
<function>g_regex_new()</function> and then use <function>g_regex_split()</function>.
</para>
<para>As a special case, the result of splitting the empty string &quot;&quot;
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.
</para>
<para>A pattern that can match empty strings splits <parameter>string</parameter> into
separate characters wherever it matches the empty string between
characters. For example splitting &quot;ab c&quot; using as a separator
&quot;\s*&quot;, you will get &quot;a&quot;, &quot;b&quot; and &quot;c&quot;.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>pattern</para></td><td class="parameter_description"><para>the regular expression</para><para>Passed as <code>pattern</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to scan for matches</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>compile_options</para></td><td class="parameter_description"><para>compile options for the regular expression, or 0</para><para>Passed as <code>compile-options</code></para></td></tr><tr><td class="parameter_name"><para>match_options</para></td><td class="parameter_description"><para>match options, or 0</para><para>Passed as <code>match-options</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibRegexCompileFlags&gt;</refname></refnamediv><refsect1><title>Description</title><para>Flags specifying compile-time options.</para></refsect1><refsect1><title>Members</title><refsect2><title>caseless</title><remark>alias <code>G_REGEX_CASELESS</code></remark><para>Letters in the pattern match both upper- and
    lowercase letters. This option can be changed within a pattern
    by a &quot;(?i)&quot; option setting.</para></refsect2><refsect2><title>multiline</title><remark>alias <code>G_REGEX_MULTILINE</code></remark><para>By default, GRegex treats the strings as consisting
    of a single line of characters (even if it actually contains
    newlines). The &quot;start of line&quot; metacharacter (&quot;^&quot;) matches only
    at the start of the string, while the &quot;end of line&quot; metacharacter
    (&quot;$&quot;) matches only at the end of the string, or before a terminating
    newline (unless <type>G_REGEX_DOLLAR_ENDONLY</type> is set). When
    <type>G_REGEX_MULTILINE</type> is set, the &quot;start of line&quot; and &quot;end of line&quot;
    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 &quot;(?m)&quot; option
    setting.</para></refsect2><refsect2><title>dotall</title><remark>alias <code>G_REGEX_DOTALL</code></remark><para>A dot metacharacter (&quot;.&quot;) in the pattern matches all
    characters, including newlines. Without it, newlines are excluded.
    This option can be changed within a pattern by a (&quot;?s&quot;) option setting.</para></refsect2><refsect2><title>extended</title><remark>alias <code>G_REGEX_EXTENDED</code></remark><para>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 &quot;#&quot; outside a character class and
    the next newline character, inclusive, are also ignored. This can
    be changed within a pattern by a &quot;(?x)&quot; option setting.</para></refsect2><refsect2><title>anchored</title><remark>alias <code>G_REGEX_ANCHORED</code></remark><para>The pattern is forced to be &quot;anchored&quot;, 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 &quot;^&quot;
    metacharacter.</para></refsect2><refsect2><title>dollar-endonly</title><remark>alias <code>G_REGEX_DOLLAR_ENDONLY</code></remark><para>A dollar metacharacter (&quot;$&quot;) 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 <type>G_REGEX_MULTILINE</type> is set.</para></refsect2><refsect2><title>ungreedy</title><remark>alias <code>G_REGEX_UNGREEDY</code></remark><para>Inverts the &quot;greediness&quot; of the quantifiers so that
    they are not greedy by default, but become greedy if followed by &quot;?&quot;.
    It can also be set by a &quot;(?U)&quot; option setting within the pattern.</para></refsect2><refsect2><title>raw</title><remark>alias <code>G_REGEX_RAW</code></remark><para>Usually strings must be valid UTF-8 strings, using this
    flag they are considered as a raw sequence of bytes.</para></refsect2><refsect2><title>no-auto-capture</title><remark>alias <code>G_REGEX_NO_AUTO_CAPTURE</code></remark><para>Disables the use of numbered capturing
    parentheses in the pattern. Any opening parenthesis that is not
    followed by &quot;?&quot; behaves as if it were followed by &quot;?:&quot; but named
    parentheses can still be used for capturing (and they acquire numbers
    in the usual way).</para></refsect2><refsect2><title>optimize</title><remark>alias <code>G_REGEX_OPTIMIZE</code></remark><para>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.</para></refsect2><refsect2><title>firstline</title><remark>alias <code>G_REGEX_FIRSTLINE</code></remark><para>Limits an unanchored pattern to match before (or at) the
    first newline. Since: 2.34</para></refsect2><refsect2><title>dupnames</title><remark>alias <code>G_REGEX_DUPNAMES</code></remark><para>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.</para></refsect2><refsect2><title>newline-cr</title><remark>alias <code>G_REGEX_NEWLINE_CR</code></remark><para>Usually any newline character or character sequence is
    recognized. If this option is set, the only recognized newline character
    is '\r'.</para></refsect2><refsect2><title>newline-lf</title><remark>alias <code>G_REGEX_NEWLINE_LF</code></remark><para>Usually any newline character or character sequence is
    recognized. If this option is set, the only recognized newline character
    is '\n'.</para></refsect2><refsect2><title>newline-crlf</title><remark>alias <code>G_REGEX_NEWLINE_CRLF</code></remark><para>Usually any newline character or character sequence is
    recognized. If this option is set, the only recognized newline character
    sequence is '\r\n'.</para></refsect2><refsect2><title>newline-anycrlf</title><remark>alias <code>G_REGEX_NEWLINE_ANYCRLF</code></remark><para>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</para></refsect2><refsect2><title>bsr-anycrlf</title><remark>alias <code>G_REGEX_BSR_ANYCRLF</code></remark><para>Usually any newline character or character sequence
    is recognised. If this option is set, then &quot;\R&quot; only recognizes the newline
   characters '\r', '\n' and '\r\n'. Since: 2.34</para></refsect2><refsect2><title>javascript-compat</title><remark>alias <code>G_REGEX_JAVASCRIPT_COMPAT</code></remark><para>Changes behaviour so that it is compatible with
    JavaScript rather than PCRE. Since: 2.34</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibRegexError&gt;</refname></refnamediv><refsect1><title>Description</title><para>Error codes returned by regular expressions functions.</para></refsect1><refsect1><title>Members</title><refsect2><title>compile</title><remark>alias <code>G_REGEX_ERROR_COMPILE</code></remark><para>Compilation of the regular expression failed.</para></refsect2><refsect2><title>optimize</title><remark>alias <code>G_REGEX_ERROR_OPTIMIZE</code></remark><para>Optimization of the regular expression failed.</para></refsect2><refsect2><title>replace</title><remark>alias <code>G_REGEX_ERROR_REPLACE</code></remark><para>Replacement failed due to an ill-formed replacement
    string.</para></refsect2><refsect2><title>match</title><remark>alias <code>G_REGEX_ERROR_MATCH</code></remark><para>The match process failed.</para></refsect2><refsect2><title>internal</title><remark>alias <code>G_REGEX_ERROR_INTERNAL</code></remark><para>Internal error of the regular expression engine.
    Since 2.16</para></refsect2><refsect2><title>stray-backslash</title><remark>alias <code>G_REGEX_ERROR_STRAY_BACKSLASH</code></remark><para>&quot;\\&quot; at end of pattern. Since 2.16</para></refsect2><refsect2><title>missing-control-char</title><remark>alias <code>G_REGEX_ERROR_MISSING_CONTROL_CHAR</code></remark><para>&quot;\\c&quot; at end of pattern. Since 2.16</para></refsect2><refsect2><title>unrecognized-escape</title><remark>alias <code>G_REGEX_ERROR_UNRECOGNIZED_ESCAPE</code></remark><para>Unrecognized character follows &quot;\\&quot;.
    Since 2.16</para></refsect2><refsect2><title>quantifiers-out-of-order</title><remark>alias <code>G_REGEX_ERROR_QUANTIFIERS_OUT_OF_ORDER</code></remark><para>Numbers out of order in &quot;{}&quot;
    quantifier. Since 2.16</para></refsect2><refsect2><title>quantifier-too-big</title><remark>alias <code>G_REGEX_ERROR_QUANTIFIER_TOO_BIG</code></remark><para>Number too big in &quot;{}&quot; quantifier.
    Since 2.16</para></refsect2><refsect2><title>unterminated-character-class</title><remark>alias <code>G_REGEX_ERROR_UNTERMINATED_CHARACTER_CLASS</code></remark><para>Missing terminating &quot;]&quot; for
    character class. Since 2.16</para></refsect2><refsect2><title>invalid-escape-in-character-class</title><remark>alias <code>G_REGEX_ERROR_INVALID_ESCAPE_IN_CHARACTER_CLASS</code></remark><para>Invalid escape sequence
    in character class. Since 2.16</para></refsect2><refsect2><title>range-out-of-order</title><remark>alias <code>G_REGEX_ERROR_RANGE_OUT_OF_ORDER</code></remark><para>Range out of order in character class.
    Since 2.16</para></refsect2><refsect2><title>nothing-to-repeat</title><remark>alias <code>G_REGEX_ERROR_NOTHING_TO_REPEAT</code></remark><para>Nothing to repeat. Since 2.16</para></refsect2><refsect2><title>unrecognized-character</title><remark>alias <code>G_REGEX_ERROR_UNRECOGNIZED_CHARACTER</code></remark><para>Unrecognized character after &quot;(?&quot;,
    &quot;(?&lt;&quot; or &quot;(?P&quot;. Since 2.16</para></refsect2><refsect2><title>posix-named-class-outside-class</title><remark>alias <code>G_REGEX_ERROR_POSIX_NAMED_CLASS_OUTSIDE_CLASS</code></remark><para>POSIX named classes are
    supported only within a class. Since 2.16</para></refsect2><refsect2><title>unmatched-parenthesis</title><remark>alias <code>G_REGEX_ERROR_UNMATCHED_PARENTHESIS</code></remark><para>Missing terminating &quot;)&quot; or &quot;)&quot;
    without opening &quot;(&quot;. Since 2.16</para></refsect2><refsect2><title>inexistent-subpattern-reference</title><remark>alias <code>G_REGEX_ERROR_INEXISTENT_SUBPATTERN_REFERENCE</code></remark><para>Reference to non-existent
    subpattern. Since 2.16</para></refsect2><refsect2><title>unterminated-comment</title><remark>alias <code>G_REGEX_ERROR_UNTERMINATED_COMMENT</code></remark><para>Missing terminating &quot;)&quot; after comment.
    Since 2.16</para></refsect2><refsect2><title>expression-too-large</title><remark>alias <code>G_REGEX_ERROR_EXPRESSION_TOO_LARGE</code></remark><para>Regular expression too large.
    Since 2.16</para></refsect2><refsect2><title>memory-error</title><remark>alias <code>G_REGEX_ERROR_MEMORY_ERROR</code></remark><para>Failed to get memory. Since 2.16</para></refsect2><refsect2><title>variable-length-lookbehind</title><remark>alias <code>G_REGEX_ERROR_VARIABLE_LENGTH_LOOKBEHIND</code></remark><para>Lookbehind assertion is not
    fixed length. Since 2.16</para></refsect2><refsect2><title>malformed-condition</title><remark>alias <code>G_REGEX_ERROR_MALFORMED_CONDITION</code></remark><para>Malformed number or name after &quot;(?(&quot;.
    Since 2.16</para></refsect2><refsect2><title>too-many-conditional-branches</title><remark>alias <code>G_REGEX_ERROR_TOO_MANY_CONDITIONAL_BRANCHES</code></remark><para>Conditional group contains
    more than two branches. Since 2.16</para></refsect2><refsect2><title>assertion-expected</title><remark>alias <code>G_REGEX_ERROR_ASSERTION_EXPECTED</code></remark><para>Assertion expected after &quot;(?(&quot;.
    Since 2.16</para></refsect2><refsect2><title>unknown-posix-class-name</title><remark>alias <code>G_REGEX_ERROR_UNKNOWN_POSIX_CLASS_NAME</code></remark><para>Unknown POSIX class name.
    Since 2.16</para></refsect2><refsect2><title>posix-collating-elements-not-supported</title><remark>alias <code>G_REGEX_ERROR_POSIX_COLLATING_ELEMENTS_NOT_SUPPORTED</code></remark><para>POSIX collating
    elements are not supported. Since 2.16</para></refsect2><refsect2><title>hex-code-too-large</title><remark>alias <code>G_REGEX_ERROR_HEX_CODE_TOO_LARGE</code></remark><para>Character value in &quot;\\x{...}&quot; sequence
    is too large. Since 2.16</para></refsect2><refsect2><title>invalid-condition</title><remark>alias <code>G_REGEX_ERROR_INVALID_CONDITION</code></remark><para>Invalid condition &quot;(?(0)&quot;. Since 2.16</para></refsect2><refsect2><title>single-byte-match-in-lookbehind</title><remark>alias <code>G_REGEX_ERROR_SINGLE_BYTE_MATCH_IN_LOOKBEHIND</code></remark><para>\\C not allowed in
    lookbehind assertion. Since 2.16</para></refsect2><refsect2><title>infinite-loop</title><remark>alias <code>G_REGEX_ERROR_INFINITE_LOOP</code></remark><para>Recursive call could loop indefinitely.
    Since 2.16</para></refsect2><refsect2><title>missing-subpattern-name-terminator</title><remark>alias <code>G_REGEX_ERROR_MISSING_SUBPATTERN_NAME_TERMINATOR</code></remark><para>Missing terminator
    in subpattern name. Since 2.16</para></refsect2><refsect2><title>duplicate-subpattern-name</title><remark>alias <code>G_REGEX_ERROR_DUPLICATE_SUBPATTERN_NAME</code></remark><para>Two named subpatterns have
    the same name. Since 2.16</para></refsect2><refsect2><title>malformed-property</title><remark>alias <code>G_REGEX_ERROR_MALFORMED_PROPERTY</code></remark><para>Malformed &quot;\\P&quot; or &quot;\\p&quot; sequence.
    Since 2.16</para></refsect2><refsect2><title>unknown-property</title><remark>alias <code>G_REGEX_ERROR_UNKNOWN_PROPERTY</code></remark><para>Unknown property name after &quot;\\P&quot; or
    &quot;\\p&quot;. Since 2.16</para></refsect2><refsect2><title>subpattern-name-too-long</title><remark>alias <code>G_REGEX_ERROR_SUBPATTERN_NAME_TOO_LONG</code></remark><para>Subpattern name is too long
    (maximum 32 characters). Since 2.16</para></refsect2><refsect2><title>too-many-subpatterns</title><remark>alias <code>G_REGEX_ERROR_TOO_MANY_SUBPATTERNS</code></remark><para>Too many named subpatterns (maximum
    10,000). Since 2.16</para></refsect2><refsect2><title>invalid-octal-value</title><remark>alias <code>G_REGEX_ERROR_INVALID_OCTAL_VALUE</code></remark><para>Octal value is greater than &quot;\\377&quot;.
    Since 2.16</para></refsect2><refsect2><title>too-many-branches-in-define</title><remark>alias <code>G_REGEX_ERROR_TOO_MANY_BRANCHES_IN_DEFINE</code></remark><para>&quot;DEFINE&quot; group contains more
    than one branch. Since 2.16</para></refsect2><refsect2><title>define-repetion</title><remark>alias <code>G_REGEX_ERROR_DEFINE_REPETION</code></remark><para>Repeating a &quot;DEFINE&quot; group is not allowed.
    This error is never raised. Since: 2.16 Deprecated: 2.34</para></refsect2><refsect2><title>inconsistent-newline-options</title><remark>alias <code>G_REGEX_ERROR_INCONSISTENT_NEWLINE_OPTIONS</code></remark><para>Inconsistent newline options.
    Since 2.16</para></refsect2><refsect2><title>missing-back-reference</title><remark>alias <code>G_REGEX_ERROR_MISSING_BACK_REFERENCE</code></remark><para>&quot;\\g&quot; is not followed by a braced,
     angle-bracketed, or quoted name or number, or by a plain number. Since: 2.16</para></refsect2><refsect2><title>invalid-relative-reference</title><remark>alias <code>G_REGEX_ERROR_INVALID_RELATIVE_REFERENCE</code></remark><para>relative reference must not be zero. Since: 2.34</para></refsect2><refsect2><title>backtracking-control-verb-argument-forbidden</title><remark>alias <code>G_REGEX_ERROR_BACKTRACKING_CONTROL_VERB_ARGUMENT_FORBIDDEN</code></remark><para>the backtracing
    control verb used does not allow an argument. Since: 2.34</para></refsect2><refsect2><title>unknown-backtracking-control-verb</title><remark>alias <code>G_REGEX_ERROR_UNKNOWN_BACKTRACKING_CONTROL_VERB</code></remark><para>unknown backtracing
    control verb. Since: 2.34</para></refsect2><refsect2><title>number-too-big</title><remark>alias <code>G_REGEX_ERROR_NUMBER_TOO_BIG</code></remark><para>number is too big in escape sequence. Since: 2.34</para></refsect2><refsect2><title>missing-subpattern-name</title><remark>alias <code>G_REGEX_ERROR_MISSING_SUBPATTERN_NAME</code></remark><para>Missing subpattern name. Since: 2.34</para></refsect2><refsect2><title>missing-digit</title><remark>alias <code>G_REGEX_ERROR_MISSING_DIGIT</code></remark><para>Missing digit. Since 2.34</para></refsect2><refsect2><title>invalid-data-character</title><remark>alias <code>G_REGEX_ERROR_INVALID_DATA_CHARACTER</code></remark><para>In JavaScript compatibility mode,
    &quot;[&quot; is an invalid data character. Since: 2.34</para></refsect2><refsect2><title>extra-subpattern-name</title><remark>alias <code>G_REGEX_ERROR_EXTRA_SUBPATTERN_NAME</code></remark><para>different names for subpatterns of the
    same number are not allowed. Since: 2.34</para></refsect2><refsect2><title>backtracking-control-verb-argument-required</title><remark>alias <code>G_REGEX_ERROR_BACKTRACKING_CONTROL_VERB_ARGUMENT_REQUIRED</code></remark><para>the backtracing control
    verb requires an argument. Since: 2.34</para></refsect2><refsect2><title>invalid-control-char</title><remark>alias <code>G_REGEX_ERROR_INVALID_CONTROL_CHAR</code></remark><para>&quot;\\c&quot; must be followed by an ASCII
    character. Since: 2.34</para></refsect2><refsect2><title>missing-name</title><remark>alias <code>G_REGEX_ERROR_MISSING_NAME</code></remark><para>&quot;\\k&quot; is not followed by a braced, angle-bracketed, or
    quoted name. Since: 2.34</para></refsect2><refsect2><title>not-supported-in-class</title><remark>alias <code>G_REGEX_ERROR_NOT_SUPPORTED_IN_CLASS</code></remark><para>&quot;\\N&quot; is not supported in a class. Since: 2.34</para></refsect2><refsect2><title>too-many-forward-references</title><remark>alias <code>G_REGEX_ERROR_TOO_MANY_FORWARD_REFERENCES</code></remark><para>too many forward references. Since: 2.34</para></refsect2><refsect2><title>name-too-long</title><remark>alias <code>G_REGEX_ERROR_NAME_TOO_LONG</code></remark><para>the name is too long in &quot;(*MARK)&quot;, &quot;(*PRUNE)&quot;,
    &quot;(*SKIP)&quot;, or &quot;(*THEN)&quot;. Since: 2.34</para></refsect2><refsect2><title>character-value-too-large</title><remark>alias <code>G_REGEX_ERROR_CHARACTER_VALUE_TOO_LARGE</code></remark><para>the character value in the \\u sequence is
    too large. Since: 2.34</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibRegexMatchFlags&gt;</refname></refnamediv><refsect1><title>Description</title><para>Flags specifying match-time options.</para></refsect1><refsect1><title>Members</title><refsect2><title>anchored</title><remark>alias <code>G_REGEX_MATCH_ANCHORED</code></remark><para>The pattern is forced to be &quot;anchored&quot;, 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 &quot;^&quot;
    metacharacter.</para></refsect2><refsect2><title>notbol</title><remark>alias <code>G_REGEX_MATCH_NOTBOL</code></remark><para>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 <type>G_REGEX_MULTILINE</type> (at
    compile time) causes circumflex never to match. This option affects
    only the behaviour of the circumflex metacharacter, it does not
    affect &quot;\A&quot;.</para></refsect2><refsect2><title>noteol</title><remark>alias <code>G_REGEX_MATCH_NOTEOL</code></remark><para>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 <type>G_REGEX_MULTILINE</type> (at compile time) causes
    dollar never to match. This option affects only the behaviour of
    the dollar metacharacter, it does not affect &quot;\Z&quot; or &quot;\z&quot;.</para></refsect2><refsect2><title>notempty</title><remark>alias <code>G_REGEX_MATCH_NOTEMPTY</code></remark><para>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 &quot;a?b?&quot; is applied to
    a string not beginning with &quot;a&quot; or &quot;b&quot;, 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 &quot;a&quot; or &quot;b&quot;.</para></refsect2><refsect2><title>partial</title><remark>alias <code>G_REGEX_MATCH_PARTIAL</code></remark><para>Turns on the partial matching feature, for more
    documentation on partial matching see <function>g_match_info_is_partial_match()</function>.</para></refsect2><refsect2><title>newline-cr</title><remark>alias <code>G_REGEX_MATCH_NEWLINE_CR</code></remark><para>Overrides the newline definition set when
    creating a new <type>GRegex</type>, setting the '\r' character as line terminator.</para></refsect2><refsect2><title>newline-lf</title><remark>alias <code>G_REGEX_MATCH_NEWLINE_LF</code></remark><para>Overrides the newline definition set when
    creating a new <type>GRegex</type>, setting the '\n' character as line terminator.</para></refsect2><refsect2><title>newline-crlf</title><remark>alias <code>G_REGEX_MATCH_NEWLINE_CRLF</code></remark><para>Overrides the newline definition set when
    creating a new <type>GRegex</type>, setting the '\r\n' characters sequence as line terminator.</para></refsect2><refsect2><title>newline-any</title><remark>alias <code>G_REGEX_MATCH_NEWLINE_ANY</code></remark><para>Overrides the newline definition set when
    creating a new <type>GRegex</type>, 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.</para></refsect2><refsect2><title>newline-anycrlf</title><remark>alias <code>G_REGEX_MATCH_NEWLINE_ANYCRLF</code></remark><para>Overrides the newline definition set when
    creating a new <type>GRegex</type>; any '\r', '\n', or '\r\n' character sequence
    is recognized as a newline. Since: 2.34</para></refsect2><refsect2><title>bsr-anycrlf</title><remark>alias <code>G_REGEX_MATCH_BSR_ANYCRLF</code></remark><para>Overrides the newline definition for &quot;\R&quot; set when
    creating a new <type>GRegex</type>; only '\r', '\n', or '\r\n' character sequences
    are recognized as a newline by &quot;\R&quot;. Since: 2.34</para></refsect2><refsect2><title>bsr-any</title><remark>alias <code>G_REGEX_MATCH_BSR_ANY</code></remark><para>Overrides the newline definition for &quot;\R&quot; set when
    creating a new <type>GRegex</type>; any Unicode newline character or character sequence
    are recognized as a newline by &quot;\R&quot;. 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</para></refsect2><refsect2><title>partial-soft</title><remark>alias <code>G_REGEX_MATCH_PARTIAL_SOFT</code></remark><para>An alias for <type>G_REGEX_MATCH_PARTIAL</type>. Since: 2.34</para></refsect2><refsect2><title>partial-hard</title><remark>alias <code>G_REGEX_MATCH_PARTIAL_HARD</code></remark><para>Turns on the partial matching feature. In contrast to
    to <type>G_REGEX_MATCH_PARTIAL_SOFT</type>, this stops matching as soon as a partial match
    is found, without continuing to search for a possible complete match. See
    <function>g_match_info_is_partial_match()</function> for more information. Since: 2.34</para></refsect2><refsect2><title>notempty-atstart</title><remark>alias <code>G_REGEX_MATCH_NOTEMPTY_ATSTART</code></remark><para>Like <type>G_REGEX_MATCH_NOTEMPTY</type>, but only applied to
    the start of the matched string. For anchored
    patterns this can only happen for pattern containing &quot;\K&quot;. Since: 2.34</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibSeekType&gt;</refname></refnamediv><refsect1><title>Description</title><para>An enumeration specifying the base position for a
<function>g_io_channel_seek_position()</function> operation.</para></refsect1><refsect1><title>Members</title><refsect2><title>cur</title><remark>alias <code>G_SEEK_CUR</code></remark><para>the current position in the file.</para></refsect2><refsect2><title>set</title><remark>alias <code>G_SEEK_SET</code></remark><para>the start of the file.</para></refsect2><refsect2><title>end</title><remark>alias <code>G_SEEK_END</code></remark><para>the end of the file.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibShellError&gt;</refname></refnamediv><refsect1><title>Description</title><para>Error codes returned by shell functions.</para></refsect1><refsect1><title>Members</title><refsect2><title>bad-quoting</title><remark>alias <code>G_SHELL_ERROR_BAD_QUOTING</code></remark><para>Mismatched or otherwise mangled quoting.</para></refsect2><refsect2><title>empty-string</title><remark>alias <code>G_SHELL_ERROR_EMPTY_STRING</code></remark><para>String to be parsed was empty.</para></refsect2><refsect2><title>failed</title><remark>alias <code>G_SHELL_ERROR_FAILED</code></remark><para>Some other error.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibSliceConfig&gt;</refname></refnamediv><refsect1><title>Members</title><refsect2><title>always-malloc</title><remark>alias <code>G_SLICE_CONFIG_ALWAYS_MALLOC</code></remark><para>Undocumented</para></refsect2><refsect2><title>bypass-magazines</title><remark>alias <code>G_SLICE_CONFIG_BYPASS_MAGAZINES</code></remark><para>Undocumented</para></refsect2><refsect2><title>working-set-msecs</title><remark>alias <code>G_SLICE_CONFIG_WORKING_SET_MSECS</code></remark><para>Undocumented</para></refsect2><refsect2><title>color-increment</title><remark>alias <code>G_SLICE_CONFIG_COLOR_INCREMENT</code></remark><para>Undocumented</para></refsect2><refsect2><title>chunk-sizes</title><remark>alias <code>G_SLICE_CONFIG_CHUNK_SIZES</code></remark><para>Undocumented</para></refsect2><refsect2><title>contention-counter</title><remark>alias <code>G_SLICE_CONFIG_CONTENTION_COUNTER</code></remark><para>Undocumented</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GSource&gt;</refname></refnamediv><refsect1><title>Description</title><para>The <code>GSource</code> struct is an opaque data type
representing an event source.</para></refsect1><refsect1><title>Functions</title><refsect2><title>add-child-source</title><informalexample><programlisting>(define-values () (source:add-child-source self child-source))
</programlisting></informalexample><para>Adds <parameter>child_source</parameter> to <parameter>source</parameter> as a &quot;polled&quot; source; when <parameter>source</parameter> is
added to a <type>GMainContext</type>, <parameter>child_source</parameter> will be automatically added
with the same priority, when <parameter>child_source</parameter> is triggered, it will
cause <parameter>source</parameter> to dispatch (in addition to calling its own
callback), and when <parameter>source</parameter> is destroyed, it will destroy
<parameter>child_source</parameter> as well. (<parameter>source</parameter> will also still be dispatched if
its own prepare/check functions indicate that it is ready.)
</para>
<para>If you don't need <parameter>child_source</parameter> to do anything on its own when it
triggers, you can call <function>g_source_set_dummy_callback()</function> on it to set a
callback that does nothing (except return <constant>TRUE</constant> if appropriate).
</para>
<para><parameter>source</parameter> will hold a reference on <parameter>child_source</parameter> while <parameter>child_source</parameter>
is attached to it.
</para>
<para>This API is only intended to be used by implementations of <type>GSource</type>.
Do not call this API on a <type>GSource</type> that you did not create.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>child_source</para></td><td class="parameter_description"><para>a second <type>GSource</type> that <parameter>source</parameter> should &quot;poll&quot;</para><para>Passed as <code>child-source</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>add-poll</title><informalexample><programlisting>(define-values () (source:add-poll self fd))
</programlisting></informalexample><para>Adds a file descriptor to the set of file descriptors polled for
this source. This is usually combined with <function>g_source_new()</function> to add an
event source. The event source's check function will typically test
the <parameter>revents</parameter> field in the <type>GPollFD</type> struct and return <constant>TRUE</constant> if events need
to be processed.
</para>
<para>This API is only intended to be used by implementations of <type>GSource</type>.
Do not call this API on a <type>GSource</type> that you did not create.
</para>
<para>Using this API forces the linear scanning of event sources on each
main loop iteration.  Newly-written event sources should try to use
<function>g_source_add_unix_fd()</function> instead of this API.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>fd</para></td><td class="parameter_description"><para>a <type>GPollFD</type> structure holding information about a file
     descriptor to watch.</para><para>Passed as <code>fd</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>add-unix-fd</title><informalexample><programlisting>(define-values (%return) (source:add-unix-fd self fd events))
</programlisting></informalexample><para>Monitors <parameter>fd</parameter> for the IO events in <parameter>events</parameter>.
</para>
<para>The tag returned by this function can be used to remove or modify the
monitoring of the fd using <function>g_source_remove_unix_fd()</function> or
<function>g_source_modify_unix_fd()</function>.
</para>
<para>It is not necessary to remove the fd before destroying the source; it
will be cleaned up automatically.
</para>
<para>This API is only intended to be used by implementations of <type>GSource</type>.
Do not call this API on a <type>GSource</type> that you did not create.
</para>
<para>As the name suggests, this function is not available on Windows.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>fd</para></td><td class="parameter_description"><para>the fd to monitor</para><para>Passed as <code>fd</code></para></td></tr><tr><td class="parameter_name"><para>events</para></td><td class="parameter_description"><para>an event mask</para><para>Passed as <code>events</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>attach</title><informalexample><programlisting>(define-values (%return) (source:attach self context))
</programlisting></informalexample><para>Adds a <type>GSource</type> to a <parameter>context</parameter> so that it will be executed within
that context. Remove it by calling <function>g_source_destroy()</function>.
</para>
<para>This function is safe to call from any thread, regardless of which thread
the <parameter>context</parameter> is running in.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>a <type>GMainContext</type> (if <constant>NULL</constant>, the default context will be used)</para><para>Passed as <code>context</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>destroy</title><informalexample><programlisting>(define-values () (source:destroy self))
</programlisting></informalexample><para>Removes a source from its <type>GMainContext</type>, 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.
</para>
<para>This does not unref the #GSource: if you still hold a reference, use
<function>g_source_unref()</function> to drop it.
</para>
<para>This function is safe to call from any thread, regardless of which thread
the <type>GMainContext</type> is running in.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-can-recurse?</title><informalexample><programlisting>(define-values (%return) (source:get-can-recurse? self))
</programlisting></informalexample><para>Checks whether a source is allowed to be called recursively.
see <function>g_source_set_can_recurse()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-context</title><informalexample><programlisting>(define-values (%return) (source:get-context self))
</programlisting></informalexample><para>Gets the <type>GMainContext</type> with which the source is associated.
</para>
<para>You can call this on a source that has been destroyed, provided
that the <type>GMainContext</type> it was attached to still exists (in which
case it will return that <type>GMainContext</type>). In particular, you can
always call this function on the source returned from
<function>g_main_current_source()</function>. But calling this function on a source
whose <type>GMainContext</type> has been destroyed is an error.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-id</title><informalexample><programlisting>(define-values (%return) (source:get-id self))
</programlisting></informalexample><para>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 <function>g_main_context_find_source_by_id()</function>.
</para>
<para>You can only call this function while the source is associated to a
<type>GMainContext</type> instance; calling this function before <function>g_source_attach()</function>
or after <function>g_source_destroy()</function> yields undefined behavior. The ID returned
is unique within the <type>GMainContext</type> instance passed to <function>g_source_attach()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-name</title><informalexample><programlisting>(define-values (%return) (source:get-name self))
</programlisting></informalexample><para>Gets a name for the source, used in debugging and profiling.  The
name may be <type>NULL</type> if it has never been set with <function>g_source_set_name()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-priority</title><informalexample><programlisting>(define-values (%return) (source:get-priority self))
</programlisting></informalexample><para>Gets the priority of a source.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-ready-time</title><informalexample><programlisting>(define-values (%return) (source:get-ready-time self))
</programlisting></informalexample><para>Gets the &quot;ready time&quot; of <parameter>source</parameter>, as set by
<function>g_source_set_ready_time()</function>.
</para>
<para>Any time before the current monotonic time (including 0) is an
indication that the source will fire immediately.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-time</title><informalexample><programlisting>(define-values (%return) (source:get-time self))
</programlisting></informalexample><para>Gets the time to be used when checking this source. The advantage of
calling this function over calling <function>g_get_monotonic_time()</function> directly is
that when checking multiple sources, GLib can cache a single value
instead of having to repeatedly get the system monotonic time.
</para>
<para>The time here is the system monotonic time, if available, or some
other reasonable alternative otherwise.  See <function>g_get_monotonic_time()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-destroyed?</title><informalexample><programlisting>(define-values (%return) (source:is-destroyed? self))
</programlisting></informalexample><para>Returns whether <parameter>source</parameter> has been destroyed.
</para>
<para>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.
</para>
<para><informalexample><programlisting>
static gboolean
idle_callback (gpointer data)
{
  SomeWidget *self = data;
   
  GDK_THREADS_ENTER ();
  // do stuff with self
  self-&gt;idle_id = 0;
  GDK_THREADS_LEAVE ();
   
  return G_SOURCE_REMOVE;
}
 
static void
some_widget_do_stuff_later (SomeWidget *self)
{
  self-&gt;idle_id = g_idle_add (idle_callback, self);
}
 
static void
some_widget_finalize (GObject *object)
{
  SomeWidget *self = SOME_WIDGET (object);
   
  if (self-&gt;idle_id)
    g_source_remove (self-&gt;idle_id);
   
  G_OBJECT_CLASS (parent_class)-&gt;finalize (object);
}
</programlisting></informalexample></para>

<para>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.
</para>
<para><informalexample><programlisting>
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;
}
</programlisting></informalexample></para>

<para>Calls to this function from a thread other than the one acquired by the
<type>GMainContext</type> the <type>GSource</type> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>modify-unix-fd</title><informalexample><programlisting>(define-values () (source:modify-unix-fd self tag new-events))
</programlisting></informalexample><para>Updates the event mask to watch for the fd identified by <parameter>tag</parameter>.
</para>
<para><parameter>tag</parameter> is the tag returned from <function>g_source_add_unix_fd()</function>.
</para>
<para>If you want to remove a fd, don't set its event mask to zero.
Instead, call <function>g_source_remove_unix_fd()</function>.
</para>
<para>This API is only intended to be used by implementations of <type>GSource</type>.
Do not call this API on a <type>GSource</type> that you did not create.
</para>
<para>As the name suggests, this function is not available on Windows.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>tag</para></td><td class="parameter_description"><para>the tag from <function>g_source_add_unix_fd()</function></para><para>Passed as <code>tag</code></para></td></tr><tr><td class="parameter_name"><para>new_events</para></td><td class="parameter_description"><para>the new event mask to watch</para><para>Passed as <code>new-events</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>query-unix-fd</title><informalexample><programlisting>(define-values (%return) (source:query-unix-fd self tag))
</programlisting></informalexample><para>Queries the events reported for the fd corresponding to <parameter>tag</parameter> on
<parameter>source</parameter> during the last poll.
</para>
<para>The return value of this function is only defined when the function
is called from the check or dispatch functions for <parameter>source</parameter>.
</para>
<para>This API is only intended to be used by implementations of <type>GSource</type>.
Do not call this API on a <type>GSource</type> that you did not create.
</para>
<para>As the name suggests, this function is not available on Windows.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>tag</para></td><td class="parameter_description"><para>the tag from <function>g_source_add_unix_fd()</function></para><para>Passed as <code>tag</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref</title><informalexample><programlisting>(define-values (%return) (source:ref self))
</programlisting></informalexample><para>Increases the reference count on a source by one.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>remove-child-source</title><informalexample><programlisting>(define-values () (source:remove-child-source self child-source))
</programlisting></informalexample><para>Detaches <parameter>child_source</parameter> from <parameter>source</parameter> and destroys it.
</para>
<para>This API is only intended to be used by implementations of <type>GSource</type>.
Do not call this API on a <type>GSource</type> that you did not create.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>child_source</para></td><td class="parameter_description"><para>a <type>GSource</type> previously passed to
    <function>g_source_add_child_source()</function>.</para><para>Passed as <code>child-source</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>remove-poll</title><informalexample><programlisting>(define-values () (source:remove-poll self fd))
</programlisting></informalexample><para>Removes a file descriptor from the set of file descriptors polled for
this source.
</para>
<para>This API is only intended to be used by implementations of <type>GSource</type>.
Do not call this API on a <type>GSource</type> that you did not create.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>fd</para></td><td class="parameter_description"><para>a <type>GPollFD</type> structure previously passed to <function>g_source_add_poll()</function>.</para><para>Passed as <code>fd</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>remove-unix-fd</title><informalexample><programlisting>(define-values () (source:remove-unix-fd self tag))
</programlisting></informalexample><para>Reverses the effect of a previous call to <function>g_source_add_unix_fd()</function>.
</para>
<para>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.
</para>
<para>This API is only intended to be used by implementations of <type>GSource</type>.
Do not call this API on a <type>GSource</type> that you did not create.
</para>
<para>As the name suggests, this function is not available on Windows.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>tag</para></td><td class="parameter_description"><para>the tag from <function>g_source_add_unix_fd()</function></para><para>Passed as <code>tag</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-callback</title><informalexample><programlisting>(define-values () (source:set-callback self func data notify))
</programlisting></informalexample><para>Sets the callback function for a source. The callback for a source is
called from the source's dispatch function.
</para>
<para>The exact type of <parameter>func</parameter> depends on the type of source; ie. you
should not count on <parameter>func</parameter> being called with <parameter>data</parameter> as its first
parameter. Cast <parameter>func</parameter> with <function>G_SOURCE_FUNC()</function> to avoid warnings about
incompatible function types.
</para>
<para>See [memory management of sources][mainloop-memory-management] for details
on how to handle memory management of <parameter>data</parameter>.
</para>
<para>Typically, you won't use this function. Instead use functions specific
to the type of source you are using, such as <function>g_idle_add()</function> or <function>g_timeout_add()</function>.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>the source</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>func</para></td><td class="parameter_description"><para>a callback function</para><para>Passed as <code>func</code></para></td></tr><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>the data to pass to callback function</para><para>Passed as <code>data</code></para></td></tr><tr><td class="parameter_name"><para>notify</para></td><td class="parameter_description"><para>a function to call when <parameter>data</parameter> is no longer in use, or <constant>NULL</constant>.</para><para>Passed as <code>notify</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-can-recurse</title><informalexample><programlisting>(define-values () (source:set-can-recurse self can-recurse))
</programlisting></informalexample><para>Sets whether a source can be called recursively. If <parameter>can_recurse</parameter> is
<constant>TRUE</constant>, 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>can_recurse</para></td><td class="parameter_description"><para>whether recursion is allowed for this source</para><para>Passed as <code>can-recurse</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-name</title><informalexample><programlisting>(define-values () (source:set-name self name))
</programlisting></informalexample><para>Sets a name for the source, used in debugging and profiling.
The name defaults to <type>NULL</type>.
</para>
<para>The source name should describe in a human-readable way
what the source does. For example, &quot;X11 event queue&quot;
or &quot;GTK+ repaint idle handler&quot; or whatever it is.
</para>
<para>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 &quot;check&quot; function of a <type>GSourceFuncs</type>
to include details like the event type in the source name.
</para>
<para>Use caution if changing the name while another thread may be
accessing it with <function>g_source_get_name()</function>; that function does not copy
the value, and changing the value will free it while the other thread
may be attempting to use it.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>name</para></td><td class="parameter_description"><para>debug name for the source</para><para>Passed as <code>name</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-priority</title><informalexample><programlisting>(define-values () (source:set-priority self priority))
</programlisting></informalexample><para>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.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>priority</para></td><td class="parameter_description"><para>the new priority.</para><para>Passed as <code>priority</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-ready-time</title><informalexample><programlisting>(define-values () (source:set-ready-time self ready-time))
</programlisting></informalexample><para>Sets a <type>GSource</type> 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 <parameter>ready_time</parameter> is 0) then the source will be
dispatched immediately.
</para>
<para>If <parameter>ready_time</parameter> is -1 then the source is never woken up on the basis
of the passage of time.
</para>
<para>Dispatching the source does not reset the ready time.  You should do
so yourself, from the source dispatch function.
</para>
<para>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.
</para>
<para>It is a no-op to call this function on a <type>GSource</type> which has already been
destroyed with <function>g_source_destroy()</function>.
</para>
<para>This API is only intended to be used by implementations of <type>GSource</type>.
Do not call this API on a <type>GSource</type> that you did not create.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>ready_time</para></td><td class="parameter_description"><para>the monotonic time at which the source will be ready,
             0 for &quot;immediately&quot;, -1 for &quot;never&quot;</para><para>Passed as <code>ready-time</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-static-name</title><informalexample><programlisting>(define-values () (source:set-static-name self name))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>name</para></td><td class="parameter_description"><para></para><para>Passed as <code>name</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (source:unref self))
</programlisting></informalexample><para>Decreases the reference count of a source by one. If the
resulting reference count is zero the source and associated
memory will be destroyed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a <type>GSource</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>source:remove?</title><informalexample><programlisting>(define-values (%return) (source:remove? tag))
</programlisting></informalexample><para>Removes the source with the given ID from the default main context. You must
use <function>g_source_destroy()</function> for sources added to a non-default main context.
</para>
<para>The ID of a <type>GSource</type> is given by <function>g_source_get_id()</function>, or will be
returned by the functions <function>g_source_attach()</function>, <function>g_idle_add()</function>,
<function>g_idle_add_full()</function>, <function>g_timeout_add()</function>, <function>g_timeout_add_full()</function>,
<function>g_child_watch_add()</function>, <function>g_child_watch_add_full()</function>, <function>g_io_add_watch()</function>, and
<function>g_io_add_watch_full()</function>.
</para>
<para>It is a programmer error to attempt to remove a non-existent source.
</para>
<para>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 <function>g_idle_add()</function>: 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tag</para></td><td class="parameter_description"><para>the ID of the source to remove.</para><para>Passed as <code>tag</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>source:remove-by-user-data?</title><informalexample><programlisting>(define-values (%return) (source:remove-by-user-data? user-data))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>user_data</para></td><td class="parameter_description"><para>the user_data for the callback.</para><para>Passed as <code>user-data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>source:set-name-by-id</title><informalexample><programlisting>(define-values () (source:set-name-by-id tag name))
</programlisting></informalexample><para>Sets the name of a source using its ID.
</para>
<para>This is a convenience utility to set source names from the return
value of <function>g_idle_add()</function>, <function>g_timeout_add()</function>, etc.
</para>
<para>It is a programmer error to attempt to set the name of a non-existent
source.
</para>
<para>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 <function>g_idle_add()</function>: 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tag</para></td><td class="parameter_description"><para>a <type>GSource</type> ID</para><para>Passed as <code>tag</code></para></td></tr><tr><td class="parameter_name"><para>name</para></td><td class="parameter_description"><para>debug name for the source</para><para>Passed as <code>name</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibSpawnError&gt;</refname></refnamediv><refsect1><title>Description</title><para>Error codes returned by spawning processes.</para></refsect1><refsect1><title>Members</title><refsect2><title>fork</title><remark>alias <code>G_SPAWN_ERROR_FORK</code></remark><para>Fork failed due to lack of memory.</para></refsect2><refsect2><title>read</title><remark>alias <code>G_SPAWN_ERROR_READ</code></remark><para>Read or select on pipes failed.</para></refsect2><refsect2><title>chdir</title><remark>alias <code>G_SPAWN_ERROR_CHDIR</code></remark><para>Changing to working directory failed.</para></refsect2><refsect2><title>acces</title><remark>alias <code>G_SPAWN_ERROR_ACCES</code></remark><para><function>execv()</function> returned <code>EACCES</code></para></refsect2><refsect2><title>perm</title><remark>alias <code>G_SPAWN_ERROR_PERM</code></remark><para><function>execv()</function> returned <code>EPERM</code></para></refsect2><refsect2><title>too-big</title><remark>alias <code>G_SPAWN_ERROR_TOO_BIG</code></remark><para><function>execv()</function> returned <code>E2BIG</code></para></refsect2><refsect2><title>2big</title><remark>alias <code>G_SPAWN_ERROR_2BIG</code></remark><para>deprecated alias for <constant>G_SPAWN_ERROR_TOO_BIG</constant> (deprecated since GLib 2.32)</para></refsect2><refsect2><title>noexec</title><remark>alias <code>G_SPAWN_ERROR_NOEXEC</code></remark><para><function>execv()</function> returned <code>ENOEXEC</code></para></refsect2><refsect2><title>nametoolong</title><remark>alias <code>G_SPAWN_ERROR_NAMETOOLONG</code></remark><para><function>execv()</function> returned <code>ENAMETOOLONG</code></para></refsect2><refsect2><title>noent</title><remark>alias <code>G_SPAWN_ERROR_NOENT</code></remark><para><function>execv()</function> returned <code>ENOENT</code></para></refsect2><refsect2><title>nomem</title><remark>alias <code>G_SPAWN_ERROR_NOMEM</code></remark><para><function>execv()</function> returned <code>ENOMEM</code></para></refsect2><refsect2><title>notdir</title><remark>alias <code>G_SPAWN_ERROR_NOTDIR</code></remark><para><function>execv()</function> returned <code>ENOTDIR</code></para></refsect2><refsect2><title>loop</title><remark>alias <code>G_SPAWN_ERROR_LOOP</code></remark><para><function>execv()</function> returned <code>ELOOP</code></para></refsect2><refsect2><title>txtbusy</title><remark>alias <code>G_SPAWN_ERROR_TXTBUSY</code></remark><para><function>execv()</function> returned <code>ETXTBUSY</code></para></refsect2><refsect2><title>io</title><remark>alias <code>G_SPAWN_ERROR_IO</code></remark><para><function>execv()</function> returned <code>EIO</code></para></refsect2><refsect2><title>nfile</title><remark>alias <code>G_SPAWN_ERROR_NFILE</code></remark><para><function>execv()</function> returned <code>ENFILE</code></para></refsect2><refsect2><title>mfile</title><remark>alias <code>G_SPAWN_ERROR_MFILE</code></remark><para><function>execv()</function> returned <code>EMFILE</code></para></refsect2><refsect2><title>inval</title><remark>alias <code>G_SPAWN_ERROR_INVAL</code></remark><para><function>execv()</function> returned <code>EINVAL</code></para></refsect2><refsect2><title>isdir</title><remark>alias <code>G_SPAWN_ERROR_ISDIR</code></remark><para><function>execv()</function> returned <code>EISDIR</code></para></refsect2><refsect2><title>libbad</title><remark>alias <code>G_SPAWN_ERROR_LIBBAD</code></remark><para><function>execv()</function> returned <code>ELIBBAD</code></para></refsect2><refsect2><title>failed</title><remark>alias <code>G_SPAWN_ERROR_FAILED</code></remark><para>Some other fatal failure,
  <code>error-&gt;message</code> should explain.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibSpawnFlags&gt;</refname></refnamediv><refsect1><title>Description</title><para>Flags passed to <function>g_spawn_sync()</function>, <function>g_spawn_async()</function> and <function>g_spawn_async_with_pipes()</function>.</para></refsect1><refsect1><title>Members</title><refsect2><title>default</title><remark>alias <code>G_SPAWN_DEFAULT</code></remark><para>no flags, default behaviour</para></refsect2><refsect2><title>leave-descriptors-open</title><remark>alias <code>G_SPAWN_LEAVE_DESCRIPTORS_OPEN</code></remark><para>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 <function>exec()</function> in the child.</para></refsect2><refsect2><title>do-not-reap-child</title><remark>alias <code>G_SPAWN_DO_NOT_REAP_CHILD</code></remark><para>the child will not be automatically reaped;
    you must use <function>g_child_watch_add()</function> yourself (or call <function>waitpid()</function> or handle
    <code>SIGCHLD</code> yourself), or the child will become a zombie.</para></refsect2><refsect2><title>search-path</title><remark>alias <code>G_SPAWN_SEARCH_PATH</code></remark><para><code>argv[0]</code> need not be an absolute path, it will be
    looked for in the user's <code>PATH</code>.</para></refsect2><refsect2><title>stdout-to-dev-null</title><remark>alias <code>G_SPAWN_STDOUT_TO_DEV_NULL</code></remark><para>the child's standard output will be discarded,
    instead of going to the same location as the parent's standard output.</para></refsect2><refsect2><title>stderr-to-dev-null</title><remark>alias <code>G_SPAWN_STDERR_TO_DEV_NULL</code></remark><para>the child's standard error will be discarded.</para></refsect2><refsect2><title>child-inherits-stdin</title><remark>alias <code>G_SPAWN_CHILD_INHERITS_STDIN</code></remark><para>the child will inherit the parent's standard
    input (by default, the child's standard input is attached to <code>/dev/null</code>).</para></refsect2><refsect2><title>file-and-argv-zero</title><remark>alias <code>G_SPAWN_FILE_AND_ARGV_ZERO</code></remark><para>the first element of <code>argv</code> is the file to
    execute, while the remaining elements are the actual argument vector
    to pass to the file. Normally <function>g_spawn_async_with_pipes()</function> uses <code>argv[0]</code>
    as the file to execute, and passes all of <code>argv</code> to the child.</para></refsect2><refsect2><title>search-path-from-envp</title><remark>alias <code>G_SPAWN_SEARCH_PATH_FROM_ENVP</code></remark><para>if <code>argv[0]</code> is not an absolute path,
    it will be looked for in the <code>PATH</code> from the passed child environment.
    Since: 2.34</para></refsect2><refsect2><title>cloexec-pipes</title><remark>alias <code>G_SPAWN_CLOEXEC_PIPES</code></remark><para>create all pipes with the <code>O_CLOEXEC</code> flag set.
    Since: 2.40</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GString&gt;</refname></refnamediv><refsect1><title>Description</title><para>The GString struct contains the public fields of a GString.</para></refsect1><refsect1><title>Functions</title><refsect2><title>append</title><informalexample><programlisting>(define-values (%return) (string:append self val))
</programlisting></informalexample><para>Adds a string onto the end of a <type>GString</type>, expanding
it if necessary.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>the string to append onto the end of <parameter>string</parameter></para><para>Passed as <code>val</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>append-c</title><informalexample><programlisting>(define-values (%return) (string:append-c self c))
</programlisting></informalexample><para>Adds a byte onto the end of a <type>GString</type>, expanding
it if necessary.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>the byte to append onto the end of <parameter>string</parameter></para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>append-len</title><informalexample><programlisting>(define-values (%return) (string:append-len self val len))
</programlisting></informalexample><para>Appends <parameter>len</parameter> bytes of <parameter>val</parameter> to <parameter>string</parameter>.
</para>
<para>If <parameter>len</parameter> is positive, <parameter>val</parameter> may contain embedded nuls and need
not be nul-terminated. It is the caller's responsibility to
ensure that <parameter>val</parameter> has at least <parameter>len</parameter> addressable bytes.
</para>
<para>If <parameter>len</parameter> is negative, <parameter>val</parameter> must be nul-terminated and <parameter>len</parameter>
is considered to request the entire string length. This
makes <function>g_string_append_len()</function> equivalent to <function>g_string_append()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>bytes to append</para><para>Passed as <code>val</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>number of bytes of <parameter>val</parameter> to use, or -1 for all of <parameter>val</parameter></para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>append-unichar</title><informalexample><programlisting>(define-values (%return) (string:append-unichar self wc))
</programlisting></informalexample><para>Converts a Unicode character into UTF-8, and appends it
to the string.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>wc</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>wc</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>append-uri-escaped</title><informalexample><programlisting>(define-values
  (%return)
  (string:append-uri-escaped self unescaped reserved-chars-allowed allow-utf8))
</programlisting></informalexample><para>Appends <parameter>unescaped</parameter> to <parameter>string</parameter>, escaping any characters that
are reserved in URIs using URI-style escape sequences.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>unescaped</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>unescaped</code></para></td></tr><tr><td class="parameter_name"><para>reserved_chars_allowed</para></td><td class="parameter_description"><para>a string of reserved characters allowed
    to be used, or <constant>NULL</constant></para><para>Passed as <code>reserved-chars-allowed</code></para></td></tr><tr><td class="parameter_name"><para>allow_utf8</para></td><td class="parameter_description"><para>set <constant>TRUE</constant> if the escaped string may include UTF8 characters</para><para>Passed as <code>allow-utf8</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ascii-down</title><informalexample><programlisting>(define-values (%return) (string:ascii-down self))
</programlisting></informalexample><para>Converts all uppercase ASCII letters to lowercase ASCII letters.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a GString</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ascii-up</title><informalexample><programlisting>(define-values (%return) (string:ascii-up self))
</programlisting></informalexample><para>Converts all lowercase ASCII letters to uppercase ASCII letters.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a GString</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>assign</title><informalexample><programlisting>(define-values (%return) (string:assign self rval))
</programlisting></informalexample><para>Copies the bytes from a string into a <type>GString</type>,
destroying any previous contents. It is rather like
the standard <function>strcpy()</function> function, except that you do not
have to worry about having enough space to copy the string.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the destination <type>GString</type>. Its current contents
         are destroyed.</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>rval</para></td><td class="parameter_description"><para>the string to copy into <parameter>string</parameter></para><para>Passed as <code>rval</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>down</title><informalexample><programlisting>(define-values (%return) (string:down self))
</programlisting></informalexample><para>Converts a <type>GString</type> to lowercase.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>equal?</title><informalexample><programlisting>(define-values (%return) (string:equal? self v2))
</programlisting></informalexample><para>Compares two strings for equality, returning <constant>TRUE</constant> if they are equal.
For use with <type>GHashTable</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>v</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>v2</para></td><td class="parameter_description"><para>another <type>GString</type></para><para>Passed as <code>v2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>erase</title><informalexample><programlisting>(define-values (%return) (string:erase self pos len))
</programlisting></informalexample><para>Removes <parameter>len</parameter> bytes from a <type>GString</type>, starting at position <parameter>pos</parameter>.
The rest of the <type>GString</type> is shifted down to fill the gap.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>pos</para></td><td class="parameter_description"><para>the position of the content to remove</para><para>Passed as <code>pos</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the number of bytes to remove, or -1 to remove all
      following bytes</para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>free</title><informalexample><programlisting>(define-values (%return) (string:free self free-segment))
</programlisting></informalexample><para>Frees the memory allocated for the <type>GString</type>.
If <parameter>free_segment</parameter> is <constant>TRUE</constant> it also frees the character data.  If
it's <constant>FALSE</constant>, the caller gains ownership of the buffer and must
free it after use with <function>g_free()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>free_segment</para></td><td class="parameter_description"><para>if <constant>TRUE</constant>, the actual character data is freed as well</para><para>Passed as <code>free-segment</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>free-to-bytes</title><informalexample><programlisting>(define-values (%return) (string:free-to-bytes self))
</programlisting></informalexample><para>Transfers ownership of the contents of <parameter>string</parameter> to a newly allocated
<type>GBytes</type>.  The <type>GString</type> structure itself is deallocated, and it is
therefore invalid to use <parameter>string</parameter> after invoking this function.
</para>
<para>Note that while <type>GString</type> ensures that its buffer always has a
trailing nul character (not reflected in its &quot;len&quot;), the returned
<type>GBytes</type> does not include this extra nul; i.e. it has length exactly
equal to the &quot;len&quot; member.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash</title><informalexample><programlisting>(define-values (%return) (string:hash self))
</programlisting></informalexample><para>Creates a hash code for <parameter>str</parameter>; for use with <type>GHashTable</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a string to hash</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>insert</title><informalexample><programlisting>(define-values (%return) (string:insert self pos val))
</programlisting></informalexample><para>Inserts a copy of a string into a <type>GString</type>,
expanding it if necessary.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>pos</para></td><td class="parameter_description"><para>the position to insert the copy of the string</para><para>Passed as <code>pos</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>the string to insert</para><para>Passed as <code>val</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>insert-c</title><informalexample><programlisting>(define-values (%return) (string:insert-c self pos c))
</programlisting></informalexample><para>Inserts a byte into a <type>GString</type>, expanding it if necessary.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>pos</para></td><td class="parameter_description"><para>the position to insert the byte</para><para>Passed as <code>pos</code></para></td></tr><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>the byte to insert</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>insert-len</title><informalexample><programlisting>(define-values (%return) (string:insert-len self pos val len))
</programlisting></informalexample><para>Inserts <parameter>len</parameter> bytes of <parameter>val</parameter> into <parameter>string</parameter> at <parameter>pos</parameter>.
</para>
<para>If <parameter>len</parameter> is positive, <parameter>val</parameter> may contain embedded nuls and need
not be nul-terminated. It is the caller's responsibility to
ensure that <parameter>val</parameter> has at least <parameter>len</parameter> addressable bytes.
</para>
<para>If <parameter>len</parameter> is negative, <parameter>val</parameter> must be nul-terminated and <parameter>len</parameter>
is considered to request the entire string length.
</para>
<para>If <parameter>pos</parameter> is -1, bytes are inserted at the end of the string.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>pos</para></td><td class="parameter_description"><para>position in <parameter>string</parameter> where insertion should
      happen, or -1 for at the end</para><para>Passed as <code>pos</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>bytes to insert</para><para>Passed as <code>val</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>number of bytes of <parameter>val</parameter> to insert, or -1 for all of <parameter>val</parameter></para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>insert-unichar</title><informalexample><programlisting>(define-values (%return) (string:insert-unichar self pos wc))
</programlisting></informalexample><para>Converts a Unicode character into UTF-8, and insert it
into the string at the given position.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>pos</para></td><td class="parameter_description"><para>the position at which to insert character, or -1
    to append at the end of the string</para><para>Passed as <code>pos</code></para></td></tr><tr><td class="parameter_name"><para>wc</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>wc</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>overwrite</title><informalexample><programlisting>(define-values (%return) (string:overwrite self pos val))
</programlisting></informalexample><para>Overwrites part of a string, lengthening it if necessary.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>pos</para></td><td class="parameter_description"><para>the position at which to start overwriting</para><para>Passed as <code>pos</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>the string that will overwrite the <parameter>string</parameter> starting at <parameter>pos</parameter></para><para>Passed as <code>val</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>overwrite-len</title><informalexample><programlisting>(define-values (%return) (string:overwrite-len self pos val len))
</programlisting></informalexample><para>Overwrites part of a string, lengthening it if necessary.
This function will work with embedded nuls.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>pos</para></td><td class="parameter_description"><para>the position at which to start overwriting</para><para>Passed as <code>pos</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>the string that will overwrite the <parameter>string</parameter> starting at <parameter>pos</parameter></para><para>Passed as <code>val</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the number of bytes to write from <parameter>val</parameter></para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>prepend</title><informalexample><programlisting>(define-values (%return) (string:prepend self val))
</programlisting></informalexample><para>Adds a string on to the start of a <type>GString</type>,
expanding it if necessary.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>the string to prepend on the start of <parameter>string</parameter></para><para>Passed as <code>val</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>prepend-c</title><informalexample><programlisting>(define-values (%return) (string:prepend-c self c))
</programlisting></informalexample><para>Adds a byte onto the start of a <type>GString</type>,
expanding it if necessary.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>the byte to prepend on the start of the <type>GString</type></para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>prepend-len</title><informalexample><programlisting>(define-values (%return) (string:prepend-len self val len))
</programlisting></informalexample><para>Prepends <parameter>len</parameter> bytes of <parameter>val</parameter> to <parameter>string</parameter>.
</para>
<para>If <parameter>len</parameter> is positive, <parameter>val</parameter> may contain embedded nuls and need
not be nul-terminated. It is the caller's responsibility to
ensure that <parameter>val</parameter> has at least <parameter>len</parameter> addressable bytes.
</para>
<para>If <parameter>len</parameter> is negative, <parameter>val</parameter> must be nul-terminated and <parameter>len</parameter>
is considered to request the entire string length. This
makes <function>g_string_prepend_len()</function> equivalent to <function>g_string_prepend()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>bytes to prepend</para><para>Passed as <code>val</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>number of bytes in <parameter>val</parameter> to prepend, or -1 for all of <parameter>val</parameter></para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>prepend-unichar</title><informalexample><programlisting>(define-values (%return) (string:prepend-unichar self wc))
</programlisting></informalexample><para>Converts a Unicode character into UTF-8, and prepends it
to the string.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>wc</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>wc</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>replace</title><informalexample><programlisting>(define-values (%return) (string:replace self find replace limit))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>find</para></td><td class="parameter_description"><para></para><para>Passed as <code>find</code></para></td></tr><tr><td class="parameter_name"><para>replace</para></td><td class="parameter_description"><para></para><para>Passed as <code>replace</code></para></td></tr><tr><td class="parameter_name"><para>limit</para></td><td class="parameter_description"><para></para><para>Passed as <code>limit</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-size</title><informalexample><programlisting>(define-values (%return) (string:set-size self len))
</programlisting></informalexample><para>Sets the length of a <type>GString</type>. 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-&gt;str[string-&gt;len] will be a nul byte.)</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the new length</para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>truncate</title><informalexample><programlisting>(define-values (%return) (string:truncate self len))
</programlisting></informalexample><para>Cuts off the end of the GString, leaving the first <parameter>len</parameter> bytes.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the new size of <parameter>string</parameter></para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>up</title><informalexample><programlisting>(define-values (%return) (string:up self))
</programlisting></informalexample><para>Converts a <type>GString</type> to uppercase.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a <type>GString</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibTestFileType&gt;</refname></refnamediv><refsect1><title>Description</title><para>The type of file to return the filename for, when used with
<function>g_test_build_filename()</function>.
</para>
<para>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
<code>EXTRA_DIST</code> or <code>dist_schema_DATA</code>
sense, in which case they will always be in the srcdir) or built (in
the <code>BUILT_SOURCES</code> sense, in which case they will
always be in the builddir).
</para>
<para>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.</para></refsect1><refsect1><title>Members</title><refsect2><title>dist</title><remark>alias <code>G_TEST_DIST</code></remark><para>a file that was included in the distribution tarball</para></refsect2><refsect2><title>built</title><remark>alias <code>G_TEST_BUILT</code></remark><para>a file that was built on the compiling machine</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibTestLogType&gt;</refname></refnamediv><refsect1><title>Members</title><refsect2><title>none</title><remark>alias <code>G_TEST_LOG_NONE</code></remark><para>Undocumented</para></refsect2><refsect2><title>error</title><remark>alias <code>G_TEST_LOG_ERROR</code></remark><para>Undocumented</para></refsect2><refsect2><title>start-binary</title><remark>alias <code>G_TEST_LOG_START_BINARY</code></remark><para>Undocumented</para></refsect2><refsect2><title>list-case</title><remark>alias <code>G_TEST_LOG_LIST_CASE</code></remark><para>Undocumented</para></refsect2><refsect2><title>skip-case</title><remark>alias <code>G_TEST_LOG_SKIP_CASE</code></remark><para>Undocumented</para></refsect2><refsect2><title>start-case</title><remark>alias <code>G_TEST_LOG_START_CASE</code></remark><para>Undocumented</para></refsect2><refsect2><title>stop-case</title><remark>alias <code>G_TEST_LOG_STOP_CASE</code></remark><para>Undocumented</para></refsect2><refsect2><title>min-result</title><remark>alias <code>G_TEST_LOG_MIN_RESULT</code></remark><para>Undocumented</para></refsect2><refsect2><title>max-result</title><remark>alias <code>G_TEST_LOG_MAX_RESULT</code></remark><para>Undocumented</para></refsect2><refsect2><title>message</title><remark>alias <code>G_TEST_LOG_MESSAGE</code></remark><para>Undocumented</para></refsect2><refsect2><title>start-suite</title><remark>alias <code>G_TEST_LOG_START_SUITE</code></remark><para>Undocumented</para></refsect2><refsect2><title>stop-suite</title><remark>alias <code>G_TEST_LOG_STOP_SUITE</code></remark><para>Undocumented</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibTestResult&gt;</refname></refnamediv><refsect1><title>Members</title><refsect2><title>success</title><remark>alias <code>G_TEST_RUN_SUCCESS</code></remark><para>Undocumented</para></refsect2><refsect2><title>skipped</title><remark>alias <code>G_TEST_RUN_SKIPPED</code></remark><para>Undocumented</para></refsect2><refsect2><title>failure</title><remark>alias <code>G_TEST_RUN_FAILURE</code></remark><para>Undocumented</para></refsect2><refsect2><title>incomplete</title><remark>alias <code>G_TEST_RUN_INCOMPLETE</code></remark><para>Undocumented</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibTestSubprocessFlags&gt;</refname></refnamediv><refsect1><title>Description</title><para>Flags to pass to <function>g_test_trap_subprocess()</function> to control input and output.
</para>
<para>Note that in contrast with <function>g_test_trap_fork()</function>, the default is to
not show stdout and stderr.</para></refsect1><refsect1><title>Members</title><refsect2><title>stdin</title><remark>alias <code>G_TEST_SUBPROCESS_INHERIT_STDIN</code></remark><para>If this flag is given, the child
    process will inherit the parent's stdin. Otherwise, the child's
    stdin is redirected to <code>/dev/null</code>.</para></refsect2><refsect2><title>stdout</title><remark>alias <code>G_TEST_SUBPROCESS_INHERIT_STDOUT</code></remark><para>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 <function>g_test_trap_assert_stdout()</function>.</para></refsect2><refsect2><title>stderr</title><remark>alias <code>G_TEST_SUBPROCESS_INHERIT_STDERR</code></remark><para>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 <function>g_test_trap_assert_stderr()</function>.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GThread&gt;</refname></refnamediv><refsect1><title>Description</title><para>The <type>GThread</type> struct represents a running thread. This struct
is returned by <function>g_thread_new()</function> or <function>g_thread_try_new()</function>. You can
obtain the <type>GThread</type> struct representing the current thread by
calling <function>g_thread_self()</function>.
</para>
<para>GThread is refcounted, see <function>g_thread_ref()</function> and <function>g_thread_unref()</function>.
The thread represented by it holds a reference while it is running,
and <function>g_thread_join()</function> consumes the reference that it is given, so
it is normally not necessary to manage GThread references
explicitly.
</para>
<para>The structure is opaque -- none of its fields may be directly
accessed.</para></refsect1><refsect1><title>Functions</title><refsect2><title>join</title><informalexample><programlisting>(define-values (%return) (thread:join self))
</programlisting></informalexample><para>Waits until <parameter>thread</parameter> finishes, i.e. the function <parameter>func</parameter>, as
given to <function>g_thread_new()</function>, returns or <function>g_thread_exit()</function> is called.
If <parameter>thread</parameter> has already terminated, then <function>g_thread_join()</function>
returns immediately.
</para>
<para>Any thread can wait for any other thread by calling <function>g_thread_join()</function>,
not just its 'creator'. Calling <function>g_thread_join()</function> from multiple threads
for the same <parameter>thread</parameter> leads to undefined behaviour.
</para>
<para>The value returned by <parameter>func</parameter> or given to <function>g_thread_exit()</function> is
returned by this function.
</para>
<para><function>g_thread_join()</function> consumes the reference to the passed-in <parameter>thread</parameter>.
This will usually cause the <type>GThread</type> struct and associated resources
to be freed. Use <function>g_thread_ref()</function> to obtain an extra reference if you
want to keep the GThread alive beyond the <function>g_thread_join()</function> call.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>thread</para></td><td class="parameter_description"><para>a <type>GThread</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref</title><informalexample><programlisting>(define-values (%return) (thread:ref self))
</programlisting></informalexample><para>Increase the reference count on <parameter>thread</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>thread</para></td><td class="parameter_description"><para>a <type>GThread</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (thread:unref self))
</programlisting></informalexample><para>Decrease the reference count on <parameter>thread</parameter>, possibly freeing all
resources associated with it.
</para>
<para>Note that each thread holds a reference to its <type>GThread</type> while
it is running, so it is safe to drop your own reference to it
if you don't need it anymore.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>thread</para></td><td class="parameter_description"><para>a <type>GThread</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>thread:try-new</title><informalexample><programlisting>(define-values (%return) (thread:try-new name func data))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>name</para></td><td class="parameter_description"><para></para><para>Passed as <code>name</code></para></td></tr><tr><td class="parameter_name"><para>func</para></td><td class="parameter_description"><para></para><para>Passed as <code>func</code></para></td></tr><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para></para><para>Passed as <code>data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>thread:new</title><informalexample><programlisting>(define-values (%return) (thread:new name func data))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>name</para></td><td class="parameter_description"><para></para><para>Passed as <code>name</code></para></td></tr><tr><td class="parameter_name"><para>func</para></td><td class="parameter_description"><para></para><para>Passed as <code>func</code></para></td></tr><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para></para><para>Passed as <code>data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>thread:error-quark</title><informalexample><programlisting>(define-values (%return) (thread:error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>thread:exit</title><informalexample><programlisting>(define-values () (thread:exit retval))
</programlisting></informalexample><para>Terminates the current thread.
</para>
<para>If another thread is waiting for us using <function>g_thread_join()</function> then the
waiting thread will be woken up and get <parameter>retval</parameter> as the return value
of <function>g_thread_join()</function>.
</para>
<para>Calling <function>g_thread_exit()</function> with a parameter <parameter>retval</parameter> is equivalent to
returning <parameter>retval</parameter> from the function <parameter>func</parameter>, as given to <function>g_thread_new()</function>.
</para>
<para>You must only call <function>g_thread_exit()</function> from a thread that you created
yourself with <function>g_thread_new()</function> or related APIs. You must not call
this function from a thread created with another threading library
or or from within a <type>GThreadPool</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>retval</para></td><td class="parameter_description"><para>the return value of this thread</para><para>Passed as <code>retval</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>thread:self</title><informalexample><programlisting>(define-values (%return) (thread:self))
</programlisting></informalexample><para>This function returns the <type>GThread</type> corresponding to the
current thread. Note that this function does not increase
the reference count of the returned struct.
</para>
<para>This function will return a <type>GThread</type> 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 <function>g_thread_join()</function>) on these threads.</para></refsect2><refsect2><title>thread:yield</title><informalexample><programlisting>(define-values () (thread:yield))
</programlisting></informalexample><para>Causes the calling thread to voluntarily relinquish the CPU, so
that other threads can run.
</para>
<para>This function is often used as a method to make busy wait less evil.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibThreadError&gt;</refname></refnamediv><refsect1><title>Description</title><para>Possible errors of thread related functions.</para></refsect1><refsect1><title>Members</title><refsect2><title>thread-error-again</title><remark>alias <code>G_THREAD_ERROR_AGAIN</code></remark><para>a thread couldn't be created due to resource
                       shortage. Try again later.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibTimeType&gt;</refname></refnamediv><refsect1><title>Description</title><para>Disambiguates a given time in two ways.
</para>
<para>First, specifies if the given time is in universal or local time.
</para>
<para>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).</para></refsect1><refsect1><title>Members</title><refsect2><title>standard</title><remark>alias <code>G_TIME_TYPE_STANDARD</code></remark><para>the time is in local standard time</para></refsect2><refsect2><title>daylight</title><remark>alias <code>G_TIME_TYPE_DAYLIGHT</code></remark><para>the time is in local daylight time</para></refsect2><refsect2><title>universal</title><remark>alias <code>G_TIME_TYPE_UNIVERSAL</code></remark><para>the time is in UTC</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GTimeZone&gt;</refname></refnamediv><refsect1><title>Description</title><para><type>GTimeZone</type> is an opaque structure whose members cannot be accessed
directly.</para></refsect1><refsect1><title>Functions</title><refsect2><title>adjust-time</title><informalexample><programlisting>(define-values (%return) (time-zone:adjust-time self type time-))
</programlisting></informalexample><para>Finds an interval within <parameter>tz</parameter> that corresponds to the given <parameter>time_</parameter>,
possibly adjusting <parameter>time_</parameter> if required to fit into an interval.
The meaning of <parameter>time_</parameter> depends on <parameter>type</parameter>.
</para>
<para>This function is similar to <function>g_time_zone_find_interval()</function>, with the
difference that it always succeeds (by making the adjustments
described below).
</para>
<para>In any of the cases where <function>g_time_zone_find_interval()</function> succeeds then
this function returns the same value, without modifying <parameter>time_</parameter>.
</para>
<para>This function may, however, modify <parameter>time_</parameter> in order to deal with
non-existent times.  If the non-existent local <parameter>time_</parameter> of 02:30 were
requested on March 14th 2010 in Toronto then this function would
adjust <parameter>time_</parameter> to be 03:00 and return the interval containing the
adjusted time.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tz</para></td><td class="parameter_description"><para>a <type>GTimeZone</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>the <type>GTimeType</type> of <parameter>time_</parameter></para><para>Passed as <code>type</code></para></td></tr><tr><td class="parameter_name"><para>time_</para></td><td class="parameter_description"><para>a pointer to a number of seconds since January 1, 1970</para><para>Passed as <code>time-</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>find-interval</title><informalexample><programlisting>(define-values (%return) (time-zone:find-interval self type time-))
</programlisting></informalexample><para>Finds an interval within <parameter>tz</parameter> that corresponds to the given <parameter>time_</parameter>.
The meaning of <parameter>time_</parameter> depends on <parameter>type</parameter>.
</para>
<para>If <parameter>type</parameter> is <constant>G_TIME_TYPE_UNIVERSAL</constant> then this function will always
succeed (since universal time is monotonic and continuous).
</para>
<para>Otherwise <parameter>time_</parameter> is treated as local time.  The distinction between
<constant>G_TIME_TYPE_STANDARD</constant> and <constant>G_TIME_TYPE_DAYLIGHT</constant> is ignored except in
the case that the given <parameter>time_</parameter> 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 <parameter>type</parameter> would result in a
different interval being returned.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tz</para></td><td class="parameter_description"><para>a <type>GTimeZone</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>the <type>GTimeType</type> of <parameter>time_</parameter></para><para>Passed as <code>type</code></para></td></tr><tr><td class="parameter_name"><para>time_</para></td><td class="parameter_description"><para>a number of seconds since January 1, 1970</para><para>Passed as <code>time-</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-abbreviation</title><informalexample><programlisting>(define-values (%return) (time-zone:get-abbreviation self interval))
</programlisting></informalexample><para>Determines the time zone abbreviation to be used during a particular
<parameter>interval</parameter> of time in the time zone <parameter>tz</parameter>.
</para>
<para>For example, in Toronto this is currently &quot;EST&quot; during the winter
months and &quot;EDT&quot; during the summer months when daylight savings time
is in effect.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tz</para></td><td class="parameter_description"><para>a <type>GTimeZone</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>interval</para></td><td class="parameter_description"><para>an interval within the timezone</para><para>Passed as <code>interval</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-identifier</title><informalexample><programlisting>(define-values (%return) (time-zone:get-identifier self))
</programlisting></informalexample><para>Get the identifier of this <type>GTimeZone</type>, as passed to <function>g_time_zone_new()</function>.
If the identifier passed at construction time was not recognised, <code>UTC</code> will
be returned. If it was <constant>NULL</constant>, the identifier of the local timezone at
construction time will be returned.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tz</para></td><td class="parameter_description"><para>a <type>GTimeZone</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-offset</title><informalexample><programlisting>(define-values (%return) (time-zone:get-offset self interval))
</programlisting></informalexample><para>Determines the offset to UTC in effect during a particular <parameter>interval</parameter>
of time in the time zone <parameter>tz</parameter>.
</para>
<para>The offset is the number of seconds that you add to UTC time to
arrive at local time for <parameter>tz</parameter> (ie: negative numbers for time zones
west of GMT, positive numbers for east).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tz</para></td><td class="parameter_description"><para>a <type>GTimeZone</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>interval</para></td><td class="parameter_description"><para>an interval within the timezone</para><para>Passed as <code>interval</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-dst?</title><informalexample><programlisting>(define-values (%return) (time-zone:is-dst? self interval))
</programlisting></informalexample><para>Determines if daylight savings time is in effect during a particular
<parameter>interval</parameter> of time in the time zone <parameter>tz</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tz</para></td><td class="parameter_description"><para>a <type>GTimeZone</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>interval</para></td><td class="parameter_description"><para>an interval within the timezone</para><para>Passed as <code>interval</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref</title><informalexample><programlisting>(define-values (%return) (time-zone:ref self))
</programlisting></informalexample><para>Increases the reference count on <parameter>tz</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tz</para></td><td class="parameter_description"><para>a <type>GTimeZone</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (time-zone:unref self))
</programlisting></informalexample><para>Decreases the reference count on <parameter>tz</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tz</para></td><td class="parameter_description"><para>a <type>GTimeZone</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>time-zone:new-utc</title><informalexample><programlisting>(define-values (%return) (time-zone:new-utc))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>time-zone:new-offset</title><informalexample><programlisting>(define-values (%return) (time-zone:new-offset seconds))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>seconds</para></td><td class="parameter_description"><para></para><para>Passed as <code>seconds</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>time-zone:new-local</title><informalexample><programlisting>(define-values (%return) (time-zone:new-local))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>time-zone:new-identifier</title><informalexample><programlisting>(define-values (%return) (time-zone:new-identifier identifier))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>identifier</para></td><td class="parameter_description"><para></para><para>Passed as <code>identifier</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>time-zone:new</title><informalexample><programlisting>(define-values (%return) (time-zone:new identifier))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>identifier</para></td><td class="parameter_description"><para></para><para>Passed as <code>identifier</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibTokenType&gt;</refname></refnamediv><refsect1><title>Description</title><para>The possible types of token returned from each
<function>g_scanner_get_next_token()</function> call.</para></refsect1><refsect1><title>Members</title><refsect2><title>eof</title><remark>alias <code>G_TOKEN_EOF</code></remark><para>the end of the file</para></refsect2><refsect2><title>left-paren</title><remark>alias <code>G_TOKEN_LEFT_PAREN</code></remark><para>a '(' character</para></refsect2><refsect2><title>right-paren</title><remark>alias <code>G_TOKEN_RIGHT_PAREN</code></remark><para>a ')' character</para></refsect2><refsect2><title>left-curly</title><remark>alias <code>G_TOKEN_LEFT_CURLY</code></remark><para>a '{' character</para></refsect2><refsect2><title>right-curly</title><remark>alias <code>G_TOKEN_RIGHT_CURLY</code></remark><para>a '}' character</para></refsect2><refsect2><title>left-brace</title><remark>alias <code>G_TOKEN_LEFT_BRACE</code></remark><para>a '[' character</para></refsect2><refsect2><title>right-brace</title><remark>alias <code>G_TOKEN_RIGHT_BRACE</code></remark><para>a ']' character</para></refsect2><refsect2><title>equal-sign</title><remark>alias <code>G_TOKEN_EQUAL_SIGN</code></remark><para>a '=' character</para></refsect2><refsect2><title>comma</title><remark>alias <code>G_TOKEN_COMMA</code></remark><para>a ',' character</para></refsect2><refsect2><title>none</title><remark>alias <code>G_TOKEN_NONE</code></remark><para>not a token</para></refsect2><refsect2><title>error</title><remark>alias <code>G_TOKEN_ERROR</code></remark><para>an error occurred</para></refsect2><refsect2><title>char</title><remark>alias <code>G_TOKEN_CHAR</code></remark><para>a character</para></refsect2><refsect2><title>binary</title><remark>alias <code>G_TOKEN_BINARY</code></remark><para>a binary integer</para></refsect2><refsect2><title>octal</title><remark>alias <code>G_TOKEN_OCTAL</code></remark><para>an octal integer</para></refsect2><refsect2><title>int</title><remark>alias <code>G_TOKEN_INT</code></remark><para>an integer</para></refsect2><refsect2><title>hex</title><remark>alias <code>G_TOKEN_HEX</code></remark><para>a hex integer</para></refsect2><refsect2><title>float</title><remark>alias <code>G_TOKEN_FLOAT</code></remark><para>a floating point number</para></refsect2><refsect2><title>string</title><remark>alias <code>G_TOKEN_STRING</code></remark><para>a string</para></refsect2><refsect2><title>symbol</title><remark>alias <code>G_TOKEN_SYMBOL</code></remark><para>a symbol</para></refsect2><refsect2><title>identifier</title><remark>alias <code>G_TOKEN_IDENTIFIER</code></remark><para>an identifier</para></refsect2><refsect2><title>identifier-null</title><remark>alias <code>G_TOKEN_IDENTIFIER_NULL</code></remark><para>a null identifier</para></refsect2><refsect2><title>comment-single</title><remark>alias <code>G_TOKEN_COMMENT_SINGLE</code></remark><para>one line comment</para></refsect2><refsect2><title>comment-multi</title><remark>alias <code>G_TOKEN_COMMENT_MULTI</code></remark><para>multi line comment</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibTraverseFlags&gt;</refname></refnamediv><refsect1><title>Description</title><para>Specifies which nodes are visited during several of the tree
functions, including <function>g_node_traverse()</function> and <function>g_node_find()</function>.</para></refsect1><refsect1><title>Members</title><refsect2><title>leaves</title><remark>alias <code>G_TRAVERSE_LEAVES</code></remark><para>only leaf nodes should be visited. This name has
                    been introduced in 2.6, for older version use
                    <constant>G_TRAVERSE_LEAFS</constant>.</para></refsect2><refsect2><title>non-leaves</title><remark>alias <code>G_TRAVERSE_NON_LEAVES</code></remark><para>only non-leaf nodes should be visited. This
                        name has been introduced in 2.6, for older
                        version use <constant>G_TRAVERSE_NON_LEAFS</constant>.</para></refsect2><refsect2><title>all</title><remark>alias <code>G_TRAVERSE_ALL</code></remark><para>all nodes should be visited.</para></refsect2><refsect2><title>mask</title><remark>alias <code>G_TRAVERSE_MASK</code></remark><para>a mask of all traverse flags.</para></refsect2><refsect2><title>leafs</title><remark>alias <code>G_TRAVERSE_LEAFS</code></remark><para>identical to <constant>G_TRAVERSE_LEAVES</constant>.</para></refsect2><refsect2><title>non-leafs</title><remark>alias <code>G_TRAVERSE_NON_LEAFS</code></remark><para>identical to <constant>G_TRAVERSE_NON_LEAVES</constant>.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibTraverseType&gt;</refname></refnamediv><refsect1><title>Description</title><para>Specifies the type of traversal performed by <function>g_tree_traverse()</function>,
<function>g_node_traverse()</function> and <function>g_node_find()</function>. The different orders are
illustrated here:
- In order: A, B, C, D, E, F, G, H, I
  ![](Sorted_binary_tree_inorder.svg)
- Pre order: F, B, A, D, C, E, G, I, H
  ![](Sorted_binary_tree_preorder.svg)
- Post order: A, C, E, D, B, H, I, G, F
  ![](Sorted_binary_tree_postorder.svg)
- Level order: F, B, G, A, D, I, C, E, H
  ![](Sorted_binary_tree_breadth-first_traversal.svg)</para></refsect1><refsect1><title>Members</title><refsect2><title>in-order</title><remark>alias <code>G_IN_ORDER</code></remark><para>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.</para></refsect2><refsect2><title>pre-order</title><remark>alias <code>G_PRE_ORDER</code></remark><para>visits a node, then its children.</para></refsect2><refsect2><title>post-order</title><remark>alias <code>G_POST_ORDER</code></remark><para>visits the node's children, then the node itself.</para></refsect2><refsect2><title>level-order</title><remark>alias <code>G_LEVEL_ORDER</code></remark><para>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.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GTree&gt;</refname></refnamediv><refsect1><title>Description</title><para>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.</para></refsect1><refsect1><title>Functions</title><refsect2><title>destroy</title><informalexample><programlisting>(define-values () (tree:destroy self))
</programlisting></informalexample><para>Removes all keys and values from the <type>GTree</type> and decreases its
reference count by one. If keys and/or values are dynamically
allocated, you should either free them first or create the <type>GTree</type>
using <function>g_tree_new_full()</function>. In the latter case the destroy functions
you supplied will be called on all keys and values before destroying
the <type>GTree</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tree</para></td><td class="parameter_description"><para>a <type>GTree</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>height</title><informalexample><programlisting>(define-values (%return) (tree:height self))
</programlisting></informalexample><para>Gets the height of a <type>GTree</type>.
</para>
<para>If the <type>GTree</type> contains no nodes, the height is 0.
If the <type>GTree</type> contains only one root node the height is 1.
If the root node has children the height is 2, etc.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tree</para></td><td class="parameter_description"><para>a <type>GTree</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>insert</title><informalexample><programlisting>(define-values () (tree:insert self key value))
</programlisting></informalexample><para>Inserts a key/value pair into a <type>GTree</type>.
</para>
<para>If the given key already exists in the <type>GTree</type> its corresponding value
is set to the new value. If you supplied a <parameter>value_destroy_func</parameter> when
creating the <type>GTree</type>, the old value is freed using that function. If
you supplied a <parameter>key_destroy_func</parameter> when creating the <type>GTree</type>, the passed
key is freed using that function.
</para>
<para>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)).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tree</para></td><td class="parameter_description"><para>a <type>GTree</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to insert</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>the value corresponding to the key</para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>lookup</title><informalexample><programlisting>(define-values (%return) (tree:lookup self key))
</programlisting></informalexample><para>Gets the value corresponding to the given key. Since a <type>GTree</type> 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).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tree</para></td><td class="parameter_description"><para>a <type>GTree</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to look up</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>lookup-extended</title><informalexample><programlisting>(define-values
  (%return orig-key value)
  (tree:lookup-extended self lookup-key))
</programlisting></informalexample><para>Looks up a key in the <type>GTree</type>, 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
<function>g_tree_remove()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tree</para></td><td class="parameter_description"><para>a <type>GTree</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>lookup_key</para></td><td class="parameter_description"><para>the key to look up</para><para>Passed as <code>lookup-key</code></para></td></tr><tr><td class="parameter_name"><para>orig_key</para></td><td class="parameter_description"><para>returns the original key</para><para>Passed as <code>orig-key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>returns the value associated with the key</para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>nnodes</title><informalexample><programlisting>(define-values (%return) (tree:nnodes self))
</programlisting></informalexample><para>Gets the number of nodes in a <type>GTree</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tree</para></td><td class="parameter_description"><para>a <type>GTree</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref</title><informalexample><programlisting>(define-values (%return) (tree:ref self))
</programlisting></informalexample><para>Increments the reference count of <parameter>tree</parameter> by one.
</para>
<para>It is safe to call this function from any thread.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tree</para></td><td class="parameter_description"><para>a <type>GTree</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>remove?</title><informalexample><programlisting>(define-values (%return) (tree:remove? self key))
</programlisting></informalexample><para>Removes a key/value pair from a <type>GTree</type>.
</para>
<para>If the <type>GTree</type> was created using <function>g_tree_new_full()</function>, 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 <type>GTree</type>, the function does nothing.
</para>
<para>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)).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tree</para></td><td class="parameter_description"><para>a <type>GTree</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to remove</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>remove-all</title><informalexample><programlisting>(define-values () (tree:remove-all self))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tree</para></td><td class="parameter_description"><para></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>replace</title><informalexample><programlisting>(define-values () (tree:replace self key value))
</programlisting></informalexample><para>Inserts a new key and value into a <type>GTree</type> similar to <function>g_tree_insert()</function>.
The difference is that if the key already exists in the <type>GTree</type>, it gets
replaced by the new key. If you supplied a <parameter>value_destroy_func</parameter> when
creating the <type>GTree</type>, the old value is freed using that function. If you
supplied a <parameter>key_destroy_func</parameter> when creating the <type>GTree</type>, the old key is
freed using that function.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tree</para></td><td class="parameter_description"><para>a <type>GTree</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to insert</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>the value corresponding to the key</para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>steal?</title><informalexample><programlisting>(define-values (%return) (tree:steal? self key))
</programlisting></informalexample><para>Removes a key and its associated value from a <type>GTree</type> without calling
the key and value destroy functions.
</para>
<para>If the key does not exist in the <type>GTree</type>, the function does nothing.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tree</para></td><td class="parameter_description"><para>a <type>GTree</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to remove</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (tree:unref self))
</programlisting></informalexample><para>Decrements the reference count of <parameter>tree</parameter> 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 <parameter>tree</parameter> will be released.
</para>
<para>It is safe to call this function from any thread.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tree</para></td><td class="parameter_description"><para>a <type>GTree</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>tree:new-full</title><informalexample><programlisting>(define-values
  (%return)
  (tree:new-full
    key-compare-func
    key-compare-data
    key-destroy-func
    value-destroy-func))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_compare_func</para></td><td class="parameter_description"><para></para><para>Passed as <code>key-compare-func</code></para></td></tr><tr><td class="parameter_name"><para>key_compare_data</para></td><td class="parameter_description"><para></para><para>Passed as <code>key-compare-data</code></para></td></tr><tr><td class="parameter_name"><para>key_destroy_func</para></td><td class="parameter_description"><para></para><para>Passed as <code>key-destroy-func</code></para></td></tr><tr><td class="parameter_name"><para>value_destroy_func</para></td><td class="parameter_description"><para></para><para>Passed as <code>value-destroy-func</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibUnicodeBreakType&gt;</refname></refnamediv><refsect1><title>Description</title><para>These are the possible line break classifications.
</para>
<para>Since new unicode versions may add new types here, applications should be ready
to handle unknown values. They may be regarded as <constant>G_UNICODE_BREAK_UNKNOWN</constant>.
</para>
<para>See [Unicode Line Breaking Algorithm](http://www.unicode.org/unicode/reports/tr14/).</para></refsect1><refsect1><title>Members</title><refsect2><title>mandatory</title><remark>alias <code>G_UNICODE_BREAK_MANDATORY</code></remark><para>Mandatory Break (BK)</para></refsect2><refsect2><title>carriage-return</title><remark>alias <code>G_UNICODE_BREAK_CARRIAGE_RETURN</code></remark><para>Carriage Return (CR)</para></refsect2><refsect2><title>line-feed</title><remark>alias <code>G_UNICODE_BREAK_LINE_FEED</code></remark><para>Line Feed (LF)</para></refsect2><refsect2><title>combining-mark</title><remark>alias <code>G_UNICODE_BREAK_COMBINING_MARK</code></remark><para>Attached Characters and Combining Marks (CM)</para></refsect2><refsect2><title>surrogate</title><remark>alias <code>G_UNICODE_BREAK_SURROGATE</code></remark><para>Surrogates (SG)</para></refsect2><refsect2><title>zero-width-space</title><remark>alias <code>G_UNICODE_BREAK_ZERO_WIDTH_SPACE</code></remark><para>Zero Width Space (ZW)</para></refsect2><refsect2><title>inseparable</title><remark>alias <code>G_UNICODE_BREAK_INSEPARABLE</code></remark><para>Inseparable (IN)</para></refsect2><refsect2><title>non-breaking-glue</title><remark>alias <code>G_UNICODE_BREAK_NON_BREAKING_GLUE</code></remark><para>Non-breaking (&quot;Glue&quot;) (GL)</para></refsect2><refsect2><title>contingent</title><remark>alias <code>G_UNICODE_BREAK_CONTINGENT</code></remark><para>Contingent Break Opportunity (CB)</para></refsect2><refsect2><title>space</title><remark>alias <code>G_UNICODE_BREAK_SPACE</code></remark><para>Space (SP)</para></refsect2><refsect2><title>after</title><remark>alias <code>G_UNICODE_BREAK_AFTER</code></remark><para>Break Opportunity After (BA)</para></refsect2><refsect2><title>before</title><remark>alias <code>G_UNICODE_BREAK_BEFORE</code></remark><para>Break Opportunity Before (BB)</para></refsect2><refsect2><title>before-and-after</title><remark>alias <code>G_UNICODE_BREAK_BEFORE_AND_AFTER</code></remark><para>Break Opportunity Before and After (B2)</para></refsect2><refsect2><title>hyphen</title><remark>alias <code>G_UNICODE_BREAK_HYPHEN</code></remark><para>Hyphen (HY)</para></refsect2><refsect2><title>non-starter</title><remark>alias <code>G_UNICODE_BREAK_NON_STARTER</code></remark><para>Nonstarter (NS)</para></refsect2><refsect2><title>open-punctuation</title><remark>alias <code>G_UNICODE_BREAK_OPEN_PUNCTUATION</code></remark><para>Opening Punctuation (OP)</para></refsect2><refsect2><title>close-punctuation</title><remark>alias <code>G_UNICODE_BREAK_CLOSE_PUNCTUATION</code></remark><para>Closing Punctuation (CL)</para></refsect2><refsect2><title>quotation</title><remark>alias <code>G_UNICODE_BREAK_QUOTATION</code></remark><para>Ambiguous Quotation (QU)</para></refsect2><refsect2><title>exclamation</title><remark>alias <code>G_UNICODE_BREAK_EXCLAMATION</code></remark><para>Exclamation/Interrogation (EX)</para></refsect2><refsect2><title>ideographic</title><remark>alias <code>G_UNICODE_BREAK_IDEOGRAPHIC</code></remark><para>Ideographic (ID)</para></refsect2><refsect2><title>numeric</title><remark>alias <code>G_UNICODE_BREAK_NUMERIC</code></remark><para>Numeric (NU)</para></refsect2><refsect2><title>infix-separator</title><remark>alias <code>G_UNICODE_BREAK_INFIX_SEPARATOR</code></remark><para>Infix Separator (Numeric) (IS)</para></refsect2><refsect2><title>symbol</title><remark>alias <code>G_UNICODE_BREAK_SYMBOL</code></remark><para>Symbols Allowing Break After (SY)</para></refsect2><refsect2><title>alphabetic</title><remark>alias <code>G_UNICODE_BREAK_ALPHABETIC</code></remark><para>Ordinary Alphabetic and Symbol Characters (AL)</para></refsect2><refsect2><title>prefix</title><remark>alias <code>G_UNICODE_BREAK_PREFIX</code></remark><para>Prefix (Numeric) (PR)</para></refsect2><refsect2><title>postfix</title><remark>alias <code>G_UNICODE_BREAK_POSTFIX</code></remark><para>Postfix (Numeric) (PO)</para></refsect2><refsect2><title>complex-context</title><remark>alias <code>G_UNICODE_BREAK_COMPLEX_CONTEXT</code></remark><para>Complex Content Dependent (South East Asian) (SA)</para></refsect2><refsect2><title>ambiguous</title><remark>alias <code>G_UNICODE_BREAK_AMBIGUOUS</code></remark><para>Ambiguous (Alphabetic or Ideographic) (AI)</para></refsect2><refsect2><title>unknown</title><remark>alias <code>G_UNICODE_BREAK_UNKNOWN</code></remark><para>Unknown (XX)</para></refsect2><refsect2><title>next-line</title><remark>alias <code>G_UNICODE_BREAK_NEXT_LINE</code></remark><para>Next Line (NL)</para></refsect2><refsect2><title>word-joiner</title><remark>alias <code>G_UNICODE_BREAK_WORD_JOINER</code></remark><para>Word Joiner (WJ)</para></refsect2><refsect2><title>hangul-l-jamo</title><remark>alias <code>G_UNICODE_BREAK_HANGUL_L_JAMO</code></remark><para>Hangul L Jamo (JL)</para></refsect2><refsect2><title>hangul-v-jamo</title><remark>alias <code>G_UNICODE_BREAK_HANGUL_V_JAMO</code></remark><para>Hangul V Jamo (JV)</para></refsect2><refsect2><title>hangul-t-jamo</title><remark>alias <code>G_UNICODE_BREAK_HANGUL_T_JAMO</code></remark><para>Hangul T Jamo (JT)</para></refsect2><refsect2><title>hangul-lv-syllable</title><remark>alias <code>G_UNICODE_BREAK_HANGUL_LV_SYLLABLE</code></remark><para>Hangul LV Syllable (H2)</para></refsect2><refsect2><title>hangul-lvt-syllable</title><remark>alias <code>G_UNICODE_BREAK_HANGUL_LVT_SYLLABLE</code></remark><para>Hangul LVT Syllable (H3)</para></refsect2><refsect2><title>close-paranthesis</title><remark>alias <code>G_UNICODE_BREAK_CLOSE_PARANTHESIS</code></remark><para>Closing Parenthesis (CP). Since 2.28. Deprecated: 2.70: Use <constant>G_UNICODE_BREAK_CLOSE_PARENTHESIS</constant> instead.</para></refsect2><refsect2><title>close-parenthesis</title><remark>alias <code>G_UNICODE_BREAK_CLOSE_PARENTHESIS</code></remark><para>Closing Parenthesis (CP). Since 2.70</para></refsect2><refsect2><title>conditional-japanese-starter</title><remark>alias <code>G_UNICODE_BREAK_CONDITIONAL_JAPANESE_STARTER</code></remark><para>Conditional Japanese Starter (CJ). Since: 2.32</para></refsect2><refsect2><title>hebrew-letter</title><remark>alias <code>G_UNICODE_BREAK_HEBREW_LETTER</code></remark><para>Hebrew Letter (HL). Since: 2.32</para></refsect2><refsect2><title>regional-indicator</title><remark>alias <code>G_UNICODE_BREAK_REGIONAL_INDICATOR</code></remark><para>Regional Indicator (RI). Since: 2.36</para></refsect2><refsect2><title>emoji-base</title><remark>alias <code>G_UNICODE_BREAK_EMOJI_BASE</code></remark><para>Emoji Base (EB). Since: 2.50</para></refsect2><refsect2><title>emoji-modifier</title><remark>alias <code>G_UNICODE_BREAK_EMOJI_MODIFIER</code></remark><para>Emoji Modifier (EM). Since: 2.50</para></refsect2><refsect2><title>zero-width-joiner</title><remark>alias <code>G_UNICODE_BREAK_ZERO_WIDTH_JOINER</code></remark><para>Zero Width Joiner (ZWJ). Since: 2.50</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibUnicodeScript&gt;</refname></refnamediv><refsect1><title>Description</title><para>The <type>GUnicodeScript</type> 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 <type>PangoScript</type>.
</para>
<para>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/).</para></refsect1><refsect1><title>Members</title><refsect2><title>invalid-code</title><remark>alias <code>G_UNICODE_SCRIPT_INVALID_CODE</code></remark><para>a value never returned from <function>g_unichar_get_script()</function></para></refsect2><refsect2><title>common</title><remark>alias <code>G_UNICODE_SCRIPT_COMMON</code></remark><para>a character used by multiple different scripts</para></refsect2><refsect2><title>inherited</title><remark>alias <code>G_UNICODE_SCRIPT_INHERITED</code></remark><para>a mark glyph that takes its script from the
                              base glyph to which it is attached</para></refsect2><refsect2><title>arabic</title><remark>alias <code>G_UNICODE_SCRIPT_ARABIC</code></remark><para>Arabic</para></refsect2><refsect2><title>armenian</title><remark>alias <code>G_UNICODE_SCRIPT_ARMENIAN</code></remark><para>Armenian</para></refsect2><refsect2><title>bengali</title><remark>alias <code>G_UNICODE_SCRIPT_BENGALI</code></remark><para>Bengali</para></refsect2><refsect2><title>bopomofo</title><remark>alias <code>G_UNICODE_SCRIPT_BOPOMOFO</code></remark><para>Bopomofo</para></refsect2><refsect2><title>cherokee</title><remark>alias <code>G_UNICODE_SCRIPT_CHEROKEE</code></remark><para>Cherokee</para></refsect2><refsect2><title>coptic</title><remark>alias <code>G_UNICODE_SCRIPT_COPTIC</code></remark><para>Coptic</para></refsect2><refsect2><title>cyrillic</title><remark>alias <code>G_UNICODE_SCRIPT_CYRILLIC</code></remark><para>Cyrillic</para></refsect2><refsect2><title>deseret</title><remark>alias <code>G_UNICODE_SCRIPT_DESERET</code></remark><para>Deseret</para></refsect2><refsect2><title>devanagari</title><remark>alias <code>G_UNICODE_SCRIPT_DEVANAGARI</code></remark><para>Devanagari</para></refsect2><refsect2><title>ethiopic</title><remark>alias <code>G_UNICODE_SCRIPT_ETHIOPIC</code></remark><para>Ethiopic</para></refsect2><refsect2><title>georgian</title><remark>alias <code>G_UNICODE_SCRIPT_GEORGIAN</code></remark><para>Georgian</para></refsect2><refsect2><title>gothic</title><remark>alias <code>G_UNICODE_SCRIPT_GOTHIC</code></remark><para>Gothic</para></refsect2><refsect2><title>greek</title><remark>alias <code>G_UNICODE_SCRIPT_GREEK</code></remark><para>Greek</para></refsect2><refsect2><title>gujarati</title><remark>alias <code>G_UNICODE_SCRIPT_GUJARATI</code></remark><para>Gujarati</para></refsect2><refsect2><title>gurmukhi</title><remark>alias <code>G_UNICODE_SCRIPT_GURMUKHI</code></remark><para>Gurmukhi</para></refsect2><refsect2><title>han</title><remark>alias <code>G_UNICODE_SCRIPT_HAN</code></remark><para>Han</para></refsect2><refsect2><title>hangul</title><remark>alias <code>G_UNICODE_SCRIPT_HANGUL</code></remark><para>Hangul</para></refsect2><refsect2><title>hebrew</title><remark>alias <code>G_UNICODE_SCRIPT_HEBREW</code></remark><para>Hebrew</para></refsect2><refsect2><title>hiragana</title><remark>alias <code>G_UNICODE_SCRIPT_HIRAGANA</code></remark><para>Hiragana</para></refsect2><refsect2><title>kannada</title><remark>alias <code>G_UNICODE_SCRIPT_KANNADA</code></remark><para>Kannada</para></refsect2><refsect2><title>katakana</title><remark>alias <code>G_UNICODE_SCRIPT_KATAKANA</code></remark><para>Katakana</para></refsect2><refsect2><title>khmer</title><remark>alias <code>G_UNICODE_SCRIPT_KHMER</code></remark><para>Khmer</para></refsect2><refsect2><title>lao</title><remark>alias <code>G_UNICODE_SCRIPT_LAO</code></remark><para>Lao</para></refsect2><refsect2><title>latin</title><remark>alias <code>G_UNICODE_SCRIPT_LATIN</code></remark><para>Latin</para></refsect2><refsect2><title>malayalam</title><remark>alias <code>G_UNICODE_SCRIPT_MALAYALAM</code></remark><para>Malayalam</para></refsect2><refsect2><title>mongolian</title><remark>alias <code>G_UNICODE_SCRIPT_MONGOLIAN</code></remark><para>Mongolian</para></refsect2><refsect2><title>myanmar</title><remark>alias <code>G_UNICODE_SCRIPT_MYANMAR</code></remark><para>Myanmar</para></refsect2><refsect2><title>ogham</title><remark>alias <code>G_UNICODE_SCRIPT_OGHAM</code></remark><para>Ogham</para></refsect2><refsect2><title>old-italic</title><remark>alias <code>G_UNICODE_SCRIPT_OLD_ITALIC</code></remark><para>Old Italic</para></refsect2><refsect2><title>oriya</title><remark>alias <code>G_UNICODE_SCRIPT_ORIYA</code></remark><para>Oriya</para></refsect2><refsect2><title>runic</title><remark>alias <code>G_UNICODE_SCRIPT_RUNIC</code></remark><para>Runic</para></refsect2><refsect2><title>sinhala</title><remark>alias <code>G_UNICODE_SCRIPT_SINHALA</code></remark><para>Sinhala</para></refsect2><refsect2><title>syriac</title><remark>alias <code>G_UNICODE_SCRIPT_SYRIAC</code></remark><para>Syriac</para></refsect2><refsect2><title>tamil</title><remark>alias <code>G_UNICODE_SCRIPT_TAMIL</code></remark><para>Tamil</para></refsect2><refsect2><title>telugu</title><remark>alias <code>G_UNICODE_SCRIPT_TELUGU</code></remark><para>Telugu</para></refsect2><refsect2><title>thaana</title><remark>alias <code>G_UNICODE_SCRIPT_THAANA</code></remark><para>Thaana</para></refsect2><refsect2><title>thai</title><remark>alias <code>G_UNICODE_SCRIPT_THAI</code></remark><para>Thai</para></refsect2><refsect2><title>tibetan</title><remark>alias <code>G_UNICODE_SCRIPT_TIBETAN</code></remark><para>Tibetan</para></refsect2><refsect2><title>canadian-aboriginal</title><remark>alias <code>G_UNICODE_SCRIPT_CANADIAN_ABORIGINAL</code></remark><para>Canadian Aboriginal</para></refsect2><refsect2><title>yi</title><remark>alias <code>G_UNICODE_SCRIPT_YI</code></remark><para>Yi</para></refsect2><refsect2><title>tagalog</title><remark>alias <code>G_UNICODE_SCRIPT_TAGALOG</code></remark><para>Tagalog</para></refsect2><refsect2><title>hanunoo</title><remark>alias <code>G_UNICODE_SCRIPT_HANUNOO</code></remark><para>Hanunoo</para></refsect2><refsect2><title>buhid</title><remark>alias <code>G_UNICODE_SCRIPT_BUHID</code></remark><para>Buhid</para></refsect2><refsect2><title>tagbanwa</title><remark>alias <code>G_UNICODE_SCRIPT_TAGBANWA</code></remark><para>Tagbanwa</para></refsect2><refsect2><title>braille</title><remark>alias <code>G_UNICODE_SCRIPT_BRAILLE</code></remark><para>Braille</para></refsect2><refsect2><title>cypriot</title><remark>alias <code>G_UNICODE_SCRIPT_CYPRIOT</code></remark><para>Cypriot</para></refsect2><refsect2><title>limbu</title><remark>alias <code>G_UNICODE_SCRIPT_LIMBU</code></remark><para>Limbu</para></refsect2><refsect2><title>osmanya</title><remark>alias <code>G_UNICODE_SCRIPT_OSMANYA</code></remark><para>Osmanya</para></refsect2><refsect2><title>shavian</title><remark>alias <code>G_UNICODE_SCRIPT_SHAVIAN</code></remark><para>Shavian</para></refsect2><refsect2><title>linear-b</title><remark>alias <code>G_UNICODE_SCRIPT_LINEAR_B</code></remark><para>Linear B</para></refsect2><refsect2><title>tai-le</title><remark>alias <code>G_UNICODE_SCRIPT_TAI_LE</code></remark><para>Tai Le</para></refsect2><refsect2><title>ugaritic</title><remark>alias <code>G_UNICODE_SCRIPT_UGARITIC</code></remark><para>Ugaritic</para></refsect2><refsect2><title>new-tai-lue</title><remark>alias <code>G_UNICODE_SCRIPT_NEW_TAI_LUE</code></remark><para>New Tai Lue</para></refsect2><refsect2><title>buginese</title><remark>alias <code>G_UNICODE_SCRIPT_BUGINESE</code></remark><para>Buginese</para></refsect2><refsect2><title>glagolitic</title><remark>alias <code>G_UNICODE_SCRIPT_GLAGOLITIC</code></remark><para>Glagolitic</para></refsect2><refsect2><title>tifinagh</title><remark>alias <code>G_UNICODE_SCRIPT_TIFINAGH</code></remark><para>Tifinagh</para></refsect2><refsect2><title>syloti-nagri</title><remark>alias <code>G_UNICODE_SCRIPT_SYLOTI_NAGRI</code></remark><para>Syloti Nagri</para></refsect2><refsect2><title>old-persian</title><remark>alias <code>G_UNICODE_SCRIPT_OLD_PERSIAN</code></remark><para>Old Persian</para></refsect2><refsect2><title>kharoshthi</title><remark>alias <code>G_UNICODE_SCRIPT_KHAROSHTHI</code></remark><para>Kharoshthi</para></refsect2><refsect2><title>unknown</title><remark>alias <code>G_UNICODE_SCRIPT_UNKNOWN</code></remark><para>an unassigned code point</para></refsect2><refsect2><title>balinese</title><remark>alias <code>G_UNICODE_SCRIPT_BALINESE</code></remark><para>Balinese</para></refsect2><refsect2><title>cuneiform</title><remark>alias <code>G_UNICODE_SCRIPT_CUNEIFORM</code></remark><para>Cuneiform</para></refsect2><refsect2><title>phoenician</title><remark>alias <code>G_UNICODE_SCRIPT_PHOENICIAN</code></remark><para>Phoenician</para></refsect2><refsect2><title>phags-pa</title><remark>alias <code>G_UNICODE_SCRIPT_PHAGS_PA</code></remark><para>Phags-pa</para></refsect2><refsect2><title>nko</title><remark>alias <code>G_UNICODE_SCRIPT_NKO</code></remark><para>N'Ko</para></refsect2><refsect2><title>kayah-li</title><remark>alias <code>G_UNICODE_SCRIPT_KAYAH_LI</code></remark><para>Kayah Li. Since 2.16.3</para></refsect2><refsect2><title>lepcha</title><remark>alias <code>G_UNICODE_SCRIPT_LEPCHA</code></remark><para>Lepcha. Since 2.16.3</para></refsect2><refsect2><title>rejang</title><remark>alias <code>G_UNICODE_SCRIPT_REJANG</code></remark><para>Rejang. Since 2.16.3</para></refsect2><refsect2><title>sundanese</title><remark>alias <code>G_UNICODE_SCRIPT_SUNDANESE</code></remark><para>Sundanese. Since 2.16.3</para></refsect2><refsect2><title>saurashtra</title><remark>alias <code>G_UNICODE_SCRIPT_SAURASHTRA</code></remark><para>Saurashtra. Since 2.16.3</para></refsect2><refsect2><title>cham</title><remark>alias <code>G_UNICODE_SCRIPT_CHAM</code></remark><para>Cham. Since 2.16.3</para></refsect2><refsect2><title>ol-chiki</title><remark>alias <code>G_UNICODE_SCRIPT_OL_CHIKI</code></remark><para>Ol Chiki. Since 2.16.3</para></refsect2><refsect2><title>vai</title><remark>alias <code>G_UNICODE_SCRIPT_VAI</code></remark><para>Vai. Since 2.16.3</para></refsect2><refsect2><title>carian</title><remark>alias <code>G_UNICODE_SCRIPT_CARIAN</code></remark><para>Carian. Since 2.16.3</para></refsect2><refsect2><title>lycian</title><remark>alias <code>G_UNICODE_SCRIPT_LYCIAN</code></remark><para>Lycian. Since 2.16.3</para></refsect2><refsect2><title>lydian</title><remark>alias <code>G_UNICODE_SCRIPT_LYDIAN</code></remark><para>Lydian. Since 2.16.3</para></refsect2><refsect2><title>avestan</title><remark>alias <code>G_UNICODE_SCRIPT_AVESTAN</code></remark><para>Avestan. Since 2.26</para></refsect2><refsect2><title>bamum</title><remark>alias <code>G_UNICODE_SCRIPT_BAMUM</code></remark><para>Bamum. Since 2.26</para></refsect2><refsect2><title>egyptian-hieroglyphs</title><remark>alias <code>G_UNICODE_SCRIPT_EGYPTIAN_HIEROGLYPHS</code></remark><para>Egyptian Hieroglpyhs. Since 2.26</para></refsect2><refsect2><title>imperial-aramaic</title><remark>alias <code>G_UNICODE_SCRIPT_IMPERIAL_ARAMAIC</code></remark><para>Imperial Aramaic. Since 2.26</para></refsect2><refsect2><title>inscriptional-pahlavi</title><remark>alias <code>G_UNICODE_SCRIPT_INSCRIPTIONAL_PAHLAVI</code></remark><para>Inscriptional Pahlavi. Since 2.26</para></refsect2><refsect2><title>inscriptional-parthian</title><remark>alias <code>G_UNICODE_SCRIPT_INSCRIPTIONAL_PARTHIAN</code></remark><para>Inscriptional Parthian. Since 2.26</para></refsect2><refsect2><title>javanese</title><remark>alias <code>G_UNICODE_SCRIPT_JAVANESE</code></remark><para>Javanese. Since 2.26</para></refsect2><refsect2><title>kaithi</title><remark>alias <code>G_UNICODE_SCRIPT_KAITHI</code></remark><para>Kaithi. Since 2.26</para></refsect2><refsect2><title>lisu</title><remark>alias <code>G_UNICODE_SCRIPT_LISU</code></remark><para>Lisu. Since 2.26</para></refsect2><refsect2><title>meetei-mayek</title><remark>alias <code>G_UNICODE_SCRIPT_MEETEI_MAYEK</code></remark><para>Meetei Mayek. Since 2.26</para></refsect2><refsect2><title>old-south-arabian</title><remark>alias <code>G_UNICODE_SCRIPT_OLD_SOUTH_ARABIAN</code></remark><para>Old South Arabian. Since 2.26</para></refsect2><refsect2><title>old-turkic</title><remark>alias <code>G_UNICODE_SCRIPT_OLD_TURKIC</code></remark><para>Old Turkic. Since 2.28</para></refsect2><refsect2><title>samaritan</title><remark>alias <code>G_UNICODE_SCRIPT_SAMARITAN</code></remark><para>Samaritan. Since 2.26</para></refsect2><refsect2><title>tai-tham</title><remark>alias <code>G_UNICODE_SCRIPT_TAI_THAM</code></remark><para>Tai Tham. Since 2.26</para></refsect2><refsect2><title>tai-viet</title><remark>alias <code>G_UNICODE_SCRIPT_TAI_VIET</code></remark><para>Tai Viet. Since 2.26</para></refsect2><refsect2><title>batak</title><remark>alias <code>G_UNICODE_SCRIPT_BATAK</code></remark><para>Batak. Since 2.28</para></refsect2><refsect2><title>brahmi</title><remark>alias <code>G_UNICODE_SCRIPT_BRAHMI</code></remark><para>Brahmi. Since 2.28</para></refsect2><refsect2><title>mandaic</title><remark>alias <code>G_UNICODE_SCRIPT_MANDAIC</code></remark><para>Mandaic. Since 2.28</para></refsect2><refsect2><title>chakma</title><remark>alias <code>G_UNICODE_SCRIPT_CHAKMA</code></remark><para>Chakma. Since: 2.32</para></refsect2><refsect2><title>meroitic-cursive</title><remark>alias <code>G_UNICODE_SCRIPT_MEROITIC_CURSIVE</code></remark><para>Meroitic Cursive. Since: 2.32</para></refsect2><refsect2><title>meroitic-hieroglyphs</title><remark>alias <code>G_UNICODE_SCRIPT_MEROITIC_HIEROGLYPHS</code></remark><para>Meroitic Hieroglyphs. Since: 2.32</para></refsect2><refsect2><title>miao</title><remark>alias <code>G_UNICODE_SCRIPT_MIAO</code></remark><para>Miao. Since: 2.32</para></refsect2><refsect2><title>sharada</title><remark>alias <code>G_UNICODE_SCRIPT_SHARADA</code></remark><para>Sharada. Since: 2.32</para></refsect2><refsect2><title>sora-sompeng</title><remark>alias <code>G_UNICODE_SCRIPT_SORA_SOMPENG</code></remark><para>Sora Sompeng. Since: 2.32</para></refsect2><refsect2><title>takri</title><remark>alias <code>G_UNICODE_SCRIPT_TAKRI</code></remark><para>Takri. Since: 2.32</para></refsect2><refsect2><title>bassa-vah</title><remark>alias <code>G_UNICODE_SCRIPT_BASSA_VAH</code></remark><para>Bassa. Since: 2.42</para></refsect2><refsect2><title>caucasian-albanian</title><remark>alias <code>G_UNICODE_SCRIPT_CAUCASIAN_ALBANIAN</code></remark><para>Caucasian Albanian. Since: 2.42</para></refsect2><refsect2><title>duployan</title><remark>alias <code>G_UNICODE_SCRIPT_DUPLOYAN</code></remark><para>Duployan. Since: 2.42</para></refsect2><refsect2><title>elbasan</title><remark>alias <code>G_UNICODE_SCRIPT_ELBASAN</code></remark><para>Elbasan. Since: 2.42</para></refsect2><refsect2><title>grantha</title><remark>alias <code>G_UNICODE_SCRIPT_GRANTHA</code></remark><para>Grantha. Since: 2.42</para></refsect2><refsect2><title>khojki</title><remark>alias <code>G_UNICODE_SCRIPT_KHOJKI</code></remark><para>Kjohki. Since: 2.42</para></refsect2><refsect2><title>khudawadi</title><remark>alias <code>G_UNICODE_SCRIPT_KHUDAWADI</code></remark><para>Khudawadi, Sindhi. Since: 2.42</para></refsect2><refsect2><title>linear-a</title><remark>alias <code>G_UNICODE_SCRIPT_LINEAR_A</code></remark><para>Linear A. Since: 2.42</para></refsect2><refsect2><title>mahajani</title><remark>alias <code>G_UNICODE_SCRIPT_MAHAJANI</code></remark><para>Mahajani. Since: 2.42</para></refsect2><refsect2><title>manichaean</title><remark>alias <code>G_UNICODE_SCRIPT_MANICHAEAN</code></remark><para>Manichaean. Since: 2.42</para></refsect2><refsect2><title>mende-kikakui</title><remark>alias <code>G_UNICODE_SCRIPT_MENDE_KIKAKUI</code></remark><para>Mende Kikakui. Since: 2.42</para></refsect2><refsect2><title>modi</title><remark>alias <code>G_UNICODE_SCRIPT_MODI</code></remark><para>Modi. Since: 2.42</para></refsect2><refsect2><title>mro</title><remark>alias <code>G_UNICODE_SCRIPT_MRO</code></remark><para>Mro. Since: 2.42</para></refsect2><refsect2><title>nabataean</title><remark>alias <code>G_UNICODE_SCRIPT_NABATAEAN</code></remark><para>Nabataean. Since: 2.42</para></refsect2><refsect2><title>old-north-arabian</title><remark>alias <code>G_UNICODE_SCRIPT_OLD_NORTH_ARABIAN</code></remark><para>Old North Arabian. Since: 2.42</para></refsect2><refsect2><title>old-permic</title><remark>alias <code>G_UNICODE_SCRIPT_OLD_PERMIC</code></remark><para>Old Permic. Since: 2.42</para></refsect2><refsect2><title>pahawh-hmong</title><remark>alias <code>G_UNICODE_SCRIPT_PAHAWH_HMONG</code></remark><para>Pahawh Hmong. Since: 2.42</para></refsect2><refsect2><title>palmyrene</title><remark>alias <code>G_UNICODE_SCRIPT_PALMYRENE</code></remark><para>Palmyrene. Since: 2.42</para></refsect2><refsect2><title>pau-cin-hau</title><remark>alias <code>G_UNICODE_SCRIPT_PAU_CIN_HAU</code></remark><para>Pau Cin Hau. Since: 2.42</para></refsect2><refsect2><title>psalter-pahlavi</title><remark>alias <code>G_UNICODE_SCRIPT_PSALTER_PAHLAVI</code></remark><para>Psalter Pahlavi. Since: 2.42</para></refsect2><refsect2><title>siddham</title><remark>alias <code>G_UNICODE_SCRIPT_SIDDHAM</code></remark><para>Siddham. Since: 2.42</para></refsect2><refsect2><title>tirhuta</title><remark>alias <code>G_UNICODE_SCRIPT_TIRHUTA</code></remark><para>Tirhuta. Since: 2.42</para></refsect2><refsect2><title>warang-citi</title><remark>alias <code>G_UNICODE_SCRIPT_WARANG_CITI</code></remark><para>Warang Citi. Since: 2.42</para></refsect2><refsect2><title>ahom</title><remark>alias <code>G_UNICODE_SCRIPT_AHOM</code></remark><para>Ahom. Since: 2.48</para></refsect2><refsect2><title>anatolian-hieroglyphs</title><remark>alias <code>G_UNICODE_SCRIPT_ANATOLIAN_HIEROGLYPHS</code></remark><para>Anatolian Hieroglyphs. Since: 2.48</para></refsect2><refsect2><title>hatran</title><remark>alias <code>G_UNICODE_SCRIPT_HATRAN</code></remark><para>Hatran. Since: 2.48</para></refsect2><refsect2><title>multani</title><remark>alias <code>G_UNICODE_SCRIPT_MULTANI</code></remark><para>Multani. Since: 2.48</para></refsect2><refsect2><title>old-hungarian</title><remark>alias <code>G_UNICODE_SCRIPT_OLD_HUNGARIAN</code></remark><para>Old Hungarian. Since: 2.48</para></refsect2><refsect2><title>signwriting</title><remark>alias <code>G_UNICODE_SCRIPT_SIGNWRITING</code></remark><para>Signwriting. Since: 2.48</para></refsect2><refsect2><title>adlam</title><remark>alias <code>G_UNICODE_SCRIPT_ADLAM</code></remark><para>Adlam. Since: 2.50</para></refsect2><refsect2><title>bhaiksuki</title><remark>alias <code>G_UNICODE_SCRIPT_BHAIKSUKI</code></remark><para>Bhaiksuki. Since: 2.50</para></refsect2><refsect2><title>marchen</title><remark>alias <code>G_UNICODE_SCRIPT_MARCHEN</code></remark><para>Marchen. Since: 2.50</para></refsect2><refsect2><title>newa</title><remark>alias <code>G_UNICODE_SCRIPT_NEWA</code></remark><para>Newa. Since: 2.50</para></refsect2><refsect2><title>osage</title><remark>alias <code>G_UNICODE_SCRIPT_OSAGE</code></remark><para>Osage. Since: 2.50</para></refsect2><refsect2><title>tangut</title><remark>alias <code>G_UNICODE_SCRIPT_TANGUT</code></remark><para>Tangut. Since: 2.50</para></refsect2><refsect2><title>masaram-gondi</title><remark>alias <code>G_UNICODE_SCRIPT_MASARAM_GONDI</code></remark><para>Masaram Gondi. Since: 2.54</para></refsect2><refsect2><title>nushu</title><remark>alias <code>G_UNICODE_SCRIPT_NUSHU</code></remark><para>Nushu. Since: 2.54</para></refsect2><refsect2><title>soyombo</title><remark>alias <code>G_UNICODE_SCRIPT_SOYOMBO</code></remark><para>Soyombo. Since: 2.54</para></refsect2><refsect2><title>zanabazar-square</title><remark>alias <code>G_UNICODE_SCRIPT_ZANABAZAR_SQUARE</code></remark><para>Zanabazar Square. Since: 2.54</para></refsect2><refsect2><title>dogra</title><remark>alias <code>G_UNICODE_SCRIPT_DOGRA</code></remark><para>Dogra. Since: 2.58</para></refsect2><refsect2><title>gunjala-gondi</title><remark>alias <code>G_UNICODE_SCRIPT_GUNJALA_GONDI</code></remark><para>Gunjala Gondi. Since: 2.58</para></refsect2><refsect2><title>hanifi-rohingya</title><remark>alias <code>G_UNICODE_SCRIPT_HANIFI_ROHINGYA</code></remark><para>Hanifi Rohingya. Since: 2.58</para></refsect2><refsect2><title>makasar</title><remark>alias <code>G_UNICODE_SCRIPT_MAKASAR</code></remark><para>Makasar. Since: 2.58</para></refsect2><refsect2><title>medefaidrin</title><remark>alias <code>G_UNICODE_SCRIPT_MEDEFAIDRIN</code></remark><para>Medefaidrin. Since: 2.58</para></refsect2><refsect2><title>old-sogdian</title><remark>alias <code>G_UNICODE_SCRIPT_OLD_SOGDIAN</code></remark><para>Old Sogdian. Since: 2.58</para></refsect2><refsect2><title>sogdian</title><remark>alias <code>G_UNICODE_SCRIPT_SOGDIAN</code></remark><para>Sogdian. Since: 2.58</para></refsect2><refsect2><title>elymaic</title><remark>alias <code>G_UNICODE_SCRIPT_ELYMAIC</code></remark><para>Elym. Since: 2.62</para></refsect2><refsect2><title>nandinagari</title><remark>alias <code>G_UNICODE_SCRIPT_NANDINAGARI</code></remark><para>Nand. Since: 2.62</para></refsect2><refsect2><title>nyiakeng-puachue-hmong</title><remark>alias <code>G_UNICODE_SCRIPT_NYIAKENG_PUACHUE_HMONG</code></remark><para>Rohg. Since: 2.62</para></refsect2><refsect2><title>wancho</title><remark>alias <code>G_UNICODE_SCRIPT_WANCHO</code></remark><para>Wcho. Since: 2.62</para></refsect2><refsect2><title>chorasmian</title><remark>alias <code>G_UNICODE_SCRIPT_CHORASMIAN</code></remark><para>Chorasmian. Since: 2.66</para></refsect2><refsect2><title>dives-akuru</title><remark>alias <code>G_UNICODE_SCRIPT_DIVES_AKURU</code></remark><para>Dives Akuru. Since: 2.66</para></refsect2><refsect2><title>khitan-small-script</title><remark>alias <code>G_UNICODE_SCRIPT_KHITAN_SMALL_SCRIPT</code></remark><para>Khitan small script. Since: 2.66</para></refsect2><refsect2><title>yezidi</title><remark>alias <code>G_UNICODE_SCRIPT_YEZIDI</code></remark><para>Yezidi. Since: 2.66</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibUnicodeType&gt;</refname></refnamediv><refsect1><title>Description</title><para>These are the possible character classifications from the
Unicode specification.
See [Unicode Character Database](http://www.unicode.org/reports/tr44/<type>General_Category_Values</type>).</para></refsect1><refsect1><title>Members</title><refsect2><title>control</title><remark>alias <code>G_UNICODE_CONTROL</code></remark><para>General category &quot;Other, Control&quot; (Cc)</para></refsect2><refsect2><title>format</title><remark>alias <code>G_UNICODE_FORMAT</code></remark><para>General category &quot;Other, Format&quot; (Cf)</para></refsect2><refsect2><title>unassigned</title><remark>alias <code>G_UNICODE_UNASSIGNED</code></remark><para>General category &quot;Other, Not Assigned&quot; (Cn)</para></refsect2><refsect2><title>private-use</title><remark>alias <code>G_UNICODE_PRIVATE_USE</code></remark><para>General category &quot;Other, Private Use&quot; (Co)</para></refsect2><refsect2><title>surrogate</title><remark>alias <code>G_UNICODE_SURROGATE</code></remark><para>General category &quot;Other, Surrogate&quot; (Cs)</para></refsect2><refsect2><title>lowercase-letter</title><remark>alias <code>G_UNICODE_LOWERCASE_LETTER</code></remark><para>General category &quot;Letter, Lowercase&quot; (Ll)</para></refsect2><refsect2><title>modifier-letter</title><remark>alias <code>G_UNICODE_MODIFIER_LETTER</code></remark><para>General category &quot;Letter, Modifier&quot; (Lm)</para></refsect2><refsect2><title>other-letter</title><remark>alias <code>G_UNICODE_OTHER_LETTER</code></remark><para>General category &quot;Letter, Other&quot; (Lo)</para></refsect2><refsect2><title>titlecase-letter</title><remark>alias <code>G_UNICODE_TITLECASE_LETTER</code></remark><para>General category &quot;Letter, Titlecase&quot; (Lt)</para></refsect2><refsect2><title>uppercase-letter</title><remark>alias <code>G_UNICODE_UPPERCASE_LETTER</code></remark><para>General category &quot;Letter, Uppercase&quot; (Lu)</para></refsect2><refsect2><title>spacing-mark</title><remark>alias <code>G_UNICODE_SPACING_MARK</code></remark><para>General category &quot;Mark, Spacing&quot; (Mc)</para></refsect2><refsect2><title>enclosing-mark</title><remark>alias <code>G_UNICODE_ENCLOSING_MARK</code></remark><para>General category &quot;Mark, Enclosing&quot; (Me)</para></refsect2><refsect2><title>non-spacing-mark</title><remark>alias <code>G_UNICODE_NON_SPACING_MARK</code></remark><para>General category &quot;Mark, Nonspacing&quot; (Mn)</para></refsect2><refsect2><title>decimal-number</title><remark>alias <code>G_UNICODE_DECIMAL_NUMBER</code></remark><para>General category &quot;Number, Decimal Digit&quot; (Nd)</para></refsect2><refsect2><title>letter-number</title><remark>alias <code>G_UNICODE_LETTER_NUMBER</code></remark><para>General category &quot;Number, Letter&quot; (Nl)</para></refsect2><refsect2><title>other-number</title><remark>alias <code>G_UNICODE_OTHER_NUMBER</code></remark><para>General category &quot;Number, Other&quot; (No)</para></refsect2><refsect2><title>connect-punctuation</title><remark>alias <code>G_UNICODE_CONNECT_PUNCTUATION</code></remark><para>General category &quot;Punctuation, Connector&quot; (Pc)</para></refsect2><refsect2><title>dash-punctuation</title><remark>alias <code>G_UNICODE_DASH_PUNCTUATION</code></remark><para>General category &quot;Punctuation, Dash&quot; (Pd)</para></refsect2><refsect2><title>close-punctuation</title><remark>alias <code>G_UNICODE_CLOSE_PUNCTUATION</code></remark><para>General category &quot;Punctuation, Close&quot; (Pe)</para></refsect2><refsect2><title>final-punctuation</title><remark>alias <code>G_UNICODE_FINAL_PUNCTUATION</code></remark><para>General category &quot;Punctuation, Final quote&quot; (Pf)</para></refsect2><refsect2><title>initial-punctuation</title><remark>alias <code>G_UNICODE_INITIAL_PUNCTUATION</code></remark><para>General category &quot;Punctuation, Initial quote&quot; (Pi)</para></refsect2><refsect2><title>other-punctuation</title><remark>alias <code>G_UNICODE_OTHER_PUNCTUATION</code></remark><para>General category &quot;Punctuation, Other&quot; (Po)</para></refsect2><refsect2><title>open-punctuation</title><remark>alias <code>G_UNICODE_OPEN_PUNCTUATION</code></remark><para>General category &quot;Punctuation, Open&quot; (Ps)</para></refsect2><refsect2><title>currency-symbol</title><remark>alias <code>G_UNICODE_CURRENCY_SYMBOL</code></remark><para>General category &quot;Symbol, Currency&quot; (Sc)</para></refsect2><refsect2><title>modifier-symbol</title><remark>alias <code>G_UNICODE_MODIFIER_SYMBOL</code></remark><para>General category &quot;Symbol, Modifier&quot; (Sk)</para></refsect2><refsect2><title>math-symbol</title><remark>alias <code>G_UNICODE_MATH_SYMBOL</code></remark><para>General category &quot;Symbol, Math&quot; (Sm)</para></refsect2><refsect2><title>other-symbol</title><remark>alias <code>G_UNICODE_OTHER_SYMBOL</code></remark><para>General category &quot;Symbol, Other&quot; (So)</para></refsect2><refsect2><title>line-separator</title><remark>alias <code>G_UNICODE_LINE_SEPARATOR</code></remark><para>General category &quot;Separator, Line&quot; (Zl)</para></refsect2><refsect2><title>paragraph-separator</title><remark>alias <code>G_UNICODE_PARAGRAPH_SEPARATOR</code></remark><para>General category &quot;Separator, Paragraph&quot; (Zp)</para></refsect2><refsect2><title>space-separator</title><remark>alias <code>G_UNICODE_SPACE_SEPARATOR</code></remark><para>General category &quot;Separator, Space&quot; (Zs)</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GUri&gt;</refname></refnamediv><refsect1><title>Description</title><para>The <type>GUri</type> type and related functions can be used to parse URIs into
their components, and build valid URIs from individual components.
</para>
<para>Note that <type>GUri</type> 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
<type>GUri</type> is not suitable for formatting URIs for display to the user for making
security-sensitive decisions.
</para>
<refsect2><title>Relative and absolute URIs <anchor id="relative-absolute-uris" /></title>
<para>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).
</para>
<para>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 <code>./</code> rather than <code>/</code>.
</para>
<para>For example, a valid relative reference is <code>./path?query</code>,
<code>/?query#fragment</code> or <code>//example.com</code>.
</para>
<para>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 <function>g_uri_parse_relative()</function>.
</para>
<para>For example, a valid absolute URI is <code>file:///home/bob</code> or
<code>https://search.com?query=string</code>.
</para>
<para>A <type>GUri</type> 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.
</para>
</refsect2><refsect2><title>Parsing URIs</title>
<para>The most minimalist APIs for parsing URIs are <function>g_uri_split()</function> and
<function>g_uri_split_with_user()</function>. These split a URI into its component
parts, and return the parts; the difference between the two is that
<function>g_uri_split()</function> treats the ‘userinfo’ component of the URI as a
single element, while <function>g_uri_split_with_user()</function> can (depending on the
<type>GUriFlags</type> you pass) treat it as containing a username, password,
and authentication parameters. Alternatively, <function>g_uri_split_network()</function>
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).
</para>
<para><function>g_uri_parse()</function> is similar to <function>g_uri_split()</function>, but instead of returning
individual strings, it returns a <type>GUri</type> structure (and it requires
that the URI be an absolute URI).
</para>
<para><function>g_uri_resolve_relative()</function> and <function>g_uri_parse_relative()</function> allow you to
resolve a relative URI relative to a base URI.
<function>g_uri_resolve_relative()</function> takes two strings and returns a string,
and <function>g_uri_parse_relative()</function> takes a <type>GUri</type> and a string and returns a
<type>GUri</type>.
</para>
<para>All of the parsing functions take a <type>GUriFlags</type> 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 <function>g_uri_peek_scheme()</function> on the URI string to check the scheme
first, and use that to decide what flags to parse it with.
</para>
<para>For example, you might want to use <constant>G_URI_PARAMS_WWW_FORM</constant> when parsing the
params for a web URI, so compare the result of <function>g_uri_peek_scheme()</function> against
<code>http</code> and <code>https</code>.
</para>
</refsect2><refsect2><title>Building URIs</title>
<para><function>g_uri_join()</function> and <function>g_uri_join_with_user()</function> can be used to construct
valid URI strings from a set of component strings. They are the
inverse of <function>g_uri_split()</function> and <function>g_uri_split_with_user()</function>.
</para>
<para>Similarly, <function>g_uri_build()</function> and <function>g_uri_build_with_user()</function> can be used to
construct a <type>GUri</type> from a set of component strings.
</para>
<para>As with the parsing functions, the building functions take a
<type>GUriFlags</type> argument. In particular, it is important to keep in mind
whether the URI components you are using are already <code>%</code>-encoded. If so,
you must pass the <constant>G_URI_FLAGS_ENCODED</constant> flag.
</para>
</refsect2><refsect2><title>`file://` URIs</title>
<para>Note that Windows and Unix both define special rules for parsing
<code>file://</code> URIs (involving non-UTF-8 character sets on Unix, and the
interpretation of path separators on Windows). <type>GUri</type> does not
implement these rules. Use <function>g_filename_from_uri()</function> and
<function>g_filename_to_uri()</function> if you want to properly convert between
<code>file://</code> URIs and local filenames.
</para>
</refsect2><refsect2><title>URI Equality</title>
<para>Note that there is no <code>g_uri_equal ()</code> function, because comparing
URIs usefully requires scheme-specific knowledge that <type>GUri</type> does
not have. For example, <code>http://example.com/</code> and
<code>http://EXAMPLE.COM:80</code> have exactly the same meaning according
to the HTTP specification, and <code>data:,foo</code> and
<code>data:;base64,Zm9v</code> resolve to the same thing according to the
<code>data:</code> URI specification.</para></refsect2></refsect1><refsect1><title>Functions</title><refsect2><title>get-auth-params</title><informalexample><programlisting>(define-values (%return) (uri:get-auth-params self))
</programlisting></informalexample><para>Gets <parameter>uri</parameter>'s authentication parameters, which may contain
<code>%</code>-encoding, depending on the flags with which <parameter>uri</parameter> was created.
(If <parameter>uri</parameter> was not created with <constant>G_URI_FLAGS_HAS_AUTH_PARAMS</constant> then this will
be <constant>NULL</constant>.)
</para>
<para>Depending on the URI scheme, <function>g_uri_parse_params()</function> may be useful for
further parsing this information.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a <type>GUri</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-flags</title><informalexample><programlisting>(define-values (%return) (uri:get-flags self))
</programlisting></informalexample><para>Gets <parameter>uri</parameter>'s flags set upon construction.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a <type>GUri</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-fragment</title><informalexample><programlisting>(define-values (%return) (uri:get-fragment self))
</programlisting></informalexample><para>Gets <parameter>uri</parameter>'s fragment, which may contain <code>%</code>-encoding, depending on
the flags with which <parameter>uri</parameter> was created.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a <type>GUri</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-host</title><informalexample><programlisting>(define-values (%return) (uri:get-host self))
</programlisting></informalexample><para>Gets <parameter>uri</parameter>'s host. This will never have <code>%</code>-encoded characters,
unless it is non-UTF-8 (which can only be the case if <parameter>uri</parameter> was
created with <constant>G_URI_FLAGS_NON_DNS</constant>).
</para>
<para>If <parameter>uri</parameter> 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, <code>fe80::1234%</code><code>em1</code> (or
<code>fe80::1234%</code><code>25em1</code> if the string is still encoded).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a <type>GUri</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-password</title><informalexample><programlisting>(define-values (%return) (uri:get-password self))
</programlisting></informalexample><para>Gets <parameter>uri</parameter>'s password, which may contain <code>%</code>-encoding, depending on
the flags with which <parameter>uri</parameter> was created. (If <parameter>uri</parameter> was not created
with <constant>G_URI_FLAGS_HAS_PASSWORD</constant> then this will be <constant>NULL</constant>.)</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a <type>GUri</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-path</title><informalexample><programlisting>(define-values (%return) (uri:get-path self))
</programlisting></informalexample><para>Gets <parameter>uri</parameter>'s path, which may contain <code>%</code>-encoding, depending on the
flags with which <parameter>uri</parameter> was created.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a <type>GUri</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-port</title><informalexample><programlisting>(define-values (%return) (uri:get-port self))
</programlisting></informalexample><para>Gets <parameter>uri</parameter>'s port.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a <type>GUri</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-query</title><informalexample><programlisting>(define-values (%return) (uri:get-query self))
</programlisting></informalexample><para>Gets <parameter>uri</parameter>'s query, which may contain <code>%</code>-encoding, depending on the
flags with which <parameter>uri</parameter> was created.
</para>
<para>For queries consisting of a series of <code>name=value</code> parameters,
<type>GUriParamsIter</type> or <function>g_uri_parse_params()</function> may be useful.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a <type>GUri</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-scheme</title><informalexample><programlisting>(define-values (%return) (uri:get-scheme self))
</programlisting></informalexample><para>Gets <parameter>uri</parameter>'s scheme. Note that this will always be all-lowercase,
regardless of the string or strings that <parameter>uri</parameter> was created from.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a <type>GUri</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-user</title><informalexample><programlisting>(define-values (%return) (uri:get-user self))
</programlisting></informalexample><para>Gets the ‘username’ component of <parameter>uri</parameter>'s userinfo, which may contain
<code>%</code>-encoding, depending on the flags with which <parameter>uri</parameter> was created.
If <parameter>uri</parameter> was not created with <constant>G_URI_FLAGS_HAS_PASSWORD</constant> or
<constant>G_URI_FLAGS_HAS_AUTH_PARAMS</constant>, this is the same as <function>g_uri_get_userinfo()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a <type>GUri</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-userinfo</title><informalexample><programlisting>(define-values (%return) (uri:get-userinfo self))
</programlisting></informalexample><para>Gets <parameter>uri</parameter>'s userinfo, which may contain <code>%</code>-encoding, depending on
the flags with which <parameter>uri</parameter> was created.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a <type>GUri</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>parse-relative</title><informalexample><programlisting>(define-values (%return) (uri:parse-relative self uri-ref flags))
</programlisting></informalexample><para>Parses <parameter>uri_ref</parameter> according to <parameter>flags</parameter> and, if it is a
[relative URI][relative-absolute-uris], resolves it relative to <parameter>base_uri</parameter>.
If the result is not a valid absolute URI, it will be discarded, and an error
returned.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>base_uri</para></td><td class="parameter_description"><para>a base absolute URI</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>uri_ref</para></td><td class="parameter_description"><para>a string representing a relative or absolute URI</para><para>Passed as <code>uri-ref</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags describing how to parse <parameter>uri_ref</parameter></para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>to-string</title><informalexample><programlisting>(define-values (%return) (uri:to-string self))
</programlisting></informalexample><para>Returns a string representing <parameter>uri</parameter>.
</para>
<para>This is not guaranteed to return a string which is identical to the
string that <parameter>uri</parameter> was parsed from. However, if the source URI was
syntactically correct (according to RFC 3986), and it was parsed
with <constant>G_URI_FLAGS_ENCODED</constant>, then <function>g_uri_to_string()</function> is guaranteed to return
a string which is at least semantically equivalent to the source
URI (according to RFC 3986).
</para>
<para>If <parameter>uri</parameter> 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 <function>g_uri_to_string_partial()</function> to redact parts.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a <type>GUri</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>to-string-partial</title><informalexample><programlisting>(define-values (%return) (uri:to-string-partial self flags))
</programlisting></informalexample><para>Returns a string representing <parameter>uri</parameter>, subject to the options in
<parameter>flags</parameter>. See <function>g_uri_to_string()</function> and <type>GUriHideFlags</type> for more details.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a <type>GUri</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags describing what parts of <parameter>uri</parameter> to hide</para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:build</title><informalexample><programlisting>(define-values
  (%return)
  (uri:build flags scheme userinfo host port path query fragment))
</programlisting></informalexample><para>Creates a new <type>GUri</type> from the given components according to <parameter>flags</parameter>.
</para>
<para>See also <function>g_uri_build_with_user()</function>, which allows specifying the
components of the &quot;userinfo&quot; separately.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags describing how to build the <type>GUri</type></para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>scheme</para></td><td class="parameter_description"><para>the URI scheme</para><para>Passed as <code>scheme</code></para></td></tr><tr><td class="parameter_name"><para>userinfo</para></td><td class="parameter_description"><para>the userinfo component, or <constant>NULL</constant></para><para>Passed as <code>userinfo</code></para></td></tr><tr><td class="parameter_name"><para>host</para></td><td class="parameter_description"><para>the host component, or <constant>NULL</constant></para><para>Passed as <code>host</code></para></td></tr><tr><td class="parameter_name"><para>port</para></td><td class="parameter_description"><para>the port, or <code>-1</code></para><para>Passed as <code>port</code></para></td></tr><tr><td class="parameter_name"><para>path</para></td><td class="parameter_description"><para>the path component</para><para>Passed as <code>path</code></para></td></tr><tr><td class="parameter_name"><para>query</para></td><td class="parameter_description"><para>the query component, or <constant>NULL</constant></para><para>Passed as <code>query</code></para></td></tr><tr><td class="parameter_name"><para>fragment</para></td><td class="parameter_description"><para>the fragment, or <constant>NULL</constant></para><para>Passed as <code>fragment</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:build-with-user</title><informalexample><programlisting>(define-values
  (%return)
  (uri:build-with-user
    flags
    scheme
    user
    password
    auth-params
    host
    port
    path
    query
    fragment))
</programlisting></informalexample><para>Creates a new <type>GUri</type> from the given components according to <parameter>flags</parameter>
(<constant>G_URI_FLAGS_HAS_PASSWORD</constant> is added unconditionally). The <parameter>flags</parameter> must be
coherent with the passed values, in particular use <code>%</code>-encoded values with
<constant>G_URI_FLAGS_ENCODED</constant>.
</para>
<para>In contrast to <function>g_uri_build()</function>, this allows specifying the components
of the ‘userinfo’ field separately. Note that <parameter>user</parameter> must be non-<constant>NULL</constant>
if either <parameter>password</parameter> or <parameter>auth_params</parameter> is non-<constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags describing how to build the <type>GUri</type></para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>scheme</para></td><td class="parameter_description"><para>the URI scheme</para><para>Passed as <code>scheme</code></para></td></tr><tr><td class="parameter_name"><para>user</para></td><td class="parameter_description"><para>the user component of the userinfo, or <constant>NULL</constant></para><para>Passed as <code>user</code></para></td></tr><tr><td class="parameter_name"><para>password</para></td><td class="parameter_description"><para>the password component of the userinfo, or <constant>NULL</constant></para><para>Passed as <code>password</code></para></td></tr><tr><td class="parameter_name"><para>auth_params</para></td><td class="parameter_description"><para>the auth params of the userinfo, or <constant>NULL</constant></para><para>Passed as <code>auth-params</code></para></td></tr><tr><td class="parameter_name"><para>host</para></td><td class="parameter_description"><para>the host component, or <constant>NULL</constant></para><para>Passed as <code>host</code></para></td></tr><tr><td class="parameter_name"><para>port</para></td><td class="parameter_description"><para>the port, or <code>-1</code></para><para>Passed as <code>port</code></para></td></tr><tr><td class="parameter_name"><para>path</para></td><td class="parameter_description"><para>the path component</para><para>Passed as <code>path</code></para></td></tr><tr><td class="parameter_name"><para>query</para></td><td class="parameter_description"><para>the query component, or <constant>NULL</constant></para><para>Passed as <code>query</code></para></td></tr><tr><td class="parameter_name"><para>fragment</para></td><td class="parameter_description"><para>the fragment, or <constant>NULL</constant></para><para>Passed as <code>fragment</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:error-quark</title><informalexample><programlisting>(define-values (%return) (uri:error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>uri:escape-bytes</title><informalexample><programlisting>(define-values (%return) (uri:escape-bytes unescaped reserved-chars-allowed))
</programlisting></informalexample><para>Escapes arbitrary data for use in a URI.
</para>
<para>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 <parameter>reserved_chars_allowed</parameter>
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.
</para>
<para>Though technically incorrect, this will also allow escaping nul
bytes as <code>%</code><code>00</code>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>unescaped</para></td><td class="parameter_description"><para>the unescaped input data.</para><para>Passed as <code>unescaped</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of <parameter>unescaped</parameter></para><para>Inferred from <code>unescaped</code></para></td></tr><tr><td class="parameter_name"><para>reserved_chars_allowed</para></td><td class="parameter_description"><para>a string of reserved
  characters that are allowed to be used, or <constant>NULL</constant>.</para><para>Passed as <code>reserved-chars-allowed</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:escape-string</title><informalexample><programlisting>(define-values
  (%return)
  (uri:escape-string unescaped reserved-chars-allowed allow-utf8))
</programlisting></informalexample><para>Escapes a string for use in a URI.
</para>
<para>Normally all characters that are not &quot;unreserved&quot; (i.e. ASCII
alphanumerical characters plus dash, dot, underscore and tilde) are
escaped. But if you specify characters in <parameter>reserved_chars_allowed</parameter>
they are not escaped. This is useful for the &quot;reserved&quot; characters
in the URI specification, since those are allowed unescaped in some
portions of a URI.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>unescaped</para></td><td class="parameter_description"><para>the unescaped input string.</para><para>Passed as <code>unescaped</code></para></td></tr><tr><td class="parameter_name"><para>reserved_chars_allowed</para></td><td class="parameter_description"><para>a string of reserved
  characters that are allowed to be used, or <constant>NULL</constant>.</para><para>Passed as <code>reserved-chars-allowed</code></para></td></tr><tr><td class="parameter_name"><para>allow_utf8</para></td><td class="parameter_description"><para><constant>TRUE</constant> if the result can include UTF-8 characters.</para><para>Passed as <code>allow-utf8</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:is-valid?</title><informalexample><programlisting>(define-values (%return) (uri:is-valid? uri-string flags))
</programlisting></informalexample><para>Parses <parameter>uri_string</parameter> according to <parameter>flags</parameter>, 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 <function>g_uri_parse_relative()</function>.
</para>
<para>If it’s not a valid URI, an error is returned explaining how it’s invalid.
</para>
<para>See <function>g_uri_split()</function>, and the definition of <type>GUriFlags</type>, for more
information on the effect of <parameter>flags</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri_string</para></td><td class="parameter_description"><para>a string containing an absolute URI</para><para>Passed as <code>uri-string</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags for parsing <parameter>uri_string</parameter></para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:join</title><informalexample><programlisting>(define-values
  (%return)
  (uri:join flags scheme userinfo host port path query fragment))
</programlisting></informalexample><para>Joins the given components together according to <parameter>flags</parameter> to create
an absolute URI string. <parameter>path</parameter> may not be <constant>NULL</constant> (though it may be the empty
string).
</para>
<para>When <parameter>host</parameter> is present, <parameter>path</parameter> must either be empty or begin with a slash (<code>/</code>)
character. When <parameter>host</parameter> is not present, <parameter>path</parameter> cannot begin with two slash
   characters (<code>//</code>). See
[RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3).
</para>
<para>See also <function>g_uri_join_with_user()</function>, which allows specifying the
components of the ‘userinfo’ separately.
</para>
<para><constant>G_URI_FLAGS_HAS_PASSWORD</constant> and <constant>G_URI_FLAGS_HAS_AUTH_PARAMS</constant> are ignored if set
in <parameter>flags</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags describing how to build the URI string</para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>scheme</para></td><td class="parameter_description"><para>the URI scheme, or <constant>NULL</constant></para><para>Passed as <code>scheme</code></para></td></tr><tr><td class="parameter_name"><para>userinfo</para></td><td class="parameter_description"><para>the userinfo component, or <constant>NULL</constant></para><para>Passed as <code>userinfo</code></para></td></tr><tr><td class="parameter_name"><para>host</para></td><td class="parameter_description"><para>the host component, or <constant>NULL</constant></para><para>Passed as <code>host</code></para></td></tr><tr><td class="parameter_name"><para>port</para></td><td class="parameter_description"><para>the port, or <code>-1</code></para><para>Passed as <code>port</code></para></td></tr><tr><td class="parameter_name"><para>path</para></td><td class="parameter_description"><para>the path component</para><para>Passed as <code>path</code></para></td></tr><tr><td class="parameter_name"><para>query</para></td><td class="parameter_description"><para>the query component, or <constant>NULL</constant></para><para>Passed as <code>query</code></para></td></tr><tr><td class="parameter_name"><para>fragment</para></td><td class="parameter_description"><para>the fragment, or <constant>NULL</constant></para><para>Passed as <code>fragment</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:join-with-user</title><informalexample><programlisting>(define-values
  (%return)
  (uri:join-with-user
    flags
    scheme
    user
    password
    auth-params
    host
    port
    path
    query
    fragment))
</programlisting></informalexample><para>Joins the given components together according to <parameter>flags</parameter> to create
an absolute URI string. <parameter>path</parameter> may not be <constant>NULL</constant> (though it may be the empty
string).
</para>
<para>In contrast to <function>g_uri_join()</function>, this allows specifying the components
of the ‘userinfo’ separately. It otherwise behaves the same.
</para>
<para><constant>G_URI_FLAGS_HAS_PASSWORD</constant> and <constant>G_URI_FLAGS_HAS_AUTH_PARAMS</constant> are ignored if set
in <parameter>flags</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags describing how to build the URI string</para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>scheme</para></td><td class="parameter_description"><para>the URI scheme, or <constant>NULL</constant></para><para>Passed as <code>scheme</code></para></td></tr><tr><td class="parameter_name"><para>user</para></td><td class="parameter_description"><para>the user component of the userinfo, or <constant>NULL</constant></para><para>Passed as <code>user</code></para></td></tr><tr><td class="parameter_name"><para>password</para></td><td class="parameter_description"><para>the password component of the userinfo, or
  <constant>NULL</constant></para><para>Passed as <code>password</code></para></td></tr><tr><td class="parameter_name"><para>auth_params</para></td><td class="parameter_description"><para>the auth params of the userinfo, or
  <constant>NULL</constant></para><para>Passed as <code>auth-params</code></para></td></tr><tr><td class="parameter_name"><para>host</para></td><td class="parameter_description"><para>the host component, or <constant>NULL</constant></para><para>Passed as <code>host</code></para></td></tr><tr><td class="parameter_name"><para>port</para></td><td class="parameter_description"><para>the port, or <code>-1</code></para><para>Passed as <code>port</code></para></td></tr><tr><td class="parameter_name"><para>path</para></td><td class="parameter_description"><para>the path component</para><para>Passed as <code>path</code></para></td></tr><tr><td class="parameter_name"><para>query</para></td><td class="parameter_description"><para>the query component, or <constant>NULL</constant></para><para>Passed as <code>query</code></para></td></tr><tr><td class="parameter_name"><para>fragment</para></td><td class="parameter_description"><para>the fragment, or <constant>NULL</constant></para><para>Passed as <code>fragment</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:list-extract-uris</title><informalexample><programlisting>(define-values (%return) (uri:list-extract-uris uri-list))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri_list</para></td><td class="parameter_description"><para>an URI list</para><para>Passed as <code>uri-list</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:parse</title><informalexample><programlisting>(define-values (%return) (uri:parse uri-string flags))
</programlisting></informalexample><para>Parses <parameter>uri_string</parameter> according to <parameter>flags</parameter>. If the result is not a
valid [absolute URI][relative-absolute-uris], it will be discarded, and an
error returned.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri_string</para></td><td class="parameter_description"><para>a string representing an absolute URI</para><para>Passed as <code>uri-string</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags describing how to parse <parameter>uri_string</parameter></para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:parse-params</title><informalexample><programlisting>(define-values (%return) (uri:parse-params params length separators flags))
</programlisting></informalexample><para>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
<type>GUriParamsIter</type>.
</para>
<para>The <parameter>params</parameter> string is assumed to still be <code>%</code>-encoded, but the returned
values will be fully decoded. (Thus it is possible that the returned values
may contain <code>=</code> or <parameter>separators</parameter>, if the value was encoded in the input.)
Invalid <code>%</code>-encoding is treated as with the <constant>G_URI_FLAGS_PARSE_RELAXED</constant>
rules for <function>g_uri_parse()</function>. (However, if <parameter>params</parameter> is the path or query string
from a <type>GUri</type> that was parsed without <constant>G_URI_FLAGS_PARSE_RELAXED</constant> and
<constant>G_URI_FLAGS_ENCODED</constant>, then you already know that it does not contain any
invalid encoding.)
</para>
<para><constant>G_URI_PARAMS_WWW_FORM</constant> is handled as documented for <function>g_uri_params_iter_init()</function>.
</para>
<para>If <constant>G_URI_PARAMS_CASE_INSENSITIVE</constant> is passed to <parameter>flags</parameter>, attributes will be
compared case-insensitively, so a params string <code>attr=123&amp;Attr=456</code> will only
return a single attribute–value pair, <code>Attr=456</code>. Case will be preserved in
the returned attributes.
</para>
<para>If <parameter>params</parameter> cannot be parsed (for example, it contains two <parameter>separators</parameter>
characters in a row), then <parameter>error</parameter> is set and <constant>NULL</constant> is returned.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>params</para></td><td class="parameter_description"><para>a <code>%</code>-encoded string containing <code>attribute=value</code>
  parameters</para><para>Passed as <code>params</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of <parameter>params</parameter>, or <code>-1</code> if it is nul-terminated</para><para>Passed as <code>length</code></para></td></tr><tr><td class="parameter_name"><para>separators</para></td><td class="parameter_description"><para>the separator byte character set between parameters. (usually
  <code>&amp;</code>, but sometimes <code>;</code> or both <code>&amp;;</code>). 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.</para><para>Passed as <code>separators</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags to modify the way the parameters are handled.</para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:parse-scheme</title><informalexample><programlisting>(define-values (%return) (uri:parse-scheme uri))
</programlisting></informalexample><para>Gets the scheme portion of a URI string.
[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
as:
<informalexample><programlisting>
URI = scheme &quot;:&quot; hier-part [ &quot;?&quot; query ] [ &quot;#&quot; fragment ]
</programlisting></informalexample></para>
<para>Common schemes include <code>file</code>, <code>https</code>, <code>svn+ssh</code>, etc.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a valid URI.</para><para>Passed as <code>uri</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:peek-scheme</title><informalexample><programlisting>(define-values (%return) (uri:peek-scheme uri))
</programlisting></informalexample><para>Gets the scheme portion of a URI string.
[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
as:
<informalexample><programlisting>
URI = scheme &quot;:&quot; hier-part [ &quot;?&quot; query ] [ &quot;#&quot; fragment ]
</programlisting></informalexample></para>
<para>Common schemes include <code>file</code>, <code>https</code>, <code>svn+ssh</code>, etc.
</para>
<para>Unlike <function>g_uri_parse_scheme()</function>, the returned scheme is normalized to
all-lowercase and does not need to be freed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a valid URI.</para><para>Passed as <code>uri</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:resolve-relative</title><informalexample><programlisting>(define-values (%return) (uri:resolve-relative base-uri-string uri-ref flags))
</programlisting></informalexample><para>Parses <parameter>uri_ref</parameter> according to <parameter>flags</parameter> and, if it is a
[relative URI][relative-absolute-uris], resolves it relative to
<parameter>base_uri_string</parameter>. If the result is not a valid absolute URI, it will be
discarded, and an error returned.
</para>
<para>(If <parameter>base_uri_string</parameter> is <constant>NULL</constant>, this just returns <parameter>uri_ref</parameter>, or
<constant>NULL</constant> if <parameter>uri_ref</parameter> is invalid or not absolute.)</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>base_uri_string</para></td><td class="parameter_description"><para>a string representing a base URI</para><para>Passed as <code>base-uri-string</code></para></td></tr><tr><td class="parameter_name"><para>uri_ref</para></td><td class="parameter_description"><para>a string representing a relative or absolute URI</para><para>Passed as <code>uri-ref</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags describing how to parse <parameter>uri_ref</parameter></para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:split</title><informalexample><programlisting>(define-values
  (%return scheme userinfo host port path query fragment)
  (uri:split uri-ref flags))
</programlisting></informalexample><para>Parses <parameter>uri_ref</parameter> (which can be an
[absolute or relative URI][relative-absolute-uris]) according to <parameter>flags</parameter>, and
returns the pieces. Any component that doesn't appear in <parameter>uri_ref</parameter> will be
returned as <constant>NULL</constant> (but note that all URIs always have a path component,
though it may be the empty string).
</para>
<para>If <parameter>flags</parameter> contains <constant>G_URI_FLAGS_ENCODED</constant>, then <code>%</code>-encoded characters in
<parameter>uri_ref</parameter> 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 <constant>G_URI_FLAGS_ENCODED</constant> if they are not.
</para>
<para>Note that the <constant>G_URI_FLAGS_HAS_PASSWORD</constant> and
<constant>G_URI_FLAGS_HAS_AUTH_PARAMS</constant> <parameter>flags</parameter> are ignored by <function>g_uri_split()</function>,
since it always returns only the full userinfo; use
<function>g_uri_split_with_user()</function> if you want it split up.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri_ref</para></td><td class="parameter_description"><para>a string containing a relative or absolute URI</para><para>Passed as <code>uri-ref</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags for parsing <parameter>uri_ref</parameter></para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>scheme</para></td><td class="parameter_description"><para>on return, contains
   the scheme (converted to lowercase), or <constant>NULL</constant></para><para>Passed as <code>scheme</code></para></td></tr><tr><td class="parameter_name"><para>userinfo</para></td><td class="parameter_description"><para>on return, contains
   the userinfo, or <constant>NULL</constant></para><para>Passed as <code>userinfo</code></para></td></tr><tr><td class="parameter_name"><para>host</para></td><td class="parameter_description"><para>on return, contains the
   host, or <constant>NULL</constant></para><para>Passed as <code>host</code></para></td></tr><tr><td class="parameter_name"><para>port</para></td><td class="parameter_description"><para>on return, contains the
   port, or <code>-1</code></para><para>Passed as <code>port</code></para></td></tr><tr><td class="parameter_name"><para>path</para></td><td class="parameter_description"><para>on return, contains the
   path</para><para>Passed as <code>path</code></para></td></tr><tr><td class="parameter_name"><para>query</para></td><td class="parameter_description"><para>on return, contains the
   query, or <constant>NULL</constant></para><para>Passed as <code>query</code></para></td></tr><tr><td class="parameter_name"><para>fragment</para></td><td class="parameter_description"><para>on return, contains
   the fragment, or <constant>NULL</constant></para><para>Passed as <code>fragment</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:split-network</title><informalexample><programlisting>(define-values
  (%return scheme host port)
  (uri:split-network uri-string flags))
</programlisting></informalexample><para>Parses <parameter>uri_string</parameter> (which must be an [absolute URI][relative-absolute-uris])
according to <parameter>flags</parameter>, and returns the pieces relevant to connecting to a host.
See the documentation for <function>g_uri_split()</function> for more details; this is
mostly a wrapper around that function with simpler arguments.
However, it will return an error if <parameter>uri_string</parameter> is a relative URI,
or does not contain a hostname component.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri_string</para></td><td class="parameter_description"><para>a string containing an absolute URI</para><para>Passed as <code>uri-string</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags for parsing <parameter>uri_string</parameter></para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>scheme</para></td><td class="parameter_description"><para>on return, contains
   the scheme (converted to lowercase), or <constant>NULL</constant></para><para>Passed as <code>scheme</code></para></td></tr><tr><td class="parameter_name"><para>host</para></td><td class="parameter_description"><para>on return, contains the
   host, or <constant>NULL</constant></para><para>Passed as <code>host</code></para></td></tr><tr><td class="parameter_name"><para>port</para></td><td class="parameter_description"><para>on return, contains the
   port, or <code>-1</code></para><para>Passed as <code>port</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:split-with-user</title><informalexample><programlisting>(define-values
  (%return scheme user password auth-params host port path query fragment)
  (uri:split-with-user uri-ref flags))
</programlisting></informalexample><para>Parses <parameter>uri_ref</parameter> (which can be an
[absolute or relative URI][relative-absolute-uris]) according to <parameter>flags</parameter>, and
returns the pieces. Any component that doesn't appear in <parameter>uri_ref</parameter> will be
returned as <constant>NULL</constant> (but note that all URIs always have a path component,
though it may be the empty string).
</para>
<para>See <function>g_uri_split()</function>, and the definition of <type>GUriFlags</type>, for more
information on the effect of <parameter>flags</parameter>. Note that <parameter>password</parameter> will only
be parsed out if <parameter>flags</parameter> contains <constant>G_URI_FLAGS_HAS_PASSWORD</constant>, and
<parameter>auth_params</parameter> will only be parsed out if <parameter>flags</parameter> contains
<constant>G_URI_FLAGS_HAS_AUTH_PARAMS</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri_ref</para></td><td class="parameter_description"><para>a string containing a relative or absolute URI</para><para>Passed as <code>uri-ref</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags for parsing <parameter>uri_ref</parameter></para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>scheme</para></td><td class="parameter_description"><para>on return, contains
   the scheme (converted to lowercase), or <constant>NULL</constant></para><para>Passed as <code>scheme</code></para></td></tr><tr><td class="parameter_name"><para>user</para></td><td class="parameter_description"><para>on return, contains
   the user, or <constant>NULL</constant></para><para>Passed as <code>user</code></para></td></tr><tr><td class="parameter_name"><para>password</para></td><td class="parameter_description"><para>on return, contains
   the password, or <constant>NULL</constant></para><para>Passed as <code>password</code></para></td></tr><tr><td class="parameter_name"><para>auth_params</para></td><td class="parameter_description"><para>on return, contains
   the auth_params, or <constant>NULL</constant></para><para>Passed as <code>auth-params</code></para></td></tr><tr><td class="parameter_name"><para>host</para></td><td class="parameter_description"><para>on return, contains the
   host, or <constant>NULL</constant></para><para>Passed as <code>host</code></para></td></tr><tr><td class="parameter_name"><para>port</para></td><td class="parameter_description"><para>on return, contains the
   port, or <code>-1</code></para><para>Passed as <code>port</code></para></td></tr><tr><td class="parameter_name"><para>path</para></td><td class="parameter_description"><para>on return, contains the
   path</para><para>Passed as <code>path</code></para></td></tr><tr><td class="parameter_name"><para>query</para></td><td class="parameter_description"><para>on return, contains the
   query, or <constant>NULL</constant></para><para>Passed as <code>query</code></para></td></tr><tr><td class="parameter_name"><para>fragment</para></td><td class="parameter_description"><para>on return, contains
   the fragment, or <constant>NULL</constant></para><para>Passed as <code>fragment</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:unescape-bytes</title><informalexample><programlisting>(define-values
  (%return)
  (uri:unescape-bytes escaped-string length illegal-characters))
</programlisting></informalexample><para>Unescapes a segment of an escaped string as binary data.
</para>
<para>Note that in contrast to <function>g_uri_unescape_string()</function>, this does allow
nul bytes to appear in the output.
</para>
<para>If any of the characters in <parameter>illegal_characters</parameter> appears as an escaped
character in <parameter>escaped_string</parameter>, then that is an error and <constant>NULL</constant> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>escaped_string</para></td><td class="parameter_description"><para>A URI-escaped string</para><para>Passed as <code>escaped-string</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length (in bytes) of <parameter>escaped_string</parameter> to escape, or <code>-1</code> if it
  is nul-terminated.</para><para>Passed as <code>length</code></para></td></tr><tr><td class="parameter_name"><para>illegal_characters</para></td><td class="parameter_description"><para>a string of illegal characters
  not to be allowed, or <constant>NULL</constant>.</para><para>Passed as <code>illegal-characters</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:unescape-segment</title><informalexample><programlisting>(define-values
  (%return)
  (uri:unescape-segment escaped-string escaped-string-end illegal-characters))
</programlisting></informalexample><para>Unescapes a segment of an escaped string.
</para>
<para>If any of the characters in <parameter>illegal_characters</parameter> or the NUL
character appears as an escaped character in <parameter>escaped_string</parameter>, then
that is an error and <constant>NULL</constant> 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.
</para>
<para>Note: <code>NUL</code> byte is not accepted in the output, in contrast to
<function>g_uri_unescape_bytes()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>escaped_string</para></td><td class="parameter_description"><para>A string, may be <constant>NULL</constant></para><para>Passed as <code>escaped-string</code></para></td></tr><tr><td class="parameter_name"><para>escaped_string_end</para></td><td class="parameter_description"><para>Pointer to end of <parameter>escaped_string</parameter>,
  may be <constant>NULL</constant></para><para>Passed as <code>escaped-string-end</code></para></td></tr><tr><td class="parameter_name"><para>illegal_characters</para></td><td class="parameter_description"><para>An optional string of illegal
  characters not to be allowed, may be <constant>NULL</constant></para><para>Passed as <code>illegal-characters</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri:unescape-string</title><informalexample><programlisting>(define-values
  (%return)
  (uri:unescape-string escaped-string illegal-characters))
</programlisting></informalexample><para>Unescapes a whole escaped string.
</para>
<para>If any of the characters in <parameter>illegal_characters</parameter> or the NUL
character appears as an escaped character in <parameter>escaped_string</parameter>, then
that is an error and <constant>NULL</constant> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>escaped_string</para></td><td class="parameter_description"><para>an escaped string to be unescaped.</para><para>Passed as <code>escaped-string</code></para></td></tr><tr><td class="parameter_name"><para>illegal_characters</para></td><td class="parameter_description"><para>a string of illegal characters
  not to be allowed, or <constant>NULL</constant>.</para><para>Passed as <code>illegal-characters</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibUriError&gt;</refname></refnamediv><refsect1><title>Description</title><para>Error codes returned by <type>GUri</type> methods.</para></refsect1><refsect1><title>Members</title><refsect2><title>failed</title><remark>alias <code>G_URI_ERROR_FAILED</code></remark><para>Generic error if no more specific error is available.
    See the error message for details.</para></refsect2><refsect2><title>bad-scheme</title><remark>alias <code>G_URI_ERROR_BAD_SCHEME</code></remark><para>The scheme of a URI could not be parsed.</para></refsect2><refsect2><title>bad-user</title><remark>alias <code>G_URI_ERROR_BAD_USER</code></remark><para>The user/userinfo of a URI could not be parsed.</para></refsect2><refsect2><title>bad-password</title><remark>alias <code>G_URI_ERROR_BAD_PASSWORD</code></remark><para>The password of a URI could not be parsed.</para></refsect2><refsect2><title>bad-auth-params</title><remark>alias <code>G_URI_ERROR_BAD_AUTH_PARAMS</code></remark><para>The authentication parameters of a URI could not be parsed.</para></refsect2><refsect2><title>bad-host</title><remark>alias <code>G_URI_ERROR_BAD_HOST</code></remark><para>The host of a URI could not be parsed.</para></refsect2><refsect2><title>bad-port</title><remark>alias <code>G_URI_ERROR_BAD_PORT</code></remark><para>The port of a URI could not be parsed.</para></refsect2><refsect2><title>bad-path</title><remark>alias <code>G_URI_ERROR_BAD_PATH</code></remark><para>The path of a URI could not be parsed.</para></refsect2><refsect2><title>bad-query</title><remark>alias <code>G_URI_ERROR_BAD_QUERY</code></remark><para>The query of a URI could not be parsed.</para></refsect2><refsect2><title>bad-fragment</title><remark>alias <code>G_URI_ERROR_BAD_FRAGMENT</code></remark><para>The fragment of a URI could not be parsed.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibUriFlags&gt;</refname></refnamediv><refsect1><title>Description</title><para>Flags that describe a URI.
</para>
<para>When parsing a URI, if you need to choose different flags based on
the type of URI, you can use <function>g_uri_peek_scheme()</function> on the URI string
to check the scheme first, and use that to decide what flags to
parse it with.</para></refsect1><refsect1><title>Members</title><refsect2><title>none</title><remark>alias <code>G_URI_FLAGS_NONE</code></remark><para>No flags set.</para></refsect2><refsect2><title>parse-relaxed</title><remark>alias <code>G_URI_FLAGS_PARSE_RELAXED</code></remark><para>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 <code>;</code>
    separates the host from the path. Don’t use this flag unless you need to.</para></refsect2><refsect2><title>has-password</title><remark>alias <code>G_URI_FLAGS_HAS_PASSWORD</code></remark><para>The userinfo field may contain a password,
    which will be separated from the username by <code>:</code>.</para></refsect2><refsect2><title>has-auth-params</title><remark>alias <code>G_URI_FLAGS_HAS_AUTH_PARAMS</code></remark><para>The userinfo may contain additional
    authentication-related parameters, which will be separated from
    the username and/or password by <code>;</code>.</para></refsect2><refsect2><title>encoded</title><remark>alias <code>G_URI_FLAGS_ENCODED</code></remark><para>When parsing a URI, this indicates that <code>%</code>-encoded
    characters in the userinfo, path, query, and fragment fields
    should not be decoded. (And likewise the host field if
    <constant>G_URI_FLAGS_NON_DNS</constant> is also set.) When building a URI, it indicates
    that you have already <code>%</code>-encoded the components, and so <type>GUri</type>
    should not do any encoding itself.</para></refsect2><refsect2><title>non-dns</title><remark>alias <code>G_URI_FLAGS_NON_DNS</code></remark><para>The host component should not be assumed to be a
    DNS hostname or IP address (for example, for <code>smb</code> URIs with NetBIOS
    hostnames).</para></refsect2><refsect2><title>encoded-query</title><remark>alias <code>G_URI_FLAGS_ENCODED_QUERY</code></remark><para>Same as <constant>G_URI_FLAGS_ENCODED</constant>, for the query
    field only.</para></refsect2><refsect2><title>encoded-path</title><remark>alias <code>G_URI_FLAGS_ENCODED_PATH</code></remark><para>Same as <constant>G_URI_FLAGS_ENCODED</constant>, for the path only.</para></refsect2><refsect2><title>encoded-fragment</title><remark>alias <code>G_URI_FLAGS_ENCODED_FRAGMENT</code></remark><para>Same as <constant>G_URI_FLAGS_ENCODED</constant>, for the
    fragment only.</para></refsect2><refsect2><title>scheme-normalize</title><remark>alias <code>G_URI_FLAGS_SCHEME_NORMALIZE</code></remark><para>A scheme-based normalization will be applied.
    For example, when parsing an HTTP URI changing omitted path to <code>/</code> and
    omitted port to <code>80</code>; and when building a URI, changing empty path to <code>/</code>
    and default port <code>80</code>). This only supports a subset of known schemes. (Since: 2.68)</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibUriHideFlags&gt;</refname></refnamediv><refsect1><title>Description</title><para>Flags describing what parts of the URI to hide in
<function>g_uri_to_string_partial()</function>. Note that <constant>G_URI_HIDE_PASSWORD</constant> and
<constant>G_URI_HIDE_AUTH_PARAMS</constant> will only work if the <type>GUri</type> was parsed with
the corresponding flags.</para></refsect1><refsect1><title>Members</title><refsect2><title>none</title><remark>alias <code>G_URI_HIDE_NONE</code></remark><para>No flags set.</para></refsect2><refsect2><title>userinfo</title><remark>alias <code>G_URI_HIDE_USERINFO</code></remark><para>Hide the userinfo.</para></refsect2><refsect2><title>password</title><remark>alias <code>G_URI_HIDE_PASSWORD</code></remark><para>Hide the password.</para></refsect2><refsect2><title>auth-params</title><remark>alias <code>G_URI_HIDE_AUTH_PARAMS</code></remark><para>Hide the auth_params.</para></refsect2><refsect2><title>query</title><remark>alias <code>G_URI_HIDE_QUERY</code></remark><para>Hide the query.</para></refsect2><refsect2><title>fragment</title><remark>alias <code>G_URI_HIDE_FRAGMENT</code></remark><para>Hide the fragment.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibUriParamsFlags&gt;</refname></refnamediv><refsect1><title>Description</title><para>Flags modifying the way parameters are handled by <function>g_uri_parse_params()</function> and
<type>GUriParamsIter</type>.</para></refsect1><refsect1><title>Members</title><refsect2><title>none</title><remark>alias <code>G_URI_PARAMS_NONE</code></remark><para>No flags set.</para></refsect2><refsect2><title>case-insensitive</title><remark>alias <code>G_URI_PARAMS_CASE_INSENSITIVE</code></remark><para>Parameter names are case insensitive.</para></refsect2><refsect2><title>www-form</title><remark>alias <code>G_URI_PARAMS_WWW_FORM</code></remark><para>Replace <code>+</code> with space character. Only useful for
    URLs on the web, using the <code>https</code> or <code>http</code> schemas.</para></refsect2><refsect2><title>parse-relaxed</title><remark>alias <code>G_URI_PARAMS_PARSE_RELAXED</code></remark><para>See <constant>G_URI_FLAGS_PARSE_RELAXED</constant>.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibUserDirectory&gt;</refname></refnamediv><refsect1><title>Description</title><para>These are logical ids for special directories which are defined
depending on the platform used. You should use <function>g_get_user_special_dir()</function>
to retrieve the full path associated to the logical id.
</para>
<para>The <type>GUserDirectory</type> enumeration can be extended at later date. Not
every platform has a directory for every logical id in this
enumeration.</para></refsect1><refsect1><title>Members</title><refsect2><title>directory-desktop</title><remark>alias <code>G_USER_DIRECTORY_DESKTOP</code></remark><para>the user's Desktop directory</para></refsect2><refsect2><title>directory-documents</title><remark>alias <code>G_USER_DIRECTORY_DOCUMENTS</code></remark><para>the user's Documents directory</para></refsect2><refsect2><title>directory-download</title><remark>alias <code>G_USER_DIRECTORY_DOWNLOAD</code></remark><para>the user's Downloads directory</para></refsect2><refsect2><title>directory-music</title><remark>alias <code>G_USER_DIRECTORY_MUSIC</code></remark><para>the user's Music directory</para></refsect2><refsect2><title>directory-pictures</title><remark>alias <code>G_USER_DIRECTORY_PICTURES</code></remark><para>the user's Pictures directory</para></refsect2><refsect2><title>directory-public-share</title><remark>alias <code>G_USER_DIRECTORY_PUBLIC_SHARE</code></remark><para>the user's shared directory</para></refsect2><refsect2><title>directory-templates</title><remark>alias <code>G_USER_DIRECTORY_TEMPLATES</code></remark><para>the user's Templates directory</para></refsect2><refsect2><title>directory-videos</title><remark>alias <code>G_USER_DIRECTORY_VIDEOS</code></remark><para>the user's Movies directory</para></refsect2><refsect2><title>n-directories</title><remark>alias <code>G_USER_N_DIRECTORIES</code></remark><para>the number of enum values</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GVariant&gt;</refname></refnamediv><refsect1><title>Description</title><para><type>GVariant</type> is a variant datatype; it can contain one or more values
along with information about the type of the values.
</para>
<para>A <type>GVariant</type> 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 <type>GVariant</type> is also immutable: once it's been created neither
its type nor its content can be modified further.
</para>
<para>GVariant is useful whenever data needs to be serialized, for example when
sending method parameters in DBus, or when saving settings using GSettings.
</para>
<para>When creating a new <type>GVariant</type>, 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.
</para>
<para>For instance, if you want to create a <type>GVariant</type> holding an integer value you
can use:
</para>
<para><informalexample><programlisting>
  GVariant *v = g_variant_new (&quot;u&quot;, 40);
</programlisting></informalexample></para>

<para>The string &quot;u&quot; in the first argument tells <type>GVariant</type> that the data passed to
the constructor (40) is going to be an unsigned integer.
</para>
<para>More advanced examples of <type>GVariant</type> in use can be found in documentation for
[GVariant format strings][gvariant-format-strings-pointers].
</para>
<para>The range of possible values is determined by the type.
</para>
<para>The type system used by <type>GVariant</type> is <type>GVariantType</type>.
</para>
<para><type>GVariant</type> instances always have a type and a value (which are given
at construction time).  The type and value of a <type>GVariant</type> instance
can never change other than by the <type>GVariant</type> itself being
destroyed.  A <type>GVariant</type> cannot contain a pointer.
</para>
<para><type>GVariant</type> is reference counted using <function>g_variant_ref()</function> and
<function>g_variant_unref()</function>.  <type>GVariant</type> also has floating reference counts --
see <function>g_variant_ref_sink()</function>.
</para>
<para><type>GVariant</type> is completely threadsafe.  A <type>GVariant</type> instance can be
concurrently accessed in any way from any number of threads without
problems.
</para>
<para><type>GVariant</type> 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 <type>GVariant</type> data can also be sent over the network.
</para>
<para><type>GVariant</type> is largely compatible with D-Bus.  Almost all types of
<type>GVariant</type> instances can be sent over D-Bus.  See <type>GVariantType</type> for
exceptions.  (However, <type>GVariant</type>'s serialisation format is not the same
as the serialisation format of a D-Bus message body: use <type>GDBusMessage</type>,
in the gio library, for those.)
</para>
<para>For space-efficiency, the <type>GVariant</type> 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
<constant>G_VARIANT_TYPE_VARIANT</constant> 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).
</para>
<para>A <type>GVariant</type>'s size is limited mainly by any lower level operating
system constraints, such as the number of bits in <type>gsize</type>.  For
example, it is reasonable to have a 2GB file mapped into memory
with <type>GMappedFile</type>, and call <function>g_variant_new_from_data()</function> on it.
</para>
<para>For convenience to C programmers, <type>GVariant</type> features powerful
varargs-based value construction and destruction.  This feature is
designed to be embedded in other libraries.
</para>
<para>There is a Python-inspired text language for describing <type>GVariant</type>
values.  <type>GVariant</type> includes a printer for this language and a parser
with type inferencing.
</para>
<refsect2><title>Memory Use</title>
<para><type>GVariant</type> 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.
</para>
<para>The memory allocated by <type>GVariant</type> can be grouped into 4 broad
purposes: memory for serialised data, memory for the type
information cache, buffer management memory and memory for the
<type>GVariant</type> structure itself.
</para>
</refsect2><refsect2><title>Serialised Data Memory</title>
<para>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.
</para>
<para>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 &quot;natural&quot; 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.
</para>
<para>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.
</para>
<para>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.
</para>
<para>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.
</para>
<para>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.
</para>
<para>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.
</para>
<para>If we add an item &quot;width&quot; 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.
</para>
<para>If we add another entry, &quot;title&quot; 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.
</para>
<para>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.
</para>
</refsect2><refsect2><title>Type Information Cache</title>
<para>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.
</para>
<para>Continuing with the above example, if a <type>GVariant</type> exists with the
type &quot;a{sv}&quot; then a type information struct will exist for
&quot;a{sv}&quot;, &quot;{sv}&quot;, &quot;s&quot;, and &quot;v&quot;.  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
<type>GVariant</type>.
</para>
<para>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.
</para>
<para>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 &quot;a{sv}&quot; would require 30
bytes of memory (plus malloc overhead).
</para>
<para>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
&quot;{sv}&quot; would require 61 bytes of memory (plus malloc overhead).
</para>
<para>This means that in total, for our &quot;a{sv}&quot; example, 91 bytes of
type information would be allocated.
</para>
<para>The type information cache, additionally, uses a <type>GHashTable</type> 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.
</para>
<para>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.
</para>
</refsect2><refsect2><title>Buffer Management Memory</title>
<para><type>GVariant</type> 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
<type>GVariant</type>.  This may involve a <function>g_free()</function> or a <function>g_slice_free()</function> or
even <function>g_mapped_file_unref()</function>.
</para>
<para>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.
</para>
</refsect2><refsect2><title>GVariant structure</title>
<para>The size of a <type>GVariant</type> structure is 6 * (void *).  On 32-bit
systems, that's 24 bytes.
</para>
<para><type>GVariant</type> structures only exist if they are explicitly created
with API calls.  For example, if a <type>GVariant</type> 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 <type>GVariant</type> instance exists -- the one referring to the
dictionary.
</para>
<para>If calls are made to start accessing the other values then
<type>GVariant</type> instances will exist for those values only for as long
as they are in use (ie: until you call <function>g_variant_unref()</function>).  The
type information is shared.  The serialised data and the buffer
management structure for that serialised data is shared by the
child.
</para>
</refsect2><refsect2><title>Summary</title>
<para>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 <type>GVariant</type> instance, or a total of 160 bytes, plus
malloc overhead.  If we were to use <function>g_variant_get_child_value()</function> 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.</para></refsect2></refsect1><refsect1><title>Functions</title><refsect2><title>byteswap</title><informalexample><programlisting>(define-values (%return) (variant:byteswap self))
</programlisting></informalexample><para>Performs a byteswapping operation on the contents of <parameter>value</parameter>.  The
result is that all multi-byte numeric data contained in <parameter>value</parameter> is
byteswapped.  That includes 16, 32, and 64bit signed and unsigned
integers as well as file handles and double precision floating point
values.
</para>
<para>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).
</para>
<para>The returned value is always in normal form and is marked as trusted.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>check-format-string?</title><informalexample><programlisting>(define-values
  (%return)
  (variant:check-format-string? self format-string copy-only))
</programlisting></informalexample><para>Checks if calling <function>g_variant_get()</function> with <parameter>format_string</parameter> on <parameter>value</parameter> would
be valid from a type-compatibility standpoint.  <parameter>format_string</parameter> is
assumed to be a valid format string (from a syntactic standpoint).
</para>
<para>If <parameter>copy_only</parameter> is <constant>TRUE</constant> then this function additionally checks that it
would be safe to call <function>g_variant_unref()</function> on <parameter>value</parameter> immediately after
the call to <function>g_variant_get()</function> 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 <type>GVariant</type> instance).  If this
check fails then a <function>g_critical()</function> is printed and <constant>FALSE</constant> is returned.
</para>
<para>This function is meant to be used by functions that wish to provide
varargs accessors to <type>GVariant</type> values of uncertain values (eg:
<function>g_variant_lookup()</function> or <function>g_menu_model_get_item_attribute()</function>).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>format_string</para></td><td class="parameter_description"><para>a valid <type>GVariant</type> format string</para><para>Passed as <code>format-string</code></para></td></tr><tr><td class="parameter_name"><para>copy_only</para></td><td class="parameter_description"><para><constant>TRUE</constant> to ensure the format string makes deep copies</para><para>Passed as <code>copy-only</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>classify</title><informalexample><programlisting>(define-values (%return) (variant:classify self))
</programlisting></informalexample><para>Classifies <parameter>value</parameter> according to its top-level type.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>compare</title><informalexample><programlisting>(define-values (%return) (variant:compare self two))
</programlisting></informalexample><para>Compares <parameter>one</parameter> and <parameter>two</parameter>.
</para>
<para>The types of <parameter>one</parameter> and <parameter>two</parameter> are <type>gconstpointer</type> only to allow use of
this function with <type>GTree</type>, <type>GPtrArray</type>, etc.  They must each be a
<type>GVariant</type>.
</para>
<para>Comparison is only defined for basic types (ie: booleans, numbers,
strings).  For booleans, <constant>FALSE</constant> is less than <constant>TRUE</constant>.  Numbers are
ordered in the usual way.  Strings are in ASCII lexographical order.
</para>
<para>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.
</para>
<para>If you only require an equality comparison, <function>g_variant_equal()</function> is more
general.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>one</para></td><td class="parameter_description"><para>a basic-typed <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>two</para></td><td class="parameter_description"><para>a <type>GVariant</type> instance of the same type</para><para>Passed as <code>two</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>dup-bytestring</title><informalexample><programlisting>(define-values (%return length) (variant:dup-bytestring self))
</programlisting></informalexample><para>Similar to <function>g_variant_get_bytestring()</function> except that instead of
returning a constant string, the string is duplicated.
</para>
<para>The return value must be freed using <function>g_free()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>an array-of-bytes <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>a pointer to a <type>gsize</type>, to store
         the length (not including the nul terminator)</para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>dup-bytestring-array</title><informalexample><programlisting>(define-values (%return length) (variant:dup-bytestring-array self))
</programlisting></informalexample><para>Gets the contents of an array of array of bytes <type>GVariant</type>.  This call
makes a deep copy; the return result should be released with
<function>g_strfreev()</function>.
</para>
<para>If <parameter>length</parameter> is non-<constant>NULL</constant> then the number of elements in the result is
stored there.  In any case, the resulting array will be
<constant>NULL</constant>-terminated.
</para>
<para>For an empty array, <parameter>length</parameter> will be set to 0 and a pointer to a
<constant>NULL</constant> pointer will be returned.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>an array of array of bytes <type>GVariant</type> ('aay')</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of the result, or <constant>NULL</constant></para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>dup-objv</title><informalexample><programlisting>(define-values (%return length) (variant:dup-objv self))
</programlisting></informalexample><para>Gets the contents of an array of object paths <type>GVariant</type>.  This call
makes a deep copy; the return result should be released with
<function>g_strfreev()</function>.
</para>
<para>If <parameter>length</parameter> is non-<constant>NULL</constant> then the number of elements in the result
is stored there.  In any case, the resulting array will be
<constant>NULL</constant>-terminated.
</para>
<para>For an empty array, <parameter>length</parameter> will be set to 0 and a pointer to a
<constant>NULL</constant> pointer will be returned.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>an array of object paths <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of the result, or <constant>NULL</constant></para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>dup-string</title><informalexample><programlisting>(define-values (%return length) (variant:dup-string self))
</programlisting></informalexample><para>Similar to <function>g_variant_get_string()</function> except that instead of returning
a constant string, the string is duplicated.
</para>
<para>The string will always be UTF-8 encoded.
</para>
<para>The return value must be freed using <function>g_free()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a string <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>a pointer to a <type>gsize</type>, to store the length</para><para>Passed as <code>length</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>dup-strv</title><informalexample><programlisting>(define-values (%return length) (variant:dup-strv self))
</programlisting></informalexample><para>Gets the contents of an array of strings <type>GVariant</type>.  This call
makes a deep copy; the return result should be released with
<function>g_strfreev()</function>.
</para>
<para>If <parameter>length</parameter> is non-<constant>NULL</constant> then the number of elements in the result
is stored there.  In any case, the resulting array will be
<constant>NULL</constant>-terminated.
</para>
<para>For an empty array, <parameter>length</parameter> will be set to 0 and a pointer to a
<constant>NULL</constant> pointer will be returned.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>an array of strings <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of the result, or <constant>NULL</constant></para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>equal?</title><informalexample><programlisting>(define-values (%return) (variant:equal? self two))
</programlisting></informalexample><para>Checks if <parameter>one</parameter> and <parameter>two</parameter> have the same type and value.
</para>
<para>The types of <parameter>one</parameter> and <parameter>two</parameter> are <type>gconstpointer</type> only to allow use of
this function with <type>GHashTable</type>.  They must each be a <type>GVariant</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>one</para></td><td class="parameter_description"><para>a <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>two</para></td><td class="parameter_description"><para>a <type>GVariant</type> instance</para><para>Passed as <code>two</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-boolean?</title><informalexample><programlisting>(define-values (%return) (variant:get-boolean? self))
</programlisting></informalexample><para>Returns the boolean value of <parameter>value</parameter>.
</para>
<para>It is an error to call this function with a <parameter>value</parameter> of any type
other than <constant>G_VARIANT_TYPE_BOOLEAN</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a boolean <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-byte</title><informalexample><programlisting>(define-values (%return) (variant:get-byte self))
</programlisting></informalexample><para>Returns the byte value of <parameter>value</parameter>.
</para>
<para>It is an error to call this function with a <parameter>value</parameter> of any type
other than <constant>G_VARIANT_TYPE_BYTE</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a byte <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-bytestring</title><informalexample><programlisting>(define-values (%return) (variant:get-bytestring self))
</programlisting></informalexample><para>Returns the string value of a <type>GVariant</type> instance with an
array-of-bytes type.  The string has no particular encoding.
</para>
<para>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-<constant>NULL</constant> nul-terminated string will be returned by this function.
</para>
<para>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.
</para>
<para><function>g_variant_get_fixed_array()</function> should be used instead if the array contains
arbitrary data that could not be nul-terminated or could contain nul bytes.
</para>
<para>It is an error to call this function with a <parameter>value</parameter> that is not an
array of bytes.
</para>
<para>The return value remains valid as long as <parameter>value</parameter> exists.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>an array-of-bytes <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-bytestring-array</title><informalexample><programlisting>(define-values (%return length) (variant:get-bytestring-array self))
</programlisting></informalexample><para>Gets the contents of an array of array of bytes <type>GVariant</type>.  This call
makes a shallow copy; the return result should be released with
<function>g_free()</function>, but the individual strings must not be modified.
</para>
<para>If <parameter>length</parameter> is non-<constant>NULL</constant> then the number of elements in the result is
stored there.  In any case, the resulting array will be
<constant>NULL</constant>-terminated.
</para>
<para>For an empty array, <parameter>length</parameter> will be set to 0 and a pointer to a
<constant>NULL</constant> pointer will be returned.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>an array of array of bytes <type>GVariant</type> ('aay')</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of the result, or <constant>NULL</constant></para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-child-value</title><informalexample><programlisting>(define-values (%return) (variant:get-child-value self index-))
</programlisting></informalexample><para>Reads a child item out of a container <type>GVariant</type> instance.  This
includes variants, maybes, arrays, tuples and dictionary
entries.  It is an error to call this function on any other type of
<type>GVariant</type>.
</para>
<para>It is an error if <parameter>index_</parameter> is greater than the number of child items
in the container.  See <function>g_variant_n_children()</function>.
</para>
<para>The returned value is never floating.  You should free it with
<function>g_variant_unref()</function> when you're done with it.
</para>
<para>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 <parameter>value</parameter>, if <parameter>value</parameter> has not been serialised at the time this function is
called. To avoid this, you can serialize <parameter>value</parameter> by calling
<function>g_variant_get_data()</function> and optionally ignoring the return value.
</para>
<para>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. <type>GVariant</type> is guaranteed to handle
nesting up to at least 64 levels.
</para>
<para>This function is O(1).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a container <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>index_</para></td><td class="parameter_description"><para>the index of the child to fetch</para><para>Passed as <code>index-</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-data</title><informalexample><programlisting>(define-values (%return) (variant:get-data self))
</programlisting></informalexample><para>Returns a pointer to the serialised form of a <type>GVariant</type> 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 <parameter>value</parameter> exists.
</para>
<para>If <parameter>value</parameter> is a fixed-sized value that was deserialised from a
corrupted serialised container then <constant>NULL</constant> may be returned.  In this
case, the proper thing to do is typically to use the appropriate
number of nul bytes in place of <parameter>value</parameter>.  If <parameter>value</parameter> is not fixed-sized
then <constant>NULL</constant> is never returned.
</para>
<para>In the case that <parameter>value</parameter> 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.
</para>
<para>To deserialise the data returned by this function, in addition to the
serialised data, you must know the type of the <type>GVariant</type>, 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 <type>GVariants</type> must include this information either
implicitly (for instance &quot;the file always contains a
<constant>G_VARIANT_TYPE_VARIANT</constant> and it is always in little-endian order&quot;) or
explicitly (by storing the type and/or endianness in addition to the
serialised data).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-data-as-bytes</title><informalexample><programlisting>(define-values (%return) (variant:get-data-as-bytes self))
</programlisting></informalexample><para>Returns a pointer to the serialised form of a <type>GVariant</type> instance.
The semantics of this function are exactly the same as
<function>g_variant_get_data()</function>, except that the returned <type>GBytes</type> holds
a reference to the variant data.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-double</title><informalexample><programlisting>(define-values (%return) (variant:get-double self))
</programlisting></informalexample><para>Returns the double precision floating point value of <parameter>value</parameter>.
</para>
<para>It is an error to call this function with a <parameter>value</parameter> of any type
other than <constant>G_VARIANT_TYPE_DOUBLE</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a double <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-handle</title><informalexample><programlisting>(define-values (%return) (variant:get-handle self))
</programlisting></informalexample><para>Returns the 32-bit signed integer value of <parameter>value</parameter>.
</para>
<para>It is an error to call this function with a <parameter>value</parameter> of any type other
than <constant>G_VARIANT_TYPE_HANDLE</constant>.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a handle <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-int16</title><informalexample><programlisting>(define-values (%return) (variant:get-int16 self))
</programlisting></informalexample><para>Returns the 16-bit signed integer value of <parameter>value</parameter>.
</para>
<para>It is an error to call this function with a <parameter>value</parameter> of any type
other than <constant>G_VARIANT_TYPE_INT16</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>an int16 <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-int32</title><informalexample><programlisting>(define-values (%return) (variant:get-int32 self))
</programlisting></informalexample><para>Returns the 32-bit signed integer value of <parameter>value</parameter>.
</para>
<para>It is an error to call this function with a <parameter>value</parameter> of any type
other than <constant>G_VARIANT_TYPE_INT32</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>an int32 <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-int64</title><informalexample><programlisting>(define-values (%return) (variant:get-int64 self))
</programlisting></informalexample><para>Returns the 64-bit signed integer value of <parameter>value</parameter>.
</para>
<para>It is an error to call this function with a <parameter>value</parameter> of any type
other than <constant>G_VARIANT_TYPE_INT64</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>an int64 <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-maybe</title><informalexample><programlisting>(define-values (%return) (variant:get-maybe self))
</programlisting></informalexample><para>Given a maybe-typed <type>GVariant</type> instance, extract its value.  If the
value is Nothing, then this function returns <constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a maybe-typed value</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-normal-form</title><informalexample><programlisting>(define-values (%return) (variant:get-normal-form self))
</programlisting></informalexample><para>Gets a <type>GVariant</type> instance that has the same value as <parameter>value</parameter> and is
trusted to be in normal form.
</para>
<para>If <parameter>value</parameter> is already trusted to be in normal form then a new
reference to <parameter>value</parameter> is returned.
</para>
<para>If <parameter>value</parameter> 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.
</para>
<para>If <parameter>value</parameter> is found not to be in normal form then a new trusted
<type>GVariant</type> is created with the same value as <parameter>value</parameter>.
</para>
<para>It makes sense to call this function if you've received <type>GVariant</type>
data from untrusted sources and you want to ensure your serialised
output is definitely in normal form.
</para>
<para>If <parameter>value</parameter> is already in normal form, a new reference will be returned
(which will be floating if <parameter>value</parameter> is floating). If it is not in normal form,
the newly created <type>GVariant</type> will be returned with a single non-floating
reference. Typically, <function>g_variant_take_ref()</function> should be called on the return
value from this function to guarantee ownership of a single non-floating
reference to it.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-objv</title><informalexample><programlisting>(define-values (%return length) (variant:get-objv self))
</programlisting></informalexample><para>Gets the contents of an array of object paths <type>GVariant</type>.  This call
makes a shallow copy; the return result should be released with
<function>g_free()</function>, but the individual strings must not be modified.
</para>
<para>If <parameter>length</parameter> is non-<constant>NULL</constant> then the number of elements in the result
is stored there.  In any case, the resulting array will be
<constant>NULL</constant>-terminated.
</para>
<para>For an empty array, <parameter>length</parameter> will be set to 0 and a pointer to a
<constant>NULL</constant> pointer will be returned.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>an array of object paths <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of the result, or <constant>NULL</constant></para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-size</title><informalexample><programlisting>(define-values (%return) (variant:get-size self))
</programlisting></informalexample><para>Determines the number of bytes that would be required to store <parameter>value</parameter>
with <function>g_variant_store()</function>.
</para>
<para>If <parameter>value</parameter> has a fixed-sized type then this function always returned
that fixed size.
</para>
<para>In the case that <parameter>value</parameter> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-string</title><informalexample><programlisting>(define-values (%return length) (variant:get-string self))
</programlisting></informalexample><para>Returns the string value of a <type>GVariant</type> instance with a string
type.  This includes the types <constant>G_VARIANT_TYPE_STRING</constant>,
<constant>G_VARIANT_TYPE_OBJECT_PATH</constant> and <constant>G_VARIANT_TYPE_SIGNATURE</constant>.
</para>
<para>The string will always be UTF-8 encoded, will never be <constant>NULL</constant>, and will never
contain nul bytes.
</para>
<para>If <parameter>length</parameter> is non-<constant>NULL</constant> 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 <function>strlen()</function> will be
performed. If invalid, a default value will be returned — for
<constant>G_VARIANT_TYPE_OBJECT_PATH</constant>, this is <code>&quot;/&quot;</code>, and for other types it is the
empty string.
</para>
<para>It is an error to call this function with a <parameter>value</parameter> of any type
other than those three.
</para>
<para>The return value remains valid as long as <parameter>value</parameter> exists.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a string <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>a pointer to a <type>gsize</type>,
         to store the length</para><para>Passed as <code>length</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-strv</title><informalexample><programlisting>(define-values (%return length) (variant:get-strv self))
</programlisting></informalexample><para>Gets the contents of an array of strings <type>GVariant</type>.  This call
makes a shallow copy; the return result should be released with
<function>g_free()</function>, but the individual strings must not be modified.
</para>
<para>If <parameter>length</parameter> is non-<constant>NULL</constant> then the number of elements in the result
is stored there.  In any case, the resulting array will be
<constant>NULL</constant>-terminated.
</para>
<para>For an empty array, <parameter>length</parameter> will be set to 0 and a pointer to a
<constant>NULL</constant> pointer will be returned.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>an array of strings <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of the result, or <constant>NULL</constant></para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-type</title><informalexample><programlisting>(define-values (%return) (variant:get-type self))
</programlisting></informalexample><para>Determines the type of <parameter>value</parameter>.
</para>
<para>The return value is valid for the lifetime of <parameter>value</parameter> and must not
be freed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-type-string</title><informalexample><programlisting>(define-values (%return) (variant:get-type-string self))
</programlisting></informalexample><para>Returns the type string of <parameter>value</parameter>.  Unlike the result of calling
<function>g_variant_type_peek_string()</function>, this string is nul-terminated.  This
string belongs to <type>GVariant</type> and must not be freed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-uint16</title><informalexample><programlisting>(define-values (%return) (variant:get-uint16 self))
</programlisting></informalexample><para>Returns the 16-bit unsigned integer value of <parameter>value</parameter>.
</para>
<para>It is an error to call this function with a <parameter>value</parameter> of any type
other than <constant>G_VARIANT_TYPE_UINT16</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a uint16 <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-uint32</title><informalexample><programlisting>(define-values (%return) (variant:get-uint32 self))
</programlisting></informalexample><para>Returns the 32-bit unsigned integer value of <parameter>value</parameter>.
</para>
<para>It is an error to call this function with a <parameter>value</parameter> of any type
other than <constant>G_VARIANT_TYPE_UINT32</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a uint32 <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-uint64</title><informalexample><programlisting>(define-values (%return) (variant:get-uint64 self))
</programlisting></informalexample><para>Returns the 64-bit unsigned integer value of <parameter>value</parameter>.
</para>
<para>It is an error to call this function with a <parameter>value</parameter> of any type
other than <constant>G_VARIANT_TYPE_UINT64</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a uint64 <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-variant</title><informalexample><programlisting>(define-values (%return) (variant:get-variant self))
</programlisting></informalexample><para>Unboxes <parameter>value</parameter>.  The result is the <type>GVariant</type> instance that was
contained in <parameter>value</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a variant <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash</title><informalexample><programlisting>(define-values (%return) (variant:hash self))
</programlisting></informalexample><para>Generates a hash value for a <type>GVariant</type> instance.
</para>
<para>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.
</para>
<para>The type of <parameter>value</parameter> is <type>gconstpointer</type> only to allow use of this
function with <type>GHashTable</type>.  <parameter>value</parameter> must be a <type>GVariant</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a basic <type>GVariant</type> value as a <type>gconstpointer</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-container?</title><informalexample><programlisting>(define-values (%return) (variant:is-container? self))
</programlisting></informalexample><para>Checks if <parameter>value</parameter> is a container.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-floating?</title><informalexample><programlisting>(define-values (%return) (variant:is-floating? self))
</programlisting></informalexample><para>Checks whether <parameter>value</parameter> has a floating reference count.
</para>
<para>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 <function>g_variant_ref_sink()</function>
or <function>g_variant_take_ref()</function>.
</para>
<para>See <function>g_variant_ref_sink()</function> for more information about floating reference
counts.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-normal-form?</title><informalexample><programlisting>(define-values (%return) (variant:is-normal-form? self))
</programlisting></informalexample><para>Checks if <parameter>value</parameter> is in normal form.
</para>
<para>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 <type>GVariant</type>
using <function>g_variant_new_from_data()</function> and then use this function to
check.
</para>
<para>If <parameter>value</parameter> 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 <constant>TRUE</constant>.
</para>
<para>There may be implementation specific restrictions on deeply nested values.
GVariant is guaranteed to handle nesting up to at least 64 levels.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-of-type?</title><informalexample><programlisting>(define-values (%return) (variant:is-of-type? self type))
</programlisting></informalexample><para>Checks if a value has a type matching the provided type.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type> instance</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type></para><para>Passed as <code>type</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>lookup-value</title><informalexample><programlisting>(define-values (%return) (variant:lookup-value self key expected-type))
</programlisting></informalexample><para>Looks up a value in a dictionary <type>GVariant</type>.
</para>
<para>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).
</para>
<para>In the event that <parameter>dictionary</parameter> has the type a{sv}, the <parameter>expected_type</parameter>
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
<constant>NULL</constant> is returned. In the event that <parameter>dictionary</parameter> has a value type other
than v then <parameter>expected_type</parameter> must directly match the value type and it is
used to unpack the value directly or an error occurs.
</para>
<para>In either case, if <parameter>key</parameter> is not found in <parameter>dictionary</parameter>, <constant>NULL</constant> is returned.
</para>
<para>If the key is found and the value has the correct type, it is
returned.  If <parameter>expected_type</parameter> was specified then any non-<constant>NULL</constant> return
value will have this type.
</para>
<para>This function is currently implemented with a linear scan.  If you
plan to do many lookups then <type>GVariantDict</type> may be more efficient.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dictionary</para></td><td class="parameter_description"><para>a dictionary <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to look up in the dictionary</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>expected_type</para></td><td class="parameter_description"><para>a <type>GVariantType</type>, or <constant>NULL</constant></para><para>Passed as <code>expected-type</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>n-children</title><informalexample><programlisting>(define-values (%return) (variant:n-children self))
</programlisting></informalexample><para>Determines the number of children in a container <type>GVariant</type> instance.
This includes variants, maybes, arrays, tuples and dictionary
entries.  It is an error to call this function on any other type of
<type>GVariant</type>.
</para>
<para>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
</para>
<para>This function is O(1).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a container <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>print</title><informalexample><programlisting>(define-values (%return) (variant:print self type-annotate))
</programlisting></informalexample><para>Pretty-prints <parameter>value</parameter> in the format understood by <function>g_variant_parse()</function>.
</para>
<para>The format is described [here][gvariant-text].
</para>
<para>If <parameter>type_annotate</parameter> is <constant>TRUE</constant>, then type information is included in
the output.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>type_annotate</para></td><td class="parameter_description"><para><constant>TRUE</constant> if type information should be included in
                the output</para><para>Passed as <code>type-annotate</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref</title><informalexample><programlisting>(define-values (%return) (variant:ref self))
</programlisting></informalexample><para>Increases the reference count of <parameter>value</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref-sink</title><informalexample><programlisting>(define-values (%return) (variant:ref-sink self))
</programlisting></informalexample><para><type>GVariant</type> uses a floating reference count system.  All functions with
names starting with <code>g_variant_new_</code> return floating
references.
</para>
<para>Calling <function>g_variant_ref_sink()</function> on a <type>GVariant</type> with a floating reference
will convert the floating reference into a full reference.  Calling
<function>g_variant_ref_sink()</function> on a non-floating <type>GVariant</type> results in an
additional normal reference being added.
</para>
<para>In other words, if the <parameter>value</parameter> is floating, then this call &quot;assumes
ownership&quot; of the floating reference, converting it to a normal
reference.  If the <parameter>value</parameter> is not floating, then this call adds a
new normal reference increasing the reference count by one.
</para>
<para>All calls that result in a <type>GVariant</type> instance being inserted into a
container will call <function>g_variant_ref_sink()</function> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>store</title><informalexample><programlisting>(define-values () (variant:store self data))
</programlisting></informalexample><para>Stores the serialised form of <parameter>value</parameter> at <parameter>data</parameter>.  <parameter>data</parameter> should be
large enough.  See <function>g_variant_get_size()</function>.
</para>
<para>The stored data is in machine native byte order but may not be in
fully-normalised form if read from an untrusted source.  See
<function>g_variant_get_normal_form()</function> for a solution.
</para>
<para>As with <function>g_variant_get_data()</function>, 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.
</para>
<para>This function is approximately O(n) in the size of <parameter>data</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>the <type>GVariant</type> to store</para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>the location to store the serialised data at</para><para>Passed as <code>data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>take-ref</title><informalexample><programlisting>(define-values (%return) (variant:take-ref self))
</programlisting></informalexample><para>If <parameter>value</parameter> is floating, sink it.  Otherwise, do nothing.
</para>
<para>Typically you want to use <function>g_variant_ref_sink()</function> 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.
</para>
<para>The situation where this function is helpful is when creating an API
that allows the user to provide a callback function that returns a
<type>GVariant</type>.  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).
</para>
<para>At the same time, the style of the <type>GVariant</type> API makes it likely that
for newly-created <type>GVariant</type> instances, the user can be saved some
typing if they are allowed to return a <type>GVariant</type> with a floating
reference.
</para>
<para>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.
</para>
<para>This function has an odd interaction when combined with
<function>g_variant_ref_sink()</function> running at the same time in another thread on
the same <type>GVariant</type> instance.  If <function>g_variant_ref_sink()</function> runs first then
the result will be that the floating reference is converted to a hard
reference.  If <function>g_variant_take_ref()</function> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (variant:unref self))
</programlisting></informalexample><para>Decreases the reference count of <parameter>value</parameter>.  When its reference count
drops to 0, the memory used by the variant is freed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-variant</title><informalexample><programlisting>(define-values (%return) (variant:new-variant value))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para></para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-uint64</title><informalexample><programlisting>(define-values (%return) (variant:new-uint64 value))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para></para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-uint32</title><informalexample><programlisting>(define-values (%return) (variant:new-uint32 value))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para></para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-uint16</title><informalexample><programlisting>(define-values (%return) (variant:new-uint16 value))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para></para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-tuple</title><informalexample><programlisting>(define-values (%return) (variant:new-tuple children))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>children</para></td><td class="parameter_description"><para></para><para>Passed as <code>children</code></para></td></tr><tr><td class="parameter_name"><para>n_children</para></td><td class="parameter_description"><para></para><para>Inferred from <code>children</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-strv</title><informalexample><programlisting>(define-values (%return) (variant:new-strv strv))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>strv</para></td><td class="parameter_description"><para></para><para>Passed as <code>strv</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para></para><para>Inferred from <code>strv</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-string</title><informalexample><programlisting>(define-values (%return) (variant:new-string string))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para></para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-signature</title><informalexample><programlisting>(define-values (%return) (variant:new-signature signature))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>signature</para></td><td class="parameter_description"><para></para><para>Passed as <code>signature</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-objv</title><informalexample><programlisting>(define-values (%return) (variant:new-objv strv))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>strv</para></td><td class="parameter_description"><para></para><para>Passed as <code>strv</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para></para><para>Inferred from <code>strv</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-object-path</title><informalexample><programlisting>(define-values (%return) (variant:new-object-path object-path))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>object_path</para></td><td class="parameter_description"><para></para><para>Passed as <code>object-path</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-maybe</title><informalexample><programlisting>(define-values (%return) (variant:new-maybe child-type child))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>child_type</para></td><td class="parameter_description"><para></para><para>Passed as <code>child-type</code></para></td></tr><tr><td class="parameter_name"><para>child</para></td><td class="parameter_description"><para></para><para>Passed as <code>child</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-int64</title><informalexample><programlisting>(define-values (%return) (variant:new-int64 value))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para></para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-int32</title><informalexample><programlisting>(define-values (%return) (variant:new-int32 value))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para></para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-int16</title><informalexample><programlisting>(define-values (%return) (variant:new-int16 value))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para></para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-handle</title><informalexample><programlisting>(define-values (%return) (variant:new-handle value))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para></para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-from-data</title><informalexample><programlisting>(define-values
  (%return)
  (variant:new-from-data type data trusted notify user-data))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para></para><para>Passed as <code>type</code></para></td></tr><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para></para><para>Passed as <code>data</code></para></td></tr><tr><td class="parameter_name"><para>size</para></td><td class="parameter_description"><para></para><para>Inferred from <code>data</code></para></td></tr><tr><td class="parameter_name"><para>trusted</para></td><td class="parameter_description"><para></para><para>Passed as <code>trusted</code></para></td></tr><tr><td class="parameter_name"><para>notify</para></td><td class="parameter_description"><para></para><para>Passed as <code>notify</code></para></td></tr><tr><td class="parameter_name"><para>user_data</para></td><td class="parameter_description"><para></para><para>Passed as <code>user-data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-from-bytes</title><informalexample><programlisting>(define-values (%return) (variant:new-from-bytes type bytes trusted))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para></para><para>Passed as <code>type</code></para></td></tr><tr><td class="parameter_name"><para>bytes</para></td><td class="parameter_description"><para></para><para>Passed as <code>bytes</code></para></td></tr><tr><td class="parameter_name"><para>trusted</para></td><td class="parameter_description"><para></para><para>Passed as <code>trusted</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-fixed-array</title><informalexample><programlisting>(define-values
  (%return)
  (variant:new-fixed-array element-type elements n-elements element-size))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>element_type</para></td><td class="parameter_description"><para></para><para>Passed as <code>element-type</code></para></td></tr><tr><td class="parameter_name"><para>elements</para></td><td class="parameter_description"><para></para><para>Passed as <code>elements</code></para></td></tr><tr><td class="parameter_name"><para>n_elements</para></td><td class="parameter_description"><para></para><para>Passed as <code>n-elements</code></para></td></tr><tr><td class="parameter_name"><para>element_size</para></td><td class="parameter_description"><para></para><para>Passed as <code>element-size</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-double</title><informalexample><programlisting>(define-values (%return) (variant:new-double value))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para></para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-dict-entry</title><informalexample><programlisting>(define-values (%return) (variant:new-dict-entry key value))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para></para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para></para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-bytestring-array</title><informalexample><programlisting>(define-values (%return) (variant:new-bytestring-array strv))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>strv</para></td><td class="parameter_description"><para></para><para>Passed as <code>strv</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para></para><para>Inferred from <code>strv</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-bytestring</title><informalexample><programlisting>(define-values (%return) (variant:new-bytestring string))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para></para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-byte</title><informalexample><programlisting>(define-values (%return) (variant:new-byte value))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para></para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-boolean</title><informalexample><programlisting>(define-values (%return) (variant:new-boolean value))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para></para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:new-array</title><informalexample><programlisting>(define-values (%return) (variant:new-array child-type children))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>child_type</para></td><td class="parameter_description"><para></para><para>Passed as <code>child-type</code></para></td></tr><tr><td class="parameter_name"><para>children</para></td><td class="parameter_description"><para></para><para>Passed as <code>children</code></para></td></tr><tr><td class="parameter_name"><para>n_children</para></td><td class="parameter_description"><para></para><para>Inferred from <code>children</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:is-object-path?</title><informalexample><programlisting>(define-values (%return) (variant:is-object-path? string))
</programlisting></informalexample><para>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 <function>g_variant_new_object_path()</function>.
</para>
<para>A valid object path starts with <code>/</code> followed by zero or more
sequences of characters separated by <code>/</code> characters.  Each sequence
must contain only the characters <code>[A-Z][a-z][0-9]_</code>.  No sequence
(including the one following the final <code>/</code> character) may be empty.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a normal C nul-terminated string</para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:is-signature?</title><informalexample><programlisting>(define-values (%return) (variant:is-signature? string))
</programlisting></informalexample><para>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 <function>g_variant_new_signature()</function>.
</para>
<para>D-Bus type signatures consist of zero or more definite <type>GVariantType</type>
strings in sequence.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a normal C nul-terminated string</para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:parse</title><informalexample><programlisting>(define-values (%return) (variant:parse type text limit endptr))
</programlisting></informalexample><para>Parses a <type>GVariant</type> from a text representation.
</para>
<para>A single <type>GVariant</type> is parsed from the content of <parameter>text</parameter>.
</para>
<para>The format is described [here][gvariant-text].
</para>
<para>The memory at <parameter>limit</parameter> will never be accessed and the parser behaves as
if the character at <parameter>limit</parameter> is the nul terminator.  This has the
effect of bounding <parameter>text</parameter>.
</para>
<para>If <parameter>endptr</parameter> is non-<constant>NULL</constant> then <parameter>text</parameter> is permitted to contain data
following the value that this function parses and <parameter>endptr</parameter> will be
updated to point to the first character past the end of the text
parsed by this function.  If <parameter>endptr</parameter> is <constant>NULL</constant> and there is extra data
then an error is returned.
</para>
<para>If <parameter>type</parameter> is non-<constant>NULL</constant> 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).
</para>
<para>In the event that the parsing is successful, the resulting <type>GVariant</type>
is returned. It is never floating, and must be freed with
<function>g_variant_unref()</function>.
</para>
<para>In case of any error, <constant>NULL</constant> will be returned.  If <parameter>error</parameter> is non-<constant>NULL</constant>
then it will be set to reflect the error that occurred.
</para>
<para>Officially, the language understood by the parser is &quot;any string
produced by <function>g_variant_print()</function>&quot;.
</para>
<para>There may be implementation specific restrictions on deeply nested values,
which would result in a <constant>G_VARIANT_PARSE_ERROR_RECURSION</constant> error. <type>GVariant</type> is
guaranteed to handle nesting up to at least 64 levels.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type>, or <constant>NULL</constant></para><para>Passed as <code>type</code></para></td></tr><tr><td class="parameter_name"><para>text</para></td><td class="parameter_description"><para>a string containing a GVariant in text form</para><para>Passed as <code>text</code></para></td></tr><tr><td class="parameter_name"><para>limit</para></td><td class="parameter_description"><para>a pointer to the end of <parameter>text</parameter>, or <constant>NULL</constant></para><para>Passed as <code>limit</code></para></td></tr><tr><td class="parameter_name"><para>endptr</para></td><td class="parameter_description"><para>a location to store the end pointer, or <constant>NULL</constant></para><para>Passed as <code>endptr</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:parse-error-print-context</title><informalexample><programlisting>(define-values (%return) (variant:parse-error-print-context error source-str))
</programlisting></informalexample><para>Pretty-prints a message showing the context of a <type>GVariant</type> parse
error within the string for which parsing was attempted.
</para>
<para>The resulting string is suitable for output to the console or other
monospace media where newlines are treated in the usual way.
</para>
<para>The message will typically look something like one of the following:
</para>
<para><informalexample><programlisting>
unterminated string constant:
  (1, 2, 3, 'abc
            ^^^^
</programlisting></informalexample></para>

<para>or
</para>
<para><informalexample><programlisting>
unable to find a common type:
  [1, 2, 3, 'str']
   ^        ^^^^^
</programlisting></informalexample></para>

<para>The format of the message may change in a future version.
</para>
<para><parameter>error</parameter> must have come from a failed attempt to <function>g_variant_parse()</function> and
<parameter>source_str</parameter> must be exactly the same string that caused the error.
If <parameter>source_str</parameter> was not nul-terminated when you passed it to
<function>g_variant_parse()</function> then you must add nul termination before using this
function.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>error</para></td><td class="parameter_description"><para>a <type>GError</type> from the <type>GVariantParseError</type> domain</para><para>Passed as <code>error</code></para></td></tr><tr><td class="parameter_name"><para>source_str</para></td><td class="parameter_description"><para>the string that was given to the parser</para><para>Passed as <code>source-str</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant:parse-error-quark</title><informalexample><programlisting>(define-values (%return) (variant:parse-error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>variant:parser-get-error-quark</title><informalexample><programlisting>(define-values (%return) (variant:parser-get-error-quark))
</programlisting></informalexample><para>Same as <function>g_variant_error_quark()</function>.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GVariantBuilder&gt;</refname></refnamediv><refsect1><title>Description</title><para>A utility type for constructing container-type <type>GVariant</type> instances.
</para>
<para>This is an opaque structure and may only be accessed using the
following functions.
</para>
<para><type>GVariantBuilder</type> is not threadsafe in any way.  Do not attempt to
access it from more than one thread.</para></refsect1><refsect1><title>Functions</title><refsect2><title>add-value</title><informalexample><programlisting>(define-values () (variant-builder:add-value self value))
</programlisting></informalexample><para>Adds <parameter>value</parameter> to <parameter>builder</parameter>.
</para>
<para>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.
</para>
<para>If <parameter>value</parameter> is a floating reference (see <function>g_variant_ref_sink()</function>),
the <parameter>builder</parameter> instance takes ownership of <parameter>value</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>builder</para></td><td class="parameter_description"><para>a <type>GVariantBuilder</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>a <type>GVariant</type></para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>close</title><informalexample><programlisting>(define-values () (variant-builder:close self))
</programlisting></informalexample><para>Closes the subcontainer inside the given <parameter>builder</parameter> that was opened by
the most recent call to <function>g_variant_builder_open()</function>.
</para>
<para>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).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>builder</para></td><td class="parameter_description"><para>a <type>GVariantBuilder</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>end</title><informalexample><programlisting>(define-values (%return) (variant-builder:end self))
</programlisting></informalexample><para>Ends the builder process and returns the constructed value.
</para>
<para>It is not permissible to use <parameter>builder</parameter> in any way after this call
except for reference counting operations (in the case of a
heap-allocated <type>GVariantBuilder</type>) or by reinitialising it with
<function>g_variant_builder_init()</function> (in the case of stack-allocated). This
means that for the stack-allocated builders there is no need to
call <function>g_variant_builder_clear()</function> after the call to
<function>g_variant_builder_end()</function>.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>builder</para></td><td class="parameter_description"><para>a <type>GVariantBuilder</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>open</title><informalexample><programlisting>(define-values () (variant-builder:open self type))
</programlisting></informalexample><para>Opens a subcontainer inside the given <parameter>builder</parameter>.  When done adding
items to the subcontainer, <function>g_variant_builder_close()</function> must be called. <parameter>type</parameter>
is the type of the container: so to build a tuple of several values, <parameter>type</parameter>
must include the tuple itself.
</para>
<para>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).
</para>
<para>Example of building a nested variant:
<informalexample><programlisting>
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 (&amp;builder, G_VARIANT_TYPE (&quot;(ua{sv})&quot;));
g_variant_builder_add (&amp;builder, &quot;u&quot;, some_number);
g_variant_builder_open (&amp;builder, G_VARIANT_TYPE (&quot;a{sv}&quot;));

g_hash_table_iter_init (&amp;iter, some_dict);
while (g_hash_table_iter_next (&amp;iter, (gpointer *) &amp;key, (gpointer *) &amp;value))
  {
    g_variant_builder_open (&amp;builder, G_VARIANT_TYPE (&quot;{sv}&quot;));
    g_variant_builder_add (&amp;builder, &quot;s&quot;, key);
    g_variant_builder_add (&amp;builder, &quot;v&quot;, value);
    g_variant_builder_close (&amp;builder);
  }

g_variant_builder_close (&amp;builder);

output = g_variant_builder_end (&amp;builder);
</programlisting></informalexample></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>builder</para></td><td class="parameter_description"><para>a <type>GVariantBuilder</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>the <type>GVariantType</type> of the container</para><para>Passed as <code>type</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref</title><informalexample><programlisting>(define-values (%return) (variant-builder:ref self))
</programlisting></informalexample><para>Increases the reference count on <parameter>builder</parameter>.
</para>
<para>Don't call this on stack-allocated <type>GVariantBuilder</type> instances or bad
things will happen.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>builder</para></td><td class="parameter_description"><para>a <type>GVariantBuilder</type> allocated by <function>g_variant_builder_new()</function></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (variant-builder:unref self))
</programlisting></informalexample><para>Decreases the reference count on <parameter>builder</parameter>.
</para>
<para>In the event that there are no more references, releases all memory
associated with the <type>GVariantBuilder</type>.
</para>
<para>Don't call this on stack-allocated <type>GVariantBuilder</type> instances or bad
things will happen.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>builder</para></td><td class="parameter_description"><para>a <type>GVariantBuilder</type> allocated by <function>g_variant_builder_new()</function></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-builder:new</title><informalexample><programlisting>(define-values (%return) (variant-builder:new type))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para></para><para>Passed as <code>type</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibVariantClass&gt;</refname></refnamediv><refsect1><title>Description</title><para>The range of possible top-level types of <type>GVariant</type> instances.</para></refsect1><refsect1><title>Members</title><refsect2><title>boolean</title><remark>alias <code>G_VARIANT_CLASS_BOOLEAN</code></remark><para>The <type>GVariant</type> is a boolean.</para></refsect2><refsect2><title>byte</title><remark>alias <code>G_VARIANT_CLASS_BYTE</code></remark><para>The <type>GVariant</type> is a byte.</para></refsect2><refsect2><title>int16</title><remark>alias <code>G_VARIANT_CLASS_INT16</code></remark><para>The <type>GVariant</type> is a signed 16 bit integer.</para></refsect2><refsect2><title>uint16</title><remark>alias <code>G_VARIANT_CLASS_UINT16</code></remark><para>The <type>GVariant</type> is an unsigned 16 bit integer.</para></refsect2><refsect2><title>int32</title><remark>alias <code>G_VARIANT_CLASS_INT32</code></remark><para>The <type>GVariant</type> is a signed 32 bit integer.</para></refsect2><refsect2><title>uint32</title><remark>alias <code>G_VARIANT_CLASS_UINT32</code></remark><para>The <type>GVariant</type> is an unsigned 32 bit integer.</para></refsect2><refsect2><title>int64</title><remark>alias <code>G_VARIANT_CLASS_INT64</code></remark><para>The <type>GVariant</type> is a signed 64 bit integer.</para></refsect2><refsect2><title>uint64</title><remark>alias <code>G_VARIANT_CLASS_UINT64</code></remark><para>The <type>GVariant</type> is an unsigned 64 bit integer.</para></refsect2><refsect2><title>handle</title><remark>alias <code>G_VARIANT_CLASS_HANDLE</code></remark><para>The <type>GVariant</type> is a file handle index.</para></refsect2><refsect2><title>double</title><remark>alias <code>G_VARIANT_CLASS_DOUBLE</code></remark><para>The <type>GVariant</type> is a double precision floating
                         point value.</para></refsect2><refsect2><title>string</title><remark>alias <code>G_VARIANT_CLASS_STRING</code></remark><para>The <type>GVariant</type> is a normal string.</para></refsect2><refsect2><title>object-path</title><remark>alias <code>G_VARIANT_CLASS_OBJECT_PATH</code></remark><para>The <type>GVariant</type> is a D-Bus object path
                              string.</para></refsect2><refsect2><title>signature</title><remark>alias <code>G_VARIANT_CLASS_SIGNATURE</code></remark><para>The <type>GVariant</type> is a D-Bus signature string.</para></refsect2><refsect2><title>variant</title><remark>alias <code>G_VARIANT_CLASS_VARIANT</code></remark><para>The <type>GVariant</type> is a variant.</para></refsect2><refsect2><title>maybe</title><remark>alias <code>G_VARIANT_CLASS_MAYBE</code></remark><para>The <type>GVariant</type> is a maybe-typed value.</para></refsect2><refsect2><title>array</title><remark>alias <code>G_VARIANT_CLASS_ARRAY</code></remark><para>The <type>GVariant</type> is an array.</para></refsect2><refsect2><title>tuple</title><remark>alias <code>G_VARIANT_CLASS_TUPLE</code></remark><para>The <type>GVariant</type> is a tuple.</para></refsect2><refsect2><title>dict-entry</title><remark>alias <code>G_VARIANT_CLASS_DICT_ENTRY</code></remark><para>The <type>GVariant</type> is a dictionary entry.</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GVariantDict&gt;</refname></refnamediv><refsect1><title>Description</title><para><type>GVariantDict</type> is a mutable interface to <type>GVariant</type> dictionaries.
</para>
<para>It can be used for doing a sequence of dictionary lookups in an
efficient way on an existing <type>GVariant</type> 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.
</para>
<para><type>GVariantDict</type> can only be used with <constant>G_VARIANT_TYPE_VARDICT</constant>
dictionaries.
</para>
<para>It is possible to use <type>GVariantDict</type> allocated on the stack or on the
heap.  When using a stack-allocated <type>GVariantDict</type>, you begin with a
call to <function>g_variant_dict_init()</function> and free the resources with a call to
<function>g_variant_dict_clear()</function>.
</para>
<para>Heap-allocated <type>GVariantDict</type> follows normal refcounting rules: you
allocate it with <function>g_variant_dict_new()</function> and use <function>g_variant_dict_ref()</function>
and <function>g_variant_dict_unref()</function>.
</para>
<para><function>g_variant_dict_end()</function> is used to convert the <type>GVariantDict</type> back into a
dictionary-type <type>GVariant</type>.  When used with stack-allocated instances,
this also implicitly frees all associated memory, but for
heap-allocated instances, you must still call <function>g_variant_dict_unref()</function>
afterwards.
</para>
<para>You will typically want to use a heap-allocated <type>GVariantDict</type> when
you expose it as part of an API.  For most other uses, the
stack-allocated form will be more convenient.
</para>
<para>Consider the following two examples that do the same thing in each
style: take an existing dictionary and look up the &quot;count&quot; 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
<type>GVariant</type>.
</para>
<refsect2><title>Using a stack-allocated GVariantDict</title>
<para><informalexample><programlisting>
  GVariant *
  add_to_count (GVariant  *orig,
                GError   **error)
  {
    GVariantDict dict;
    guint32 count;

    g_variant_dict_init (&amp;dict, orig);
    if (!g_variant_dict_lookup (&amp;dict, &quot;count&quot;, &quot;u&quot;, &amp;count))
      {
        g_set_error (...);
        g_variant_dict_clear (&amp;dict);
        return NULL;
      }

    g_variant_dict_insert (&amp;dict, &quot;count&quot;, &quot;u&quot;, count + 1);

    return g_variant_dict_end (&amp;dict);
  }
</programlisting></informalexample></para>

</refsect2><refsect2><title>Using heap-allocated GVariantDict</title>
<para><informalexample><programlisting>
  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, &quot;count&quot;, &quot;u&quot;, &amp;count))
      {
        g_variant_dict_insert (dict, &quot;count&quot;, &quot;u&quot;, count + 1);
        result = g_variant_dict_end (dict);
      }
    else
      {
        g_set_error (...);
        result = NULL;
      }

    g_variant_dict_unref (dict);

    return result;
  }
</programlisting></informalexample></para></refsect2></refsect1><refsect1><title>Functions</title><refsect2><title>clear</title><informalexample><programlisting>(define-values () (variant-dict:clear self))
</programlisting></informalexample><para>Releases all memory associated with a <type>GVariantDict</type> without freeing
the <type>GVariantDict</type> structure itself.
</para>
<para>It typically only makes sense to do this on a stack-allocated
<type>GVariantDict</type> if you want to abort building the value part-way
through.  This function need not be called if you call
<function>g_variant_dict_end()</function> and it also doesn't need to be called on dicts
allocated with g_variant_dict_new (see <function>g_variant_dict_unref()</function> for
that).
</para>
<para>It is valid to call this function on either an initialised
<type>GVariantDict</type> or one that was previously cleared by an earlier call
to <function>g_variant_dict_clear()</function> but it is not valid to call this function
on uninitialised memory.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dict</para></td><td class="parameter_description"><para>a <type>GVariantDict</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>contains?</title><informalexample><programlisting>(define-values (%return) (variant-dict:contains? self key))
</programlisting></informalexample><para>Checks if <parameter>key</parameter> exists in <parameter>dict</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dict</para></td><td class="parameter_description"><para>a <type>GVariantDict</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to look up in the dictionary</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>end</title><informalexample><programlisting>(define-values (%return) (variant-dict:end self))
</programlisting></informalexample><para>Returns the current value of <parameter>dict</parameter> as a <type>GVariant</type> of type
<constant>G_VARIANT_TYPE_VARDICT</constant>, clearing it in the process.
</para>
<para>It is not permissible to use <parameter>dict</parameter> in any way after this call except
for reference counting operations (in the case of a heap-allocated
<type>GVariantDict</type>) or by reinitialising it with <function>g_variant_dict_init()</function> (in
the case of stack-allocated).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dict</para></td><td class="parameter_description"><para>a <type>GVariantDict</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>insert-value</title><informalexample><programlisting>(define-values () (variant-dict:insert-value self key value))
</programlisting></informalexample><para>Inserts (or replaces) a key in a <type>GVariantDict</type>.
</para>
<para><parameter>value</parameter> is consumed if it is floating.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dict</para></td><td class="parameter_description"><para>a <type>GVariantDict</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to insert a value for</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>the value to insert</para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>lookup-value</title><informalexample><programlisting>(define-values (%return) (variant-dict:lookup-value self key expected-type))
</programlisting></informalexample><para>Looks up a value in a <type>GVariantDict</type>.
</para>
<para>If <parameter>key</parameter> is not found in <parameter>dictionary</parameter>, <constant>NULL</constant> is returned.
</para>
<para>The <parameter>expected_type</parameter> string specifies what type of value is expected.
If the value associated with <parameter>key</parameter> has a different type then <constant>NULL</constant> is
returned.
</para>
<para>If the key is found and the value has the correct type, it is
returned.  If <parameter>expected_type</parameter> was specified then any non-<constant>NULL</constant> return
value will have this type.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dict</para></td><td class="parameter_description"><para>a <type>GVariantDict</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to look up in the dictionary</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>expected_type</para></td><td class="parameter_description"><para>a <type>GVariantType</type>, or <constant>NULL</constant></para><para>Passed as <code>expected-type</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref</title><informalexample><programlisting>(define-values (%return) (variant-dict:ref self))
</programlisting></informalexample><para>Increases the reference count on <parameter>dict</parameter>.
</para>
<para>Don't call this on stack-allocated <type>GVariantDict</type> instances or bad
things will happen.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dict</para></td><td class="parameter_description"><para>a heap-allocated <type>GVariantDict</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>remove?</title><informalexample><programlisting>(define-values (%return) (variant-dict:remove? self key))
</programlisting></informalexample><para>Removes a key and its associated value from a <type>GVariantDict</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dict</para></td><td class="parameter_description"><para>a <type>GVariantDict</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to remove</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unref</title><informalexample><programlisting>(define-values () (variant-dict:unref self))
</programlisting></informalexample><para>Decreases the reference count on <parameter>dict</parameter>.
</para>
<para>In the event that there are no more references, releases all memory
associated with the <type>GVariantDict</type>.
</para>
<para>Don't call this on stack-allocated <type>GVariantDict</type> instances or bad
things will happen.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dict</para></td><td class="parameter_description"><para>a heap-allocated <type>GVariantDict</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-dict:new</title><informalexample><programlisting>(define-values (%return) (variant-dict:new from-asv))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>from_asv</para></td><td class="parameter_description"><para></para><para>Passed as <code>from-asv</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;%GLibVariantParseError&gt;</refname></refnamediv><refsect1><title>Description</title><para>Error codes returned by parsing text-format GVariants.</para></refsect1><refsect1><title>Members</title><refsect2><title>failed</title><remark>alias <code>G_VARIANT_PARSE_ERROR_FAILED</code></remark><para>generic error (unused)</para></refsect2><refsect2><title>basic-type-expected</title><remark>alias <code>G_VARIANT_PARSE_ERROR_BASIC_TYPE_EXPECTED</code></remark><para>a non-basic <type>GVariantType</type> was given where a basic type was expected</para></refsect2><refsect2><title>cannot-infer-type</title><remark>alias <code>G_VARIANT_PARSE_ERROR_CANNOT_INFER_TYPE</code></remark><para>cannot infer the <type>GVariantType</type></para></refsect2><refsect2><title>definite-type-expected</title><remark>alias <code>G_VARIANT_PARSE_ERROR_DEFINITE_TYPE_EXPECTED</code></remark><para>an indefinite <type>GVariantType</type> was given where a definite type was expected</para></refsect2><refsect2><title>input-not-at-end</title><remark>alias <code>G_VARIANT_PARSE_ERROR_INPUT_NOT_AT_END</code></remark><para>extra data after parsing finished</para></refsect2><refsect2><title>invalid-character</title><remark>alias <code>G_VARIANT_PARSE_ERROR_INVALID_CHARACTER</code></remark><para>invalid character in number or unicode escape</para></refsect2><refsect2><title>invalid-format-string</title><remark>alias <code>G_VARIANT_PARSE_ERROR_INVALID_FORMAT_STRING</code></remark><para>not a valid <type>GVariant</type> format string</para></refsect2><refsect2><title>invalid-object-path</title><remark>alias <code>G_VARIANT_PARSE_ERROR_INVALID_OBJECT_PATH</code></remark><para>not a valid object path</para></refsect2><refsect2><title>invalid-signature</title><remark>alias <code>G_VARIANT_PARSE_ERROR_INVALID_SIGNATURE</code></remark><para>not a valid type signature</para></refsect2><refsect2><title>invalid-type-string</title><remark>alias <code>G_VARIANT_PARSE_ERROR_INVALID_TYPE_STRING</code></remark><para>not a valid <type>GVariant</type> type string</para></refsect2><refsect2><title>no-common-type</title><remark>alias <code>G_VARIANT_PARSE_ERROR_NO_COMMON_TYPE</code></remark><para>could not find a common type for array entries</para></refsect2><refsect2><title>number-out-of-range</title><remark>alias <code>G_VARIANT_PARSE_ERROR_NUMBER_OUT_OF_RANGE</code></remark><para>the numerical value is out of range of the given type</para></refsect2><refsect2><title>number-too-big</title><remark>alias <code>G_VARIANT_PARSE_ERROR_NUMBER_TOO_BIG</code></remark><para>the numerical value is out of range for any type</para></refsect2><refsect2><title>type-error</title><remark>alias <code>G_VARIANT_PARSE_ERROR_TYPE_ERROR</code></remark><para>cannot parse as variant of the specified type</para></refsect2><refsect2><title>unexpected-token</title><remark>alias <code>G_VARIANT_PARSE_ERROR_UNEXPECTED_TOKEN</code></remark><para>an unexpected token was encountered</para></refsect2><refsect2><title>unknown-keyword</title><remark>alias <code>G_VARIANT_PARSE_ERROR_UNKNOWN_KEYWORD</code></remark><para>an unknown keyword was encountered</para></refsect2><refsect2><title>unterminated-string-constant</title><remark>alias <code>G_VARIANT_PARSE_ERROR_UNTERMINATED_STRING_CONSTANT</code></remark><para>unterminated string constant</para></refsect2><refsect2><title>value-expected</title><remark>alias <code>G_VARIANT_PARSE_ERROR_VALUE_EXPECTED</code></remark><para>no value given</para></refsect2><refsect2><title>recursion</title><remark>alias <code>G_VARIANT_PARSE_ERROR_RECURSION</code></remark><para>variant was too deeply nested; <type>GVariant</type> is only guaranteed to handle nesting up to 64 levels (Since: 2.64)</para></refsect2></refsect1></refentry><refentry><refnamediv><refname>&lt;GVariantType&gt;</refname></refnamediv><refsect1><title>Description</title><para>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.
</para>
<para>The first major change with respect to the D-Bus type system is the
introduction of maybe (or &quot;nullable&quot;) types.  Any type in GVariant can be
converted to a maybe type, in which case, &quot;nothing&quot; (or &quot;null&quot;) becomes a
valid value.  Maybe types have been added by introducing the
character &quot;m&quot; to type strings.
</para>
<para>The second major change is that the GVariant type system supports the
concept of &quot;indefinite types&quot; -- types that are less specific than
the normal types found in D-Bus.  For example, it is possible to speak
of &quot;an array of any type&quot; in GVariant, where the D-Bus type system
would require you to speak of &quot;an array of integers&quot; or &quot;an array of
strings&quot;.  Indefinite types have been added by introducing the
characters &quot;*&quot;, &quot;?&quot; and &quot;r&quot; to type strings.
</para>
<para>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.
</para>
<para>Just as in D-Bus, GVariant types are described with strings (&quot;type
strings&quot;).  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, &quot;signatures&quot;
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.
</para>
<para>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,
<function>g_variant_get_type()</function> will never return an indefinite type, but
calling <function>g_variant_is_of_type()</function> with an indefinite type may return
<constant>TRUE</constant>.  For example, you cannot have a value that represents &quot;an
array of no particular type&quot;, but you can have an &quot;array of integers&quot;
which certainly matches the type of &quot;an array of no particular type&quot;,
since &quot;array of integers&quot; is a subtype of &quot;array of no particular
type&quot;.
</para>
<para>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 <type>GtkBin</type> can exist (since <type>GtkBin</type> is an abstract class),
but a <type>GtkWindow</type> can certainly be instantiated, and you would say
that the <type>GtkWindow</type> is a <type>GtkBin</type> (since <type>GtkWindow</type> is a subclass of
<type>GtkBin</type>).
</para>
<refsect2><title>GVariant Type Strings</title>
<para>A GVariant type string can be any of the following:
</para>
<para>- any basic type string (listed below)
</para>
<para>- &quot;v&quot;, &quot;r&quot; or &quot;*&quot;
</para>
<para>- one of the characters 'a' or 'm', followed by another type string
</para>
<para>- the character '(', followed by a concatenation of zero or more other
  type strings, followed by the character ')'
</para>
<para>- the character '{', followed by a basic type string (see below),
  followed by another type string, followed by the character '}'
</para>
<para>A basic type string describes a basic type (as per
<function>g_variant_type_is_basic()</function>) and is always a single character in length.
The valid basic type strings are &quot;b&quot;, &quot;y&quot;, &quot;n&quot;, &quot;q&quot;, &quot;i&quot;, &quot;u&quot;, &quot;x&quot;, &quot;t&quot;,
&quot;h&quot;, &quot;d&quot;, &quot;s&quot;, &quot;o&quot;, &quot;g&quot; and &quot;?&quot;.
</para>
<para>The above definition is recursive to arbitrary depth. &quot;aaaaai&quot; and
&quot;(ui(nq((y)))s)&quot; are both valid type strings, as is
&quot;a(aa(ui)(qna{ya(yd)}))&quot;. In order to not hit memory limits, <type>GVariant</type>
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 <type>GDBusMessage</type> to
be nested in a top-level tuple.
</para>
<para>The meaning of each of the characters is as follows:
- <code>b</code>: the type string of <constant>G_VARIANT_TYPE_BOOLEAN</constant>; a boolean value.
- <code>y</code>: the type string of <constant>G_VARIANT_TYPE_BYTE</constant>; a byte.
- <code>n</code>: the type string of <constant>G_VARIANT_TYPE_INT16</constant>; a signed 16 bit integer.
- <code>q</code>: the type string of <constant>G_VARIANT_TYPE_UINT16</constant>; an unsigned 16 bit integer.
- <code>i</code>: the type string of <constant>G_VARIANT_TYPE_INT32</constant>; a signed 32 bit integer.
- <code>u</code>: the type string of <constant>G_VARIANT_TYPE_UINT32</constant>; an unsigned 32 bit integer.
- <code>x</code>: the type string of <constant>G_VARIANT_TYPE_INT64</constant>; a signed 64 bit integer.
- <code>t</code>: the type string of <constant>G_VARIANT_TYPE_UINT64</constant>; an unsigned 64 bit integer.
- <code>h</code>: the type string of <constant>G_VARIANT_TYPE_HANDLE</constant>; 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.
- <code>d</code>: the type string of <constant>G_VARIANT_TYPE_DOUBLE</constant>; a double precision
  floating point value.
- <code>s</code>: the type string of <constant>G_VARIANT_TYPE_STRING</constant>; a string.
- <code>o</code>: the type string of <constant>G_VARIANT_TYPE_OBJECT_PATH</constant>; a string in the form
  of a D-Bus object path.
- <code>g</code>: the type string of <constant>G_VARIANT_TYPE_SIGNATURE</constant>; a string in the form of
  a D-Bus type signature.
- <code>?</code>: the type string of <constant>G_VARIANT_TYPE_BASIC</constant>; an indefinite type that
  is a supertype of any of the basic types.
- <code>v</code>: the type string of <constant>G_VARIANT_TYPE_VARIANT</constant>; a container type that
  contain any other type of value.
- <code>a</code>: used as a prefix on another type string to mean an array of that
  type; the type string &quot;ai&quot;, for example, is the type of an array of
  signed 32-bit integers.
- <code>m</code>: used as a prefix on another type string to mean a &quot;maybe&quot;, or
  &quot;nullable&quot;, version of that type; the type string &quot;ms&quot;, for example,
  is the type of a value that maybe contains a string, or maybe contains
  nothing.
- <code>()</code>: used to enclose zero or more other concatenated type strings to
  create a tuple type; the type string &quot;(is)&quot;, for example, is the type of
  a pair of an integer and a string.
- <code>r</code>: the type string of <constant>G_VARIANT_TYPE_TUPLE</constant>; an indefinite type that is
  a supertype of any tuple type, regardless of the number of items.
- <code>{}</code>: 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 &quot;a{sd}&quot;, for example, is
  the type of a dictionary that maps strings to double precision floating
  point values.
</para>
  <para>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.
- <code>*</code>: the type string of <constant>G_VARIANT_TYPE_ANY</constant>; 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 &quot;any number of items&quot;.
</para>
<para>Any type string of a container that contains an indefinite type is,
itself, an indefinite type. For example, the type string &quot;a*&quot;
(corresponding to <constant>G_VARIANT_TYPE_ARRAY</constant>) is an indefinite type
that is a supertype of every array type. &quot;(*s)&quot; is a supertype
of all tuples that contain exactly two items where the second
item is a string.
</para>
<para>&quot;a{?*}&quot; 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 <constant>G_VARIANT_TYPE_DICTIONARY</constant>. Note
that, due to the restriction that the key of a dictionary entry must
be a basic type, &quot;{**}&quot; is not a valid type string.</para></refsect2></refsect1><refsect1><title>Functions</title><refsect2><title>copy</title><informalexample><programlisting>(define-values (%return) (variant-type:copy self))
</programlisting></informalexample><para>Makes a copy of a <type>GVariantType</type>.  It is appropriate to call
<function>g_variant_type_free()</function> on the return value.  <parameter>type</parameter> may not be <constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>dup-string</title><informalexample><programlisting>(define-values (%return) (variant-type:dup-string self))
</programlisting></informalexample><para>Returns a newly-allocated copy of the type string corresponding to
<parameter>type</parameter>.  The returned string is nul-terminated.  It is appropriate to
call <function>g_free()</function> on the return value.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>element</title><informalexample><programlisting>(define-values (%return) (variant-type:element self))
</programlisting></informalexample><para>Determines the element type of an array or maybe type.
</para>
<para>This function may only be used with array or maybe types.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>an array or maybe <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>equal?</title><informalexample><programlisting>(define-values (%return) (variant-type:equal? self type2))
</programlisting></informalexample><para>Compares <parameter>type1</parameter> and <parameter>type2</parameter> for equality.
</para>
<para>Only returns <constant>TRUE</constant> if the types are exactly equal.  Even if one type
is an indefinite type and the other is a subtype of it, <constant>FALSE</constant> will
be returned if they are not exactly equal.  If you want to check for
subtypes, use <function>g_variant_type_is_subtype_of()</function>.
</para>
<para>The argument types of <parameter>type1</parameter> and <parameter>type2</parameter> are only <type>gconstpointer</type> to
allow use with <type>GHashTable</type> without function pointer casting.  For
both arguments, a valid <type>GVariantType</type> must be provided.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type1</para></td><td class="parameter_description"><para>a <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>type2</para></td><td class="parameter_description"><para>a <type>GVariantType</type></para><para>Passed as <code>type2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>first</title><informalexample><programlisting>(define-values (%return) (variant-type:first self))
</programlisting></informalexample><para>Determines the first item type of a tuple or dictionary entry
type.
</para>
<para>This function may only be used with tuple or dictionary entry types,
but must not be used with the generic tuple type
<constant>G_VARIANT_TYPE_TUPLE</constant>.
</para>
<para>In the case of a dictionary entry type, this returns the type of
the key.
</para>
<para><constant>NULL</constant> is returned in case of <parameter>type</parameter> being <constant>G_VARIANT_TYPE_UNIT</constant>.
</para>
<para>This call, together with <function>g_variant_type_next()</function> provides an iterator
interface over tuple and dictionary entry types.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a tuple or dictionary entry <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>free</title><informalexample><programlisting>(define-values () (variant-type:free self))
</programlisting></informalexample><para>Frees a <type>GVariantType</type> that was allocated with
<function>g_variant_type_copy()</function>, <function>g_variant_type_new()</function> or one of the container
type constructor functions.
</para>
<para>In the case that <parameter>type</parameter> is <constant>NULL</constant>, this function does nothing.
</para>
<para>Since 2.24</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type>, or <constant>NULL</constant></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-string-length</title><informalexample><programlisting>(define-values (%return) (variant-type:get-string-length self))
</programlisting></informalexample><para>Returns the length of the type string corresponding to the given
<parameter>type</parameter>.  This function must be used to determine the valid extent of
the memory region returned by <function>g_variant_type_peek_string()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash</title><informalexample><programlisting>(define-values (%return) (variant-type:hash self))
</programlisting></informalexample><para>Hashes <parameter>type</parameter>.
</para>
<para>The argument type of <parameter>type</parameter> is only <type>gconstpointer</type> to allow use with
<type>GHashTable</type> without function pointer casting.  A valid
<type>GVariantType</type> must be provided.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-array?</title><informalexample><programlisting>(define-values (%return) (variant-type:is-array? self))
</programlisting></informalexample><para>Determines if the given <parameter>type</parameter> is an array type.  This is true if the
type string for <parameter>type</parameter> starts with an 'a'.
</para>
<para>This function returns <constant>TRUE</constant> for any indefinite type for which every
definite subtype is an array type -- <constant>G_VARIANT_TYPE_ARRAY</constant>, for
example.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-basic?</title><informalexample><programlisting>(define-values (%return) (variant-type:is-basic? self))
</programlisting></informalexample><para>Determines if the given <parameter>type</parameter> is a basic type.
</para>
<para>Basic types are booleans, bytes, integers, doubles, strings, object
paths and signatures.
</para>
<para>Only a basic type may be used as the key of a dictionary entry.
</para>
<para>This function returns <constant>FALSE</constant> for all indefinite types except
<constant>G_VARIANT_TYPE_BASIC</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-container?</title><informalexample><programlisting>(define-values (%return) (variant-type:is-container? self))
</programlisting></informalexample><para>Determines if the given <parameter>type</parameter> is a container type.
</para>
<para>Container types are any array, maybe, tuple, or dictionary
entry types plus the variant type.
</para>
<para>This function returns <constant>TRUE</constant> for any indefinite type for which every
definite subtype is a container -- <constant>G_VARIANT_TYPE_ARRAY</constant>, for
example.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-definite?</title><informalexample><programlisting>(define-values (%return) (variant-type:is-definite? self))
</programlisting></informalexample><para>Determines if the given <parameter>type</parameter> is definite (ie: not indefinite).
</para>
<para>A type is definite if its type string does not contain any indefinite
type characters ('*', '?', or 'r').
</para>
<para>A <type>GVariant</type> instance may not have an indefinite type, so calling
this function on the result of <function>g_variant_get_type()</function> will always
result in <constant>TRUE</constant> being returned.  Calling this function on an
indefinite type like <constant>G_VARIANT_TYPE_ARRAY</constant>, however, will result in
<constant>FALSE</constant> being returned.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-dict-entry?</title><informalexample><programlisting>(define-values (%return) (variant-type:is-dict-entry? self))
</programlisting></informalexample><para>Determines if the given <parameter>type</parameter> is a dictionary entry type.  This is
true if the type string for <parameter>type</parameter> starts with a '{'.
</para>
<para>This function returns <constant>TRUE</constant> for any indefinite type for which every
definite subtype is a dictionary entry type --
<constant>G_VARIANT_TYPE_DICT_ENTRY</constant>, for example.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-maybe?</title><informalexample><programlisting>(define-values (%return) (variant-type:is-maybe? self))
</programlisting></informalexample><para>Determines if the given <parameter>type</parameter> is a maybe type.  This is true if the
type string for <parameter>type</parameter> starts with an 'm'.
</para>
<para>This function returns <constant>TRUE</constant> for any indefinite type for which every
definite subtype is a maybe type -- <constant>G_VARIANT_TYPE_MAYBE</constant>, for
example.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-subtype-of?</title><informalexample><programlisting>(define-values (%return) (variant-type:is-subtype-of? self supertype))
</programlisting></informalexample><para>Checks if <parameter>type</parameter> is a subtype of <parameter>supertype</parameter>.
</para>
<para>This function returns <constant>TRUE</constant> if <parameter>type</parameter> is a subtype of <parameter>supertype</parameter>.  All
types are considered to be subtypes of themselves.  Aside from that,
only indefinite types can have subtypes.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr><tr><td class="parameter_name"><para>supertype</para></td><td class="parameter_description"><para>a <type>GVariantType</type></para><para>Passed as <code>supertype</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-tuple?</title><informalexample><programlisting>(define-values (%return) (variant-type:is-tuple? self))
</programlisting></informalexample><para>Determines if the given <parameter>type</parameter> is a tuple type.  This is true if the
type string for <parameter>type</parameter> starts with a '(' or if <parameter>type</parameter> is
<constant>G_VARIANT_TYPE_TUPLE</constant>.
</para>
<para>This function returns <constant>TRUE</constant> for any indefinite type for which every
definite subtype is a tuple type -- <constant>G_VARIANT_TYPE_TUPLE</constant>, for
example.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>is-variant?</title><informalexample><programlisting>(define-values (%return) (variant-type:is-variant? self))
</programlisting></informalexample><para>Determines if the given <parameter>type</parameter> is the variant type.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>key</title><informalexample><programlisting>(define-values (%return) (variant-type:key self))
</programlisting></informalexample><para>Determines the key type of a dictionary entry type.
</para>
<para>This function may only be used with a dictionary entry type.  Other
than the additional restriction, this call is equivalent to
<function>g_variant_type_first()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a dictionary entry <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>n-items</title><informalexample><programlisting>(define-values (%return) (variant-type:n-items self))
</programlisting></informalexample><para>Determines the number of items contained in a tuple or
dictionary entry type.
</para>
<para>This function may only be used with tuple or dictionary entry types,
but must not be used with the generic tuple type
<constant>G_VARIANT_TYPE_TUPLE</constant>.
</para>
<para>In the case of a dictionary entry type, this function will always
return 2.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a tuple or dictionary entry <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>next</title><informalexample><programlisting>(define-values (%return) (variant-type:next self))
</programlisting></informalexample><para>Determines the next item type of a tuple or dictionary entry
type.
</para>
<para><parameter>type</parameter> must be the result of a previous call to
<function>g_variant_type_first()</function> or <function>g_variant_type_next()</function>.
</para>
<para>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 <constant>NULL</constant>.
</para>
<para>For tuples, <constant>NULL</constant> is returned when <parameter>type</parameter> is the last item in a tuple.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type> from a previous call</para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>value</title><informalexample><programlisting>(define-values (%return) (variant-type:value self))
</programlisting></informalexample><para>Determines the value type of a dictionary entry type.
</para>
<para>This function may only be used with a dictionary entry type.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a dictionary entry <type>GVariantType</type></para><para>Passed as <code>self</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-type:new-tuple</title><informalexample><programlisting>(define-values (%return) (variant-type:new-tuple items))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>items</para></td><td class="parameter_description"><para></para><para>Passed as <code>items</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para></para><para>Inferred from <code>items</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-type:new-maybe</title><informalexample><programlisting>(define-values (%return) (variant-type:new-maybe element))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>element</para></td><td class="parameter_description"><para></para><para>Passed as <code>element</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-type:new-dict-entry</title><informalexample><programlisting>(define-values (%return) (variant-type:new-dict-entry key value))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para></para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para></para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-type:new-array</title><informalexample><programlisting>(define-values (%return) (variant-type:new-array element))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>element</para></td><td class="parameter_description"><para></para><para>Passed as <code>element</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-type:new</title><informalexample><programlisting>(define-values (%return) (variant-type:new type-string))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type_string</para></td><td class="parameter_description"><para></para><para>Passed as <code>type-string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-type:checked-</title><informalexample><programlisting>(define-values (%return) (variant-type:checked- arg0))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>arg0</para></td><td class="parameter_description"><para></para><para>Passed as <code>arg0</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-type:string-get-depth-</title><informalexample><programlisting>(define-values (%return) (variant-type:string-get-depth- type-string))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type_string</para></td><td class="parameter_description"><para></para><para>Passed as <code>type-string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-type:string-is-valid?</title><informalexample><programlisting>(define-values (%return) (variant-type:string-is-valid? type-string))
</programlisting></informalexample><para>Checks if <parameter>type_string</parameter> is a valid GVariant type string.  This call is
equivalent to calling <function>g_variant_type_string_scan()</function> and confirming
that the following character is a nul terminator.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type_string</para></td><td class="parameter_description"><para>a pointer to any string</para><para>Passed as <code>type-string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-type:string-scan</title><informalexample><programlisting>(define-values (%return endptr) (variant-type:string-scan string limit))
</programlisting></informalexample><para>Scan for a single complete and valid GVariant type string in <parameter>string</parameter>.
The memory pointed to by <parameter>limit</parameter> (or bytes beyond it) is never
accessed.
</para>
<para>If a valid type string is found, <parameter>endptr</parameter> is updated to point to the
first character past the end of the string that was found and <constant>TRUE</constant>
is returned.
</para>
<para>If there is no valid type string starting at <parameter>string</parameter>, or if the type
string does not end before <parameter>limit</parameter> then <constant>FALSE</constant> is returned.
</para>
<para>For the simple case of checking if a string is a valid type string,
see <function>g_variant_type_string_is_valid()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a pointer to any string</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>limit</para></td><td class="parameter_description"><para>the end of <parameter>string</parameter>, or <constant>NULL</constant></para><para>Passed as <code>limit</code></para></td></tr><tr><td class="parameter_name"><para>endptr</para></td><td class="parameter_description"><para>location to store the end pointer, or <constant>NULL</constant></para><para>Passed as <code>endptr</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry><refentry><refnamediv><refname>Functions</refname></refnamediv><refsect1><title>Functions</title><refsect2><title>byte-array:free</title><informalexample><programlisting>(define-values (%return) (byte-array:free array free-segment))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>free_segment</para></td><td class="parameter_description"><para></para><para>Passed as <code>free-segment</code></para></td></tr><tr><td class="parameter_name"><para>array</para></td><td class="parameter_description"><para></para><para>Passed as <code>array</code></para></td></tr><tr><td class="parameter_name"><para>mem</para></td><td class="parameter_description"><para></para><para>Passed as <code>mem</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>access</title><informalexample><programlisting>(define-values (%return) (access filename mode))
</programlisting></informalexample><para>A wrapper for the POSIX <function>access()</function> function. This function is used to
test a pathname for one or several of read, write or execute
permissions, or just existence.
</para>
<para>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.
</para>
<para>See your C library manual for more details about <function>access()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>filename</para></td><td class="parameter_description"><para>a pathname in the GLib file name encoding
    (UTF-8 on Windows)</para><para>Passed as <code>filename</code></para></td></tr><tr><td class="parameter_name"><para>mode</para></td><td class="parameter_description"><para>as in <function>access()</function></para><para>Passed as <code>mode</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ascii-digit-value</title><informalexample><programlisting>(define-values (%return) (ascii-digit-value c))
</programlisting></informalexample><para>Determines the numeric value of a character as a decimal digit.
Differs from <function>g_unichar_digit_value()</function> because it takes a char, so
there's no worry about sign extension if characters are signed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>an ASCII character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ascii-dtostr</title><informalexample><programlisting>(define-values (%return) (ascii-dtostr buffer buf-len d))
</programlisting></informalexample><para>Converts a <type>gdouble</type> to a string, using the '.' as
decimal point.
</para>
<para>This function generates enough precision that converting
the string back using <function>g_ascii_strtod()</function> 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 <parameter>G_ASCII_DTOSTR_BUF_SIZE</parameter> bytes, including the terminating
nul character, which is always added.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>buffer</para></td><td class="parameter_description"><para>A buffer to place the resulting string in</para><para>Passed as <code>buffer</code></para></td></tr><tr><td class="parameter_name"><para>buf_len</para></td><td class="parameter_description"><para>The length of the buffer.</para><para>Passed as <code>buf-len</code></para></td></tr><tr><td class="parameter_name"><para>d</para></td><td class="parameter_description"><para>The <type>gdouble</type> to convert</para><para>Passed as <code>d</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ascii-formatd</title><informalexample><programlisting>(define-values (%return) (ascii-formatd buffer buf-len format d))
</programlisting></informalexample><para>Converts a <type>gdouble</type> to a string, using the '.' as
decimal point. To format the number you pass in
a <function>printf()</function>-style format string. Allowed conversion
specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.
</para>
<para>The returned buffer is guaranteed to be nul-terminated.
</para>
<para>If you just want to want to serialize the value into a
string, use <function>g_ascii_dtostr()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>buffer</para></td><td class="parameter_description"><para>A buffer to place the resulting string in</para><para>Passed as <code>buffer</code></para></td></tr><tr><td class="parameter_name"><para>buf_len</para></td><td class="parameter_description"><para>The length of the buffer.</para><para>Passed as <code>buf-len</code></para></td></tr><tr><td class="parameter_name"><para>format</para></td><td class="parameter_description"><para>The <function>printf()</function>-style format to use for the
         code to use for converting.</para><para>Passed as <code>format</code></para></td></tr><tr><td class="parameter_name"><para>d</para></td><td class="parameter_description"><para>The <type>gdouble</type> to convert</para><para>Passed as <code>d</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ascii-strcasecmp</title><informalexample><programlisting>(define-values (%return) (ascii-strcasecmp s1 s2))
</programlisting></informalexample><para>Compare two strings, ignoring the case of ASCII characters.
</para>
<para>Unlike the BSD <function>strcasecmp()</function> function, this only recognizes standard
ASCII letters and ignores the locale, treating all non-ASCII
bytes as if they are not letters.
</para>
<para>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.
</para>
<para>Both <parameter>s1</parameter> and <parameter>s2</parameter> must be non-<constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>s1</para></td><td class="parameter_description"><para>string to compare with <parameter>s2</parameter></para><para>Passed as <code>s1</code></para></td></tr><tr><td class="parameter_name"><para>s2</para></td><td class="parameter_description"><para>string to compare with <parameter>s1</parameter></para><para>Passed as <code>s2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ascii-strdown</title><informalexample><programlisting>(define-values (%return) (ascii-strdown str len))
</programlisting></informalexample><para>Converts all upper case ASCII letters to lower case ASCII letters.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>length of <parameter>str</parameter> in bytes, or -1 if <parameter>str</parameter> is nul-terminated</para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ascii-string-to-signed</title><informalexample><programlisting>(define-values (%return out-num) (ascii-string-to-signed str base min max))
</programlisting></informalexample><para>A convenience function for converting a string to a signed number.
</para>
<para>This function assumes that <parameter>str</parameter> contains only a number of the given
<parameter>base</parameter> that is within inclusive bounds limited by <parameter>min</parameter> and <parameter>max</parameter>. If
this is true, then the converted number is stored in <parameter>out_num</parameter>. An
empty string is not a valid input. A string with leading or
trailing whitespace is also an invalid input.
</para>
<para><parameter>base</parameter> can be between 2 and 36 inclusive. Hexadecimal numbers must
not be prefixed with &quot;0x&quot; or &quot;0X&quot;. 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.
</para>
<para>Parsing failures result in an error with the <constant>G_NUMBER_PARSER_ERROR</constant>
domain. If the input is invalid, the error code will be
<constant>G_NUMBER_PARSER_ERROR_INVALID</constant>. If the parsed number is out of
bounds - <constant>G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS</constant>.
</para>
<para>See <function>g_ascii_strtoll()</function> if you have more complex needs such as
parsing a string which starts with a number, but then has other
characters.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>base</para></td><td class="parameter_description"><para>base of a parsed number</para><para>Passed as <code>base</code></para></td></tr><tr><td class="parameter_name"><para>min</para></td><td class="parameter_description"><para>a lower bound (inclusive)</para><para>Passed as <code>min</code></para></td></tr><tr><td class="parameter_name"><para>max</para></td><td class="parameter_description"><para>an upper bound (inclusive)</para><para>Passed as <code>max</code></para></td></tr><tr><td class="parameter_name"><para>out_num</para></td><td class="parameter_description"><para>a return location for a number</para><para>Passed as <code>out-num</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ascii-string-to-unsigned</title><informalexample><programlisting>(define-values (%return out-num) (ascii-string-to-unsigned str base min max))
</programlisting></informalexample><para>A convenience function for converting a string to an unsigned number.
</para>
<para>This function assumes that <parameter>str</parameter> contains only a number of the given
<parameter>base</parameter> that is within inclusive bounds limited by <parameter>min</parameter> and <parameter>max</parameter>. If
this is true, then the converted number is stored in <parameter>out_num</parameter>. 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
(<code>-</code> or <code>+</code>) is not a valid input for the unsigned parser.
</para>
<para><parameter>base</parameter> can be between 2 and 36 inclusive. Hexadecimal numbers must
not be prefixed with &quot;0x&quot; or &quot;0X&quot;. 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.
</para>
<para>Parsing failures result in an error with the <constant>G_NUMBER_PARSER_ERROR</constant>
domain. If the input is invalid, the error code will be
<constant>G_NUMBER_PARSER_ERROR_INVALID</constant>. If the parsed number is out of
bounds - <constant>G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS</constant>.
</para>
<para>See <function>g_ascii_strtoull()</function> if you have more complex needs such as
parsing a string which starts with a number, but then has other
characters.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>base</para></td><td class="parameter_description"><para>base of a parsed number</para><para>Passed as <code>base</code></para></td></tr><tr><td class="parameter_name"><para>min</para></td><td class="parameter_description"><para>a lower bound (inclusive)</para><para>Passed as <code>min</code></para></td></tr><tr><td class="parameter_name"><para>max</para></td><td class="parameter_description"><para>an upper bound (inclusive)</para><para>Passed as <code>max</code></para></td></tr><tr><td class="parameter_name"><para>out_num</para></td><td class="parameter_description"><para>a return location for a number</para><para>Passed as <code>out-num</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ascii-strncasecmp</title><informalexample><programlisting>(define-values (%return) (ascii-strncasecmp s1 s2 n))
</programlisting></informalexample><para>Compare <parameter>s1</parameter> and <parameter>s2</parameter>, ignoring the case of ASCII characters and any
characters after the first <parameter>n</parameter> in each string.
</para>
<para>Unlike the BSD <function>strcasecmp()</function> function, this only recognizes standard
ASCII letters and ignores the locale, treating all non-ASCII
characters as if they are not letters.
</para>
<para>The same warning as in <function>g_ascii_strcasecmp()</function> applies: Use this
function only on strings known to be in encodings where bytes
corresponding to ASCII letters always represent themselves.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>s1</para></td><td class="parameter_description"><para>string to compare with <parameter>s2</parameter></para><para>Passed as <code>s1</code></para></td></tr><tr><td class="parameter_name"><para>s2</para></td><td class="parameter_description"><para>string to compare with <parameter>s1</parameter></para><para>Passed as <code>s2</code></para></td></tr><tr><td class="parameter_name"><para>n</para></td><td class="parameter_description"><para>number of characters to compare</para><para>Passed as <code>n</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ascii-strtod</title><informalexample><programlisting>(define-values (%return endptr) (ascii-strtod nptr))
</programlisting></informalexample><para>Converts a string to a <type>gdouble</type> value.
</para>
<para>This function behaves like the standard <function>strtod()</function> 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.
</para>
<para>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 <function>strtod()</function> function.
</para>
<para>To convert from a <type>gdouble</type> to a string in a locale-insensitive
way, use <function>g_ascii_dtostr()</function>.
</para>
<para>If the correct value would cause overflow, plus or minus <constant>HUGE_VAL</constant>
is returned (according to the sign of the value), and <constant>ERANGE</constant> is
stored in <constant>errno</constant>. If the correct value would cause underflow,
zero is returned and <constant>ERANGE</constant> is stored in <constant>errno</constant>.
</para>
<para>This function resets <constant>errno</constant> before calling <function>strtod()</function> so that
you can reliably detect overflow and underflow.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>nptr</para></td><td class="parameter_description"><para>the string to convert to a numeric value.</para><para>Passed as <code>nptr</code></para></td></tr><tr><td class="parameter_name"><para>endptr</para></td><td class="parameter_description"><para>if non-<constant>NULL</constant>, it returns the
          character after the last character used in the conversion.</para><para>Passed as <code>endptr</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ascii-strtoll</title><informalexample><programlisting>(define-values (%return endptr) (ascii-strtoll nptr base))
</programlisting></informalexample><para>Converts a string to a <type>gint64</type> value.
This function behaves like the standard <function>strtoll()</function> function
does in the C locale. It does this without actually
changing the current locale, since that would not be
thread-safe.
</para>
<para>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 <function>strtoll()</function> function.
</para>
<para>If the correct value would cause overflow, <constant>G_MAXINT64</constant> or <constant>G_MININT64</constant>
is returned, and <code>ERANGE</code> is stored in <code>errno</code>.
If the base is outside the valid range, zero is returned, and
<code>EINVAL</code> is stored in <code>errno</code>. If the
string conversion fails, zero is returned, and <parameter>endptr</parameter> returns <parameter>nptr</parameter>
(if <parameter>endptr</parameter> is non-<constant>NULL</constant>).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>nptr</para></td><td class="parameter_description"><para>the string to convert to a numeric value.</para><para>Passed as <code>nptr</code></para></td></tr><tr><td class="parameter_name"><para>endptr</para></td><td class="parameter_description"><para>if non-<constant>NULL</constant>, it returns the
          character after the last character used in the conversion.</para><para>Passed as <code>endptr</code></para></td></tr><tr><td class="parameter_name"><para>base</para></td><td class="parameter_description"><para>to be used for the conversion, 2..36 or 0</para><para>Passed as <code>base</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ascii-strtoull</title><informalexample><programlisting>(define-values (%return endptr) (ascii-strtoull nptr base))
</programlisting></informalexample><para>Converts a string to a <type>guint64</type> value.
This function behaves like the standard <function>strtoull()</function> function
does in the C locale. It does this without actually
changing the current locale, since that would not be
thread-safe.
</para>
<para>Note that input with a leading minus sign (<code>-</code>) is accepted, and will return
the negation of the parsed number, unless that would overflow a <type>guint64</type>.
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 <code>-</code>.
</para>
<para>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 <function>strtoull()</function> function.
</para>
<para>If the correct value would cause overflow, <constant>G_MAXUINT64</constant>
is returned, and <code>ERANGE</code> is stored in <code>errno</code>.
If the base is outside the valid range, zero is returned, and
<code>EINVAL</code> is stored in <code>errno</code>.
If the string conversion fails, zero is returned, and <parameter>endptr</parameter> returns
<parameter>nptr</parameter> (if <parameter>endptr</parameter> is non-<constant>NULL</constant>).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>nptr</para></td><td class="parameter_description"><para>the string to convert to a numeric value.</para><para>Passed as <code>nptr</code></para></td></tr><tr><td class="parameter_name"><para>endptr</para></td><td class="parameter_description"><para>if non-<constant>NULL</constant>, it returns the
          character after the last character used in the conversion.</para><para>Passed as <code>endptr</code></para></td></tr><tr><td class="parameter_name"><para>base</para></td><td class="parameter_description"><para>to be used for the conversion, 2..36 or 0</para><para>Passed as <code>base</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ascii-strup</title><informalexample><programlisting>(define-values (%return) (ascii-strup str len))
</programlisting></informalexample><para>Converts all lower case ASCII letters to upper case ASCII letters.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>length of <parameter>str</parameter> in bytes, or -1 if <parameter>str</parameter> is nul-terminated</para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ascii-tolower</title><informalexample><programlisting>(define-values (%return) (ascii-tolower c))
</programlisting></informalexample><para>Convert a character to ASCII lower case.
</para>
<para>Unlike the standard C library <function>tolower()</function> 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 <constant>EOF</constant> but no need to worry about casting to <type>guchar</type>
before passing a possibly non-ASCII character in.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>any character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ascii-toupper</title><informalexample><programlisting>(define-values (%return) (ascii-toupper c))
</programlisting></informalexample><para>Convert a character to ASCII upper case.
</para>
<para>Unlike the standard C library <function>toupper()</function> 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 <constant>EOF</constant> but no need to worry about casting to <type>guchar</type>
before passing a possibly non-ASCII character in.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>any character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ascii-xdigit-value</title><informalexample><programlisting>(define-values (%return) (ascii-xdigit-value c))
</programlisting></informalexample><para>Determines the numeric value of a character as a hexadecimal
digit. Differs from <function>g_unichar_xdigit_value()</function> because it takes
a char, so there's no worry about sign extension if characters
are signed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>an ASCII character.</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>assert-warning</title><informalexample><programlisting>(define-values
  ()
  (assert-warning log-domain file line pretty-function expression))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>log_domain</para></td><td class="parameter_description"><para></para><para>Passed as <code>log-domain</code></para></td></tr><tr><td class="parameter_name"><para>file</para></td><td class="parameter_description"><para></para><para>Passed as <code>file</code></para></td></tr><tr><td class="parameter_name"><para>line</para></td><td class="parameter_description"><para></para><para>Passed as <code>line</code></para></td></tr><tr><td class="parameter_name"><para>pretty_function</para></td><td class="parameter_description"><para></para><para>Passed as <code>pretty-function</code></para></td></tr><tr><td class="parameter_name"><para>expression</para></td><td class="parameter_description"><para></para><para>Passed as <code>expression</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>assertion-message</title><informalexample><programlisting>(define-values () (assertion-message domain file line func message))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>domain</para></td><td class="parameter_description"><para></para><para>Passed as <code>domain</code></para></td></tr><tr><td class="parameter_name"><para>file</para></td><td class="parameter_description"><para></para><para>Passed as <code>file</code></para></td></tr><tr><td class="parameter_name"><para>line</para></td><td class="parameter_description"><para></para><para>Passed as <code>line</code></para></td></tr><tr><td class="parameter_name"><para>func</para></td><td class="parameter_description"><para></para><para>Passed as <code>func</code></para></td></tr><tr><td class="parameter_name"><para>message</para></td><td class="parameter_description"><para></para><para>Passed as <code>message</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>assertion-message-cmpstr</title><informalexample><programlisting>(define-values
  ()
  (assertion-message-cmpstr domain file line func expr arg1 cmp arg2))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>domain</para></td><td class="parameter_description"><para></para><para>Passed as <code>domain</code></para></td></tr><tr><td class="parameter_name"><para>file</para></td><td class="parameter_description"><para></para><para>Passed as <code>file</code></para></td></tr><tr><td class="parameter_name"><para>line</para></td><td class="parameter_description"><para></para><para>Passed as <code>line</code></para></td></tr><tr><td class="parameter_name"><para>func</para></td><td class="parameter_description"><para></para><para>Passed as <code>func</code></para></td></tr><tr><td class="parameter_name"><para>expr</para></td><td class="parameter_description"><para></para><para>Passed as <code>expr</code></para></td></tr><tr><td class="parameter_name"><para>arg1</para></td><td class="parameter_description"><para></para><para>Passed as <code>arg1</code></para></td></tr><tr><td class="parameter_name"><para>cmp</para></td><td class="parameter_description"><para></para><para>Passed as <code>cmp</code></para></td></tr><tr><td class="parameter_name"><para>arg2</para></td><td class="parameter_description"><para></para><para>Passed as <code>arg2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>assertion-message-cmpstrv</title><informalexample><programlisting>(define-values
  ()
  (assertion-message-cmpstrv
    domain
    file
    line
    func
    expr
    arg1
    arg2
    first-wrong-idx))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>domain</para></td><td class="parameter_description"><para></para><para>Passed as <code>domain</code></para></td></tr><tr><td class="parameter_name"><para>file</para></td><td class="parameter_description"><para></para><para>Passed as <code>file</code></para></td></tr><tr><td class="parameter_name"><para>line</para></td><td class="parameter_description"><para></para><para>Passed as <code>line</code></para></td></tr><tr><td class="parameter_name"><para>func</para></td><td class="parameter_description"><para></para><para>Passed as <code>func</code></para></td></tr><tr><td class="parameter_name"><para>expr</para></td><td class="parameter_description"><para></para><para>Passed as <code>expr</code></para></td></tr><tr><td class="parameter_name"><para>arg1</para></td><td class="parameter_description"><para></para><para>Passed as <code>arg1</code></para></td></tr><tr><td class="parameter_name"><para>arg2</para></td><td class="parameter_description"><para></para><para>Passed as <code>arg2</code></para></td></tr><tr><td class="parameter_name"><para>first_wrong_idx</para></td><td class="parameter_description"><para></para><para>Passed as <code>first-wrong-idx</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>assertion-message-error</title><informalexample><programlisting>(define-values
  ()
  (assertion-message-error
    domain
    file
    line
    func
    expr
    error
    error-domain
    error-code))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>domain</para></td><td class="parameter_description"><para></para><para>Passed as <code>domain</code></para></td></tr><tr><td class="parameter_name"><para>file</para></td><td class="parameter_description"><para></para><para>Passed as <code>file</code></para></td></tr><tr><td class="parameter_name"><para>line</para></td><td class="parameter_description"><para></para><para>Passed as <code>line</code></para></td></tr><tr><td class="parameter_name"><para>func</para></td><td class="parameter_description"><para></para><para>Passed as <code>func</code></para></td></tr><tr><td class="parameter_name"><para>expr</para></td><td class="parameter_description"><para></para><para>Passed as <code>expr</code></para></td></tr><tr><td class="parameter_name"><para>error</para></td><td class="parameter_description"><para></para><para>Passed as <code>error</code></para></td></tr><tr><td class="parameter_name"><para>error_domain</para></td><td class="parameter_description"><para></para><para>Passed as <code>error-domain</code></para></td></tr><tr><td class="parameter_name"><para>error_code</para></td><td class="parameter_description"><para></para><para>Passed as <code>error-code</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-int-add</title><informalexample><programlisting>(define-values (%return) (atomic-int-add atomic val))
</programlisting></informalexample><para>Atomically adds <parameter>val</parameter> to the value of <parameter>atomic</parameter>.
</para>
<para>Think of this operation as an atomic version of
<code>{ tmp = *atomic; *atomic += val; return tmp; }</code>.
</para>
<para>This call acts as a full compiler and hardware memory barrier.
</para>
<para>Before version 2.30, this function did not return a value
(but <function>g_atomic_int_exchange_and_add()</function> did, and had the same meaning).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>atomic</para></td><td class="parameter_description"><para>a pointer to a <type>gint</type> or <type>guint</type></para><para>Passed as <code>atomic</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>the value to add</para><para>Passed as <code>val</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-int-and</title><informalexample><programlisting>(define-values (%return) (atomic-int-and atomic val))
</programlisting></informalexample><para>Performs an atomic bitwise 'and' of the value of <parameter>atomic</parameter> and <parameter>val</parameter>,
storing the result back in <parameter>atomic</parameter>.
</para>
<para>This call acts as a full compiler and hardware memory barrier.
</para>
<para>Think of this operation as an atomic version of
<code>{ tmp = *atomic; *atomic &amp;= val; return tmp; }</code>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>atomic</para></td><td class="parameter_description"><para>a pointer to a <type>gint</type> or <type>guint</type></para><para>Passed as <code>atomic</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>the value to 'and'</para><para>Passed as <code>val</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-int-compare-and-exchange?</title><informalexample><programlisting>(define-values
  (%return)
  (atomic-int-compare-and-exchange? atomic oldval newval))
</programlisting></informalexample><para>Compares <parameter>atomic</parameter> to <parameter>oldval</parameter> and, if equal, sets it to <parameter>newval</parameter>.
If <parameter>atomic</parameter> was not equal to <parameter>oldval</parameter> then no change occurs.
</para>
<para>This compare and exchange is done atomically.
</para>
<para>Think of this operation as an atomic version of
<code>{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }</code>.
</para>
<para>This call acts as a full compiler and hardware memory barrier.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>atomic</para></td><td class="parameter_description"><para>a pointer to a <type>gint</type> or <type>guint</type></para><para>Passed as <code>atomic</code></para></td></tr><tr><td class="parameter_name"><para>oldval</para></td><td class="parameter_description"><para>the value to compare with</para><para>Passed as <code>oldval</code></para></td></tr><tr><td class="parameter_name"><para>newval</para></td><td class="parameter_description"><para>the value to conditionally replace with</para><para>Passed as <code>newval</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-int-dec-and-test?</title><informalexample><programlisting>(define-values (%return) (atomic-int-dec-and-test? atomic))
</programlisting></informalexample><para>Decrements the value of <parameter>atomic</parameter> by 1.
</para>
<para>Think of this operation as an atomic version of
<code>{ *atomic -= 1; return (*atomic == 0); }</code>.
</para>
<para>This call acts as a full compiler and hardware memory barrier.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>atomic</para></td><td class="parameter_description"><para>a pointer to a <type>gint</type> or <type>guint</type></para><para>Passed as <code>atomic</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-int-get</title><informalexample><programlisting>(define-values (%return) (atomic-int-get atomic))
</programlisting></informalexample><para>Gets the current value of <parameter>atomic</parameter>.
</para>
<para>This call acts as a full compiler and hardware
memory barrier (before the get).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>atomic</para></td><td class="parameter_description"><para>a pointer to a <type>gint</type> or <type>guint</type></para><para>Passed as <code>atomic</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-int-inc</title><informalexample><programlisting>(define-values () (atomic-int-inc atomic))
</programlisting></informalexample><para>Increments the value of <parameter>atomic</parameter> by 1.
</para>
<para>Think of this operation as an atomic version of <code>{ *atomic += 1; }</code>.
</para>
<para>This call acts as a full compiler and hardware memory barrier.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>atomic</para></td><td class="parameter_description"><para>a pointer to a <type>gint</type> or <type>guint</type></para><para>Passed as <code>atomic</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-int-or</title><informalexample><programlisting>(define-values (%return) (atomic-int-or atomic val))
</programlisting></informalexample><para>Performs an atomic bitwise 'or' of the value of <parameter>atomic</parameter> and <parameter>val</parameter>,
storing the result back in <parameter>atomic</parameter>.
</para>
<para>Think of this operation as an atomic version of
<code>{ tmp = *atomic; *atomic |= val; return tmp; }</code>.
</para>
<para>This call acts as a full compiler and hardware memory barrier.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>atomic</para></td><td class="parameter_description"><para>a pointer to a <type>gint</type> or <type>guint</type></para><para>Passed as <code>atomic</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>the value to 'or'</para><para>Passed as <code>val</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-int-set</title><informalexample><programlisting>(define-values () (atomic-int-set atomic newval))
</programlisting></informalexample><para>Sets the value of <parameter>atomic</parameter> to <parameter>newval</parameter>.
</para>
<para>This call acts as a full compiler and hardware
memory barrier (after the set).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>atomic</para></td><td class="parameter_description"><para>a pointer to a <type>gint</type> or <type>guint</type></para><para>Passed as <code>atomic</code></para></td></tr><tr><td class="parameter_name"><para>newval</para></td><td class="parameter_description"><para>a new value to store</para><para>Passed as <code>newval</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-int-xor</title><informalexample><programlisting>(define-values (%return) (atomic-int-xor atomic val))
</programlisting></informalexample><para>Performs an atomic bitwise 'xor' of the value of <parameter>atomic</parameter> and <parameter>val</parameter>,
storing the result back in <parameter>atomic</parameter>.
</para>
<para>Think of this operation as an atomic version of
<code>{ tmp = *atomic; *atomic ^= val; return tmp; }</code>.
</para>
<para>This call acts as a full compiler and hardware memory barrier.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>atomic</para></td><td class="parameter_description"><para>a pointer to a <type>gint</type> or <type>guint</type></para><para>Passed as <code>atomic</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>the value to 'xor'</para><para>Passed as <code>val</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-pointer-add</title><informalexample><programlisting>(define-values (%return) (atomic-pointer-add atomic val))
</programlisting></informalexample><para>Atomically adds <parameter>val</parameter> to the value of <parameter>atomic</parameter>.
</para>
<para>Think of this operation as an atomic version of
<code>{ tmp = *atomic; *atomic += val; return tmp; }</code>.
</para>
<para>This call acts as a full compiler and hardware memory barrier.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>atomic</para></td><td class="parameter_description"><para>a pointer to a <type>gpointer</type>-sized value</para><para>Passed as <code>atomic</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>the value to add</para><para>Passed as <code>val</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-pointer-and</title><informalexample><programlisting>(define-values (%return) (atomic-pointer-and atomic val))
</programlisting></informalexample><para>Performs an atomic bitwise 'and' of the value of <parameter>atomic</parameter> and <parameter>val</parameter>,
storing the result back in <parameter>atomic</parameter>.
</para>
<para>Think of this operation as an atomic version of
<code>{ tmp = *atomic; *atomic &amp;= val; return tmp; }</code>.
</para>
<para>This call acts as a full compiler and hardware memory barrier.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>atomic</para></td><td class="parameter_description"><para>a pointer to a <type>gpointer</type>-sized value</para><para>Passed as <code>atomic</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>the value to 'and'</para><para>Passed as <code>val</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-pointer-compare-and-exchange?</title><informalexample><programlisting>(define-values
  (%return)
  (atomic-pointer-compare-and-exchange? atomic oldval newval))
</programlisting></informalexample><para>Compares <parameter>atomic</parameter> to <parameter>oldval</parameter> and, if equal, sets it to <parameter>newval</parameter>.
If <parameter>atomic</parameter> was not equal to <parameter>oldval</parameter> then no change occurs.
</para>
<para>This compare and exchange is done atomically.
</para>
<para>Think of this operation as an atomic version of
<code>{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }</code>.
</para>
<para>This call acts as a full compiler and hardware memory barrier.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>atomic</para></td><td class="parameter_description"><para>a pointer to a <type>gpointer</type>-sized value</para><para>Passed as <code>atomic</code></para></td></tr><tr><td class="parameter_name"><para>oldval</para></td><td class="parameter_description"><para>the value to compare with</para><para>Passed as <code>oldval</code></para></td></tr><tr><td class="parameter_name"><para>newval</para></td><td class="parameter_description"><para>the value to conditionally replace with</para><para>Passed as <code>newval</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-pointer-get</title><informalexample><programlisting>(define-values (%return) (atomic-pointer-get atomic))
</programlisting></informalexample><para>Gets the current value of <parameter>atomic</parameter>.
</para>
<para>This call acts as a full compiler and hardware
memory barrier (before the get).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>atomic</para></td><td class="parameter_description"><para>a pointer to a <type>gpointer</type>-sized value</para><para>Passed as <code>atomic</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-pointer-or</title><informalexample><programlisting>(define-values (%return) (atomic-pointer-or atomic val))
</programlisting></informalexample><para>Performs an atomic bitwise 'or' of the value of <parameter>atomic</parameter> and <parameter>val</parameter>,
storing the result back in <parameter>atomic</parameter>.
</para>
<para>Think of this operation as an atomic version of
<code>{ tmp = *atomic; *atomic |= val; return tmp; }</code>.
</para>
<para>This call acts as a full compiler and hardware memory barrier.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>atomic</para></td><td class="parameter_description"><para>a pointer to a <type>gpointer</type>-sized value</para><para>Passed as <code>atomic</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>the value to 'or'</para><para>Passed as <code>val</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-pointer-set</title><informalexample><programlisting>(define-values () (atomic-pointer-set atomic newval))
</programlisting></informalexample><para>Sets the value of <parameter>atomic</parameter> to <parameter>newval</parameter>.
</para>
<para>This call acts as a full compiler and hardware
memory barrier (after the set).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>atomic</para></td><td class="parameter_description"><para>a pointer to a <type>gpointer</type>-sized value</para><para>Passed as <code>atomic</code></para></td></tr><tr><td class="parameter_name"><para>newval</para></td><td class="parameter_description"><para>a new value to store</para><para>Passed as <code>newval</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-pointer-xor</title><informalexample><programlisting>(define-values (%return) (atomic-pointer-xor atomic val))
</programlisting></informalexample><para>Performs an atomic bitwise 'xor' of the value of <parameter>atomic</parameter> and <parameter>val</parameter>,
storing the result back in <parameter>atomic</parameter>.
</para>
<para>Think of this operation as an atomic version of
<code>{ tmp = *atomic; *atomic ^= val; return tmp; }</code>.
</para>
<para>This call acts as a full compiler and hardware memory barrier.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>atomic</para></td><td class="parameter_description"><para>a pointer to a <type>gpointer</type>-sized value</para><para>Passed as <code>atomic</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>the value to 'xor'</para><para>Passed as <code>val</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-rc-box-acquire</title><informalexample><programlisting>(define-values (%return) (atomic-rc-box-acquire mem-block))
</programlisting></informalexample><para>Atomically acquires a reference on the data pointed by <parameter>mem_block</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>mem_block</para></td><td class="parameter_description"><para>a pointer to reference counted data</para><para>Passed as <code>mem-block</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-rc-box-alloc</title><informalexample><programlisting>(define-values (%return) (atomic-rc-box-alloc block-size))
</programlisting></informalexample><para>Allocates <parameter>block_size</parameter> bytes of memory, and adds atomic
reference counting semantics to it.
</para>
<para>The data will be freed when its reference count drops to
zero.
</para>
<para>The allocated data is guaranteed to be suitably aligned for any
built-in type.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>block_size</para></td><td class="parameter_description"><para>the size of the allocation, must be greater than 0</para><para>Passed as <code>block-size</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-rc-box-alloc0</title><informalexample><programlisting>(define-values (%return) (atomic-rc-box-alloc0 block-size))
</programlisting></informalexample><para>Allocates <parameter>block_size</parameter> bytes of memory, and adds atomic
reference counting semantics to it.
</para>
<para>The contents of the returned data is set to zero.
</para>
<para>The data will be freed when its reference count drops to
zero.
</para>
<para>The allocated data is guaranteed to be suitably aligned for any
built-in type.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>block_size</para></td><td class="parameter_description"><para>the size of the allocation, must be greater than 0</para><para>Passed as <code>block-size</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-rc-box-dup</title><informalexample><programlisting>(define-values (%return) (atomic-rc-box-dup block-size mem-block))
</programlisting></informalexample><para>Allocates a new block of data with atomic reference counting
semantics, and copies <parameter>block_size</parameter> bytes of <parameter>mem_block</parameter>
into it.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>block_size</para></td><td class="parameter_description"><para>the number of bytes to copy, must be greater than 0</para><para>Passed as <code>block-size</code></para></td></tr><tr><td class="parameter_name"><para>mem_block</para></td><td class="parameter_description"><para>the memory to copy</para><para>Passed as <code>mem-block</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-rc-box-get-size</title><informalexample><programlisting>(define-values (%return) (atomic-rc-box-get-size mem-block))
</programlisting></informalexample><para>Retrieves the size of the reference counted data pointed by <parameter>mem_block</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>mem_block</para></td><td class="parameter_description"><para>a pointer to reference counted data</para><para>Passed as <code>mem-block</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-rc-box-release</title><informalexample><programlisting>(define-values () (atomic-rc-box-release mem-block))
</programlisting></informalexample><para>Atomically releases a reference on the data pointed by <parameter>mem_block</parameter>.
</para>
<para>If the reference was the last one, it will free the
resources allocated for <parameter>mem_block</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>mem_block</para></td><td class="parameter_description"><para>a pointer to reference counted data</para><para>Passed as <code>mem-block</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-rc-box-release-full</title><informalexample><programlisting>(define-values () (atomic-rc-box-release-full mem-block clear-func))
</programlisting></informalexample><para>Atomically releases a reference on the data pointed by <parameter>mem_block</parameter>.
</para>
<para>If the reference was the last one, it will call <parameter>clear_func</parameter>
to clear the contents of <parameter>mem_block</parameter>, and then will free the
resources allocated for <parameter>mem_block</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>mem_block</para></td><td class="parameter_description"><para>a pointer to reference counted data</para><para>Passed as <code>mem-block</code></para></td></tr><tr><td class="parameter_name"><para>clear_func</para></td><td class="parameter_description"><para>a function to call when clearing the data</para><para>Passed as <code>clear-func</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-ref-count-compare?</title><informalexample><programlisting>(define-values (%return) (atomic-ref-count-compare? arc val))
</programlisting></informalexample><para>Atomically compares the current value of <parameter>arc</parameter> with <parameter>val</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>arc</para></td><td class="parameter_description"><para>the address of an atomic reference count variable</para><para>Passed as <code>arc</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>the value to compare</para><para>Passed as <code>val</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-ref-count-dec?</title><informalexample><programlisting>(define-values (%return) (atomic-ref-count-dec? arc))
</programlisting></informalexample><para>Atomically decreases the reference count.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>arc</para></td><td class="parameter_description"><para>the address of an atomic reference count variable</para><para>Passed as <code>arc</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-ref-count-inc</title><informalexample><programlisting>(define-values () (atomic-ref-count-inc arc))
</programlisting></informalexample><para>Atomically increases the reference count.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>arc</para></td><td class="parameter_description"><para>the address of an atomic reference count variable</para><para>Passed as <code>arc</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>atomic-ref-count-init</title><informalexample><programlisting>(define-values () (atomic-ref-count-init arc))
</programlisting></informalexample><para>Initializes a reference count variable.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>arc</para></td><td class="parameter_description"><para>the address of an atomic reference count variable</para><para>Passed as <code>arc</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>base64-decode</title><informalexample><programlisting>(define-values (%return out-len) (base64-decode text))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>text</para></td><td class="parameter_description"><para>zero-terminated string with base64 text to decode</para><para>Passed as <code>text</code></para></td></tr><tr><td class="parameter_name"><para>out_len</para></td><td class="parameter_description"><para>The length of the decoded data is written here</para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>base64-decode-inplace!</title><informalexample><programlisting>(define-values (%return text out-len) (base64-decode-inplace! text))
</programlisting></informalexample><para>Decode a sequence of Base-64 encoded text into binary data
by overwriting the input data.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>text</para></td><td class="parameter_description"><para>zero-terminated
       string with base64 text to decode</para><para>Passed as <code>text</code></para></td></tr><tr><td class="parameter_name"><para>out_len</para></td><td class="parameter_description"><para>The length of the decoded data is written here</para><para>Inferred from <code>text</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>base64-encode</title><informalexample><programlisting>(define-values (%return) (base64-encode data))
</programlisting></informalexample><para>Encode a sequence of binary data into its Base-64 stringified
representation.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>the binary data to encode</para><para>Passed as <code>data</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the length of <parameter>data</parameter></para><para>Inferred from <code>data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>base64-encode-close</title><informalexample><programlisting>(define-values
  (%return out state save)
  (base64-encode-close break-lines state save))
</programlisting></informalexample><para>Flush the status from a sequence of calls to <function>g_base64_encode_step()</function>.
</para>
<para>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.
</para>
<para>The <parameter>out</parameter> array will not be automatically nul-terminated.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>break_lines</para></td><td class="parameter_description"><para>whether to break long lines</para><para>Passed as <code>break-lines</code></para></td></tr><tr><td class="parameter_name"><para>out</para></td><td class="parameter_description"><para>pointer to destination buffer</para><para>Passed as <code>out</code></para></td></tr><tr><td class="parameter_name"><para>state</para></td><td class="parameter_description"><para>Saved state from <function>g_base64_encode_step()</function></para><para>Passed as <code>state</code></para></td></tr><tr><td class="parameter_name"><para>save</para></td><td class="parameter_description"><para>Saved state from <function>g_base64_encode_step()</function></para><para>Passed as <code>save</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>base64-encode-step</title><informalexample><programlisting>(define-values
  (%return out state save)
  (base64-encode-step in break-lines state save))
</programlisting></informalexample><para>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.
</para>
<para>When all of the data has been converted you must call
<function>g_base64_encode_close()</function> to flush the saved state.
</para>
<para>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: (<parameter>len</parameter> / 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:
((<parameter>len</parameter> / 3 + 1) * 4 + 4) / 76 + 1 bytes of extra space.
</para>
<para><parameter>break_lines</parameter> 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 <code>LF</code> characters, not
<code>CR LF</code> sequences, so the result cannot be passed directly to SMTP
or certain other protocols.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>in</para></td><td class="parameter_description"><para>the binary data to encode</para><para>Passed as <code>in</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the length of <parameter>in</parameter></para><para>Inferred from <code>in</code></para></td></tr><tr><td class="parameter_name"><para>break_lines</para></td><td class="parameter_description"><para>whether to break long lines</para><para>Passed as <code>break-lines</code></para></td></tr><tr><td class="parameter_name"><para>out</para></td><td class="parameter_description"><para>pointer to destination buffer</para><para>Passed as <code>out</code></para></td></tr><tr><td class="parameter_name"><para>state</para></td><td class="parameter_description"><para>Saved state between steps, initialize to 0</para><para>Passed as <code>state</code></para></td></tr><tr><td class="parameter_name"><para>save</para></td><td class="parameter_description"><para>Saved state between steps, initialize to 0</para><para>Passed as <code>save</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>bit-lock</title><informalexample><programlisting>(define-values () (bit-lock address lock-bit))
</programlisting></informalexample><para>Sets the indicated <parameter>lock_bit</parameter> in <parameter>address</parameter>.  If the bit is already
set, this call will block until <function>g_bit_unlock()</function> unsets the
corresponding bit.
</para>
<para>Attempting to lock on two different bits within the same integer is
not supported and will very probably cause deadlocks.
</para>
<para>The value of the bit that is set is (1u &lt;&lt; <parameter>bit</parameter>).  If <parameter>bit</parameter> is not
between 0 and 31 then the result is undefined.
</para>
<para>This function accesses <parameter>address</parameter> atomically.  All other accesses to
<parameter>address</parameter> must be atomic in order for this function to work
reliably.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>address</para></td><td class="parameter_description"><para>a pointer to an integer</para><para>Passed as <code>address</code></para></td></tr><tr><td class="parameter_name"><para>lock_bit</para></td><td class="parameter_description"><para>a bit value between 0 and 31</para><para>Passed as <code>lock-bit</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>bit-nth-lsf</title><informalexample><programlisting>(define-values (%return) (bit-nth-lsf mask nth-bit))
</programlisting></informalexample><para>Find the position of the first bit set in <parameter>mask</parameter>, searching
from (but not including) <parameter>nth_bit</parameter> upwards. Bits are numbered
from 0 (least significant) to sizeof(<type>gulong</type>) * 8 - 1 (31 or 63,
usually). To start searching from the 0th bit, set <parameter>nth_bit</parameter> to -1.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>mask</para></td><td class="parameter_description"><para>a <type>gulong</type> containing flags</para><para>Passed as <code>mask</code></para></td></tr><tr><td class="parameter_name"><para>nth_bit</para></td><td class="parameter_description"><para>the index of the bit to start the search from</para><para>Passed as <code>nth-bit</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>bit-nth-msf</title><informalexample><programlisting>(define-values (%return) (bit-nth-msf mask nth-bit))
</programlisting></informalexample><para>Find the position of the first bit set in <parameter>mask</parameter>, searching
from (but not including) <parameter>nth_bit</parameter> downwards. Bits are numbered
from 0 (least significant) to sizeof(<type>gulong</type>) * 8 - 1 (31 or 63,
usually). To start searching from the last bit, set <parameter>nth_bit</parameter> to
-1 or GLIB_SIZEOF_LONG * 8.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>mask</para></td><td class="parameter_description"><para>a <type>gulong</type> containing flags</para><para>Passed as <code>mask</code></para></td></tr><tr><td class="parameter_name"><para>nth_bit</para></td><td class="parameter_description"><para>the index of the bit to start the search from</para><para>Passed as <code>nth-bit</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>bit-storage</title><informalexample><programlisting>(define-values (%return) (bit-storage number))
</programlisting></informalexample><para>Gets the number of bits used to hold <parameter>number</parameter>,
e.g. if <parameter>number</parameter> is 4, 3 bits are needed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>number</para></td><td class="parameter_description"><para>a <type>guint</type></para><para>Passed as <code>number</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>bit-trylock?</title><informalexample><programlisting>(define-values (%return) (bit-trylock? address lock-bit))
</programlisting></informalexample><para>Sets the indicated <parameter>lock_bit</parameter> in <parameter>address</parameter>, returning <constant>TRUE</constant> if
successful.  If the bit is already set, returns <constant>FALSE</constant> immediately.
</para>
<para>Attempting to lock on two different bits within the same integer is
not supported.
</para>
<para>The value of the bit that is set is (1u &lt;&lt; <parameter>bit</parameter>).  If <parameter>bit</parameter> is not
between 0 and 31 then the result is undefined.
</para>
<para>This function accesses <parameter>address</parameter> atomically.  All other accesses to
<parameter>address</parameter> must be atomic in order for this function to work
reliably.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>address</para></td><td class="parameter_description"><para>a pointer to an integer</para><para>Passed as <code>address</code></para></td></tr><tr><td class="parameter_name"><para>lock_bit</para></td><td class="parameter_description"><para>a bit value between 0 and 31</para><para>Passed as <code>lock-bit</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>bit-unlock</title><informalexample><programlisting>(define-values () (bit-unlock address lock-bit))
</programlisting></informalexample><para>Clears the indicated <parameter>lock_bit</parameter> in <parameter>address</parameter>.  If another thread is
currently blocked in <function>g_bit_lock()</function> on this same bit then it will be
woken up.
</para>
<para>This function accesses <parameter>address</parameter> atomically.  All other accesses to
<parameter>address</parameter> must be atomic in order for this function to work
reliably.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>address</para></td><td class="parameter_description"><para>a pointer to an integer</para><para>Passed as <code>address</code></para></td></tr><tr><td class="parameter_name"><para>lock_bit</para></td><td class="parameter_description"><para>a bit value between 0 and 31</para><para>Passed as <code>lock-bit</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>bookmark-file-error-quark</title><informalexample><programlisting>(define-values (%return) (bookmark-file-error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>build-filenamev</title><informalexample><programlisting>(define-values (%return) (build-filenamev args))
</programlisting></informalexample><para>Behaves exactly like <function>g_build_filename()</function>, but takes the path elements
as a string array, instead of varargs. This function is mainly
meant for language bindings.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>args</para></td><td class="parameter_description"><para><constant>NULL</constant>-terminated
    array of strings containing the path elements.</para><para>Passed as <code>args</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>build-pathv</title><informalexample><programlisting>(define-values (%return) (build-pathv separator args))
</programlisting></informalexample><para>Behaves exactly like <function>g_build_path()</function>, but takes the path elements
as a string array, instead of varargs. This function is mainly
meant for language bindings.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>separator</para></td><td class="parameter_description"><para>a string used to separator the elements of the path.</para><para>Passed as <code>separator</code></para></td></tr><tr><td class="parameter_name"><para>args</para></td><td class="parameter_description"><para><constant>NULL</constant>-terminated
    array of strings containing the path elements.</para><para>Passed as <code>args</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>byte-array-free</title><informalexample><programlisting>(define-values (%return) (byte-array-free array free-segment))
</programlisting></informalexample><para>Frees the memory allocated by the <type>GByteArray</type>. If <parameter>free_segment</parameter> is
<constant>TRUE</constant> it frees the actual byte data. If the reference count of
<parameter>array</parameter> is greater than one, the <type>GByteArray</type> wrapper is preserved but
the size of <parameter>array</parameter> will be set to zero.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>array</para></td><td class="parameter_description"><para>a <type>GByteArray</type></para><para>Passed as <code>array</code></para></td></tr><tr><td class="parameter_name"><para>free_segment</para></td><td class="parameter_description"><para>if <constant>TRUE</constant> the actual byte data is freed as well</para><para>Passed as <code>free-segment</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>byte-array-free-to-bytes</title><informalexample><programlisting>(define-values (%return) (byte-array-free-to-bytes array))
</programlisting></informalexample><para>Transfers the data from the <type>GByteArray</type> into a new immutable <type>GBytes</type>.
</para>
<para>The <type>GByteArray</type> is freed unless the reference count of <parameter>array</parameter> is greater
than one, the <type>GByteArray</type> wrapper is preserved but the size of <parameter>array</parameter>
will be set to zero.
</para>
<para>This is identical to using <function>g_bytes_new_take()</function> and <function>g_byte_array_free()</function>
together.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>array</para></td><td class="parameter_description"><para>a <type>GByteArray</type></para><para>Passed as <code>array</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>byte-array-new</title><informalexample><programlisting>(define-values (%return) (byte-array-new))
</programlisting></informalexample><para>Creates a new <type>GByteArray</type> with a reference count of 1.</para></refsect2><refsect2><title>byte-array-new-take</title><informalexample><programlisting>(define-values (%return) (byte-array-new-take data))
</programlisting></informalexample><para>Create byte array containing the data. The data will be owned by the array
and will be freed with <function>g_free()</function>, i.e. it could be allocated using <function>g_strdup()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>byte data for the array</para><para>Passed as <code>data</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>length of <parameter>data</parameter></para><para>Inferred from <code>data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>byte-array-steal</title><informalexample><programlisting>(define-values (%return len) (byte-array-steal array len))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>array</para></td><td class="parameter_description"><para>a <type>GByteArray</type>.</para><para>Passed as <code>array</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>pointer to retrieve the number of
   elements of the original array</para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>byte-array-unref</title><informalexample><programlisting>(define-values () (byte-array-unref array))
</programlisting></informalexample><para>Atomically decrements the reference count of <parameter>array</parameter> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>array</para></td><td class="parameter_description"><para>A <type>GByteArray</type></para><para>Passed as <code>array</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>canonicalize-filename</title><informalexample><programlisting>(define-values (%return) (canonicalize-filename filename relative-to))
</programlisting></informalexample><para>Gets the canonical file name from <parameter>filename</parameter>. All triple slashes are turned into
single slashes, and all <code>..</code> and <code>.</code>s resolved against <parameter>relative_to</parameter>.
</para>
<para>Symlinks are not followed, and the returned path is guaranteed to be absolute.
</para>
<para>If <parameter>filename</parameter> is an absolute path, <parameter>relative_to</parameter> is ignored. Otherwise,
<parameter>relative_to</parameter> will be prepended to <parameter>filename</parameter> to make it absolute. <parameter>relative_to</parameter>
must be an absolute path, or <constant>NULL</constant>. If <parameter>relative_to</parameter> is <constant>NULL</constant>, it'll fallback
to <function>g_get_current_dir()</function>.
</para>
<para>This function never fails, and will canonicalize file paths even if they don't
exist.
</para>
<para>No file system I/O is done.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>filename</para></td><td class="parameter_description"><para>the name of the file</para><para>Passed as <code>filename</code></para></td></tr><tr><td class="parameter_name"><para>relative_to</para></td><td class="parameter_description"><para>the relative directory, or <constant>NULL</constant>
to use the current working directory</para><para>Passed as <code>relative-to</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>chdir</title><informalexample><programlisting>(define-values (%return) (chdir path))
</programlisting></informalexample><para>A wrapper for the POSIX <function>chdir()</function> function. The function changes the
current directory of the process to <parameter>path</parameter>.
</para>
<para>See your C library manual for more details about <function>chdir()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>path</para></td><td class="parameter_description"><para>a pathname in the GLib file name encoding
    (UTF-8 on Windows)</para><para>Passed as <code>path</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>check-version</title><informalexample><programlisting>(define-values
  (%return)
  (check-version required-major required-minor required-micro))
</programlisting></informalexample><para>Checks that the GLib library in use is compatible with the
given version. Generally you would pass in the constants
<type>GLIB_MAJOR_VERSION</type>, <type>GLIB_MINOR_VERSION</type>, <type>GLIB_MICRO_VERSION</type>
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.
</para>
<para>Compatibility is defined by two things: first the version
of the running library is newer than the version
<parameter>required_major</parameter>.required_minor.<parameter>required_micro</parameter>. Second
the running library must be binary compatible with the
version <parameter>required_major</parameter>.required_minor.<parameter>required_micro</parameter>
(same major version.)</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>required_major</para></td><td class="parameter_description"><para>the required major version</para><para>Passed as <code>required-major</code></para></td></tr><tr><td class="parameter_name"><para>required_minor</para></td><td class="parameter_description"><para>the required minor version</para><para>Passed as <code>required-minor</code></para></td></tr><tr><td class="parameter_name"><para>required_micro</para></td><td class="parameter_description"><para>the required micro version</para><para>Passed as <code>required-micro</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>checksum-type-get-length</title><informalexample><programlisting>(define-values (%return) (checksum-type-get-length checksum-type))
</programlisting></informalexample><para>Gets the length in bytes of digests of type <parameter>checksum_type</parameter></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>checksum_type</para></td><td class="parameter_description"><para>a <type>GChecksumType</type></para><para>Passed as <code>checksum-type</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>child-watch-add</title><informalexample><programlisting>(define-values (%return) (child-watch-add priority pid function data notify))
</programlisting></informalexample><para>Sets a function to be called when the child indicated by <parameter>pid</parameter>
exits, at a default priority, <type>G_PRIORITY_DEFAULT</type>.
</para>
<para>If you obtain <parameter>pid</parameter> from <function>g_spawn_async()</function> or <function>g_spawn_async_with_pipes()</function>
you will need to pass <type>G_SPAWN_DO_NOT_REAP_CHILD</type> as flag to
the spawn function for the child watching to work.
</para>
<para>Note that on platforms where <type>GPid</type> must be explicitly closed
(see <function>g_spawn_close_pid()</function>) <parameter>pid</parameter> must not be closed while the
source is still active. Typically, you will want to call
<function>g_spawn_close_pid()</function> in the callback function for the source.
</para>
<para>GLib supports only a single callback per process id.
On POSIX platforms, the same restrictions mentioned for
<function>g_child_watch_source_new()</function> apply to this function.
</para>
<para>This internally creates a main loop source using
<function>g_child_watch_source_new()</function> and attaches it to the main loop context
using <function>g_source_attach()</function>. You can do these steps manually if you
need greater control.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>notify</para></td><td class="parameter_description"><para></para><para>Passed as <code>notify</code></para></td></tr><tr><td class="parameter_name"><para>priority</para></td><td class="parameter_description"><para></para><para>Passed as <code>priority</code></para></td></tr><tr><td class="parameter_name"><para>pid</para></td><td class="parameter_description"><para>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).</para><para>Passed as <code>pid</code></para></td></tr><tr><td class="parameter_name"><para>function</para></td><td class="parameter_description"><para>function to call</para><para>Passed as <code>function</code></para></td></tr><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>data to pass to <parameter>function</parameter></para><para>Passed as <code>data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>child-watch-source-new</title><informalexample><programlisting>(define-values (%return) (child-watch-source-new pid))
</programlisting></informalexample><para>Creates a new child_watch source.
</para>
<para>The source will not initially be associated with any <type>GMainContext</type>
and must be added to one with <function>g_source_attach()</function> before it will be
executed.
</para>
<para>Note that child watch sources can only be used in conjunction with
<code>g_spawn...</code> when the <constant>G_SPAWN_DO_NOT_REAP_CHILD</constant> flag is used.
</para>
<para>Note that on platforms where <type>GPid</type> must be explicitly closed
(see <function>g_spawn_close_pid()</function>) <parameter>pid</parameter> must not be closed while the
source is still active. Typically, you will want to call
<function>g_spawn_close_pid()</function> in the callback function for the source.
</para>
<para>On POSIX platforms, the following restrictions apply to this API
due to limitations in POSIX process interfaces:
</para>
<para>* <parameter>pid</parameter> must be a child of this process
* <parameter>pid</parameter> must be positive
* the application must not call <code>waitpid</code> with a non-positive
  first argument, for instance in another thread
* the application must not wait for <parameter>pid</parameter> to exit by any other
  mechanism, including <code>waitpid(pid, ...)</code> or a second child-watch
  source for the same <parameter>pid</parameter>
* the application must not ignore SIGCHILD
</para>
<para>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 <code>ECHILD</code> was received by <code>waitpid</code>.
</para>
<para>Calling <code>waitpid</code> for specific processes other than <parameter>pid</parameter> remains a
valid thing to do.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>pid</para></td><td class="parameter_description"><para>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).</para><para>Passed as <code>pid</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>clear-error</title><informalexample><programlisting>(define-values () (clear-error))
</programlisting></informalexample><para>If <parameter>err</parameter> or *<parameter>err</parameter> is <constant>NULL</constant>, does nothing. Otherwise,
calls <function>g_error_free()</function> on *<parameter>err</parameter> and sets *<parameter>err</parameter> to <constant>NULL</constant>.</para></refsect2><refsect2><title>close?</title><informalexample><programlisting>(define-values (%return) (close? fd))
</programlisting></informalexample><para>This wraps the <function>close()</function> call; in case of error, <constant>errno</constant> will be
preserved, but the error will also be stored as a <type>GError</type> in <parameter>error</parameter>.
</para>
<para>Besides using <type>GError</type>, there is another major reason to prefer this
function over the call provided by the system; on Unix, it will
attempt to correctly handle <constant>EINTR</constant>, which has platform-specific
semantics.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>fd</para></td><td class="parameter_description"><para>A file descriptor</para><para>Passed as <code>fd</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>compute-checksum-for-bytes</title><informalexample><programlisting>(define-values (%return) (compute-checksum-for-bytes checksum-type data))
</programlisting></informalexample><para>Computes the checksum for a binary <parameter>data</parameter>. This is a
convenience wrapper for <function>g_checksum_new()</function>, <function>g_checksum_get_string()</function>
and <function>g_checksum_free()</function>.
</para>
<para>The hexadecimal string returned will be in lower case.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>checksum_type</para></td><td class="parameter_description"><para>a <type>GChecksumType</type></para><para>Passed as <code>checksum-type</code></para></td></tr><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>binary blob to compute the digest of</para><para>Passed as <code>data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>compute-checksum-for-data</title><informalexample><programlisting>(define-values (%return) (compute-checksum-for-data checksum-type data))
</programlisting></informalexample><para>Computes the checksum for a binary <parameter>data</parameter> of <parameter>length</parameter>. This is a
convenience wrapper for <function>g_checksum_new()</function>, <function>g_checksum_get_string()</function>
and <function>g_checksum_free()</function>.
</para>
<para>The hexadecimal string returned will be in lower case.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>checksum_type</para></td><td class="parameter_description"><para>a <type>GChecksumType</type></para><para>Passed as <code>checksum-type</code></para></td></tr><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>binary blob to compute the digest of</para><para>Passed as <code>data</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>length of <parameter>data</parameter></para><para>Inferred from <code>data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>compute-checksum-for-string</title><informalexample><programlisting>(define-values
  (%return)
  (compute-checksum-for-string checksum-type str length))
</programlisting></informalexample><para>Computes the checksum of a string.
</para>
<para>The hexadecimal string returned will be in lower case.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>checksum_type</para></td><td class="parameter_description"><para>a <type>GChecksumType</type></para><para>Passed as <code>checksum-type</code></para></td></tr><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>the string to compute the checksum of</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of the string, or -1 if the string is null-terminated.</para><para>Passed as <code>length</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>compute-hmac-for-bytes</title><informalexample><programlisting>(define-values (%return) (compute-hmac-for-bytes digest-type key data))
</programlisting></informalexample><para>Computes the HMAC for a binary <parameter>data</parameter>. This is a
convenience wrapper for <function>g_hmac_new()</function>, <function>g_hmac_get_string()</function>
and <function>g_hmac_unref()</function>.
</para>
<para>The hexadecimal string returned will be in lower case.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>digest_type</para></td><td class="parameter_description"><para>a <type>GChecksumType</type> to use for the HMAC</para><para>Passed as <code>digest-type</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to use in the HMAC</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>binary blob to compute the HMAC of</para><para>Passed as <code>data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>compute-hmac-for-data</title><informalexample><programlisting>(define-values (%return) (compute-hmac-for-data digest-type key data))
</programlisting></informalexample><para>Computes the HMAC for a binary <parameter>data</parameter> of <parameter>length</parameter>. This is a
convenience wrapper for <function>g_hmac_new()</function>, <function>g_hmac_get_string()</function>
and <function>g_hmac_unref()</function>.
</para>
<para>The hexadecimal string returned will be in lower case.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>digest_type</para></td><td class="parameter_description"><para>a <type>GChecksumType</type> to use for the HMAC</para><para>Passed as <code>digest-type</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to use in the HMAC</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>key_len</para></td><td class="parameter_description"><para>the length of the key</para><para>Inferred from <code>key</code></para></td></tr><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>binary blob to compute the HMAC of</para><para>Passed as <code>data</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>length of <parameter>data</parameter></para><para>Inferred from <code>data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>compute-hmac-for-string</title><informalexample><programlisting>(define-values (%return) (compute-hmac-for-string digest-type key str length))
</programlisting></informalexample><para>Computes the HMAC for a string.
</para>
<para>The hexadecimal string returned will be in lower case.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>digest_type</para></td><td class="parameter_description"><para>a <type>GChecksumType</type> to use for the HMAC</para><para>Passed as <code>digest-type</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to use in the HMAC</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>key_len</para></td><td class="parameter_description"><para>the length of the key</para><para>Inferred from <code>key</code></para></td></tr><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>the string to compute the HMAC for</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of the string, or -1 if the string is nul-terminated</para><para>Passed as <code>length</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>convert</title><informalexample><programlisting>(define-values
  (%return bytes-read bytes-written)
  (convert str to-codeset from-codeset))
</programlisting></informalexample><para>Converts a string from one character set to another.
</para>
<para>Note that you should use <function>g_iconv()</function> for streaming conversions.
Despite the fact that <parameter>bytes_read</parameter> 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 <function>g_convert()</function>,
<function>g_convert_with_iconv()</function> or <function>g_convert_with_fallback()</function>. (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.)
</para>
<para>Using extensions such as &quot;//TRANSLIT&quot; may not work (or may not work
well) on many platforms.  Consider using <function>g_str_to_ascii()</function> instead.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>
                <para>the string to convert.</para></para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>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 <parameter>len</parameter> parameter is unsafe)</para><para>Inferred from <code>str</code></para></td></tr><tr><td class="parameter_name"><para>to_codeset</para></td><td class="parameter_description"><para>name of character set into which to convert <parameter>str</parameter></para><para>Passed as <code>to-codeset</code></para></td></tr><tr><td class="parameter_name"><para>from_codeset</para></td><td class="parameter_description"><para>character set of <parameter>str</parameter>.</para><para>Passed as <code>from-codeset</code></para></td></tr><tr><td class="parameter_name"><para>bytes_read</para></td><td class="parameter_description"><para>location to store the number of bytes in
                the input string that were successfully converted, or <constant>NULL</constant>.
                Even if the conversion was successful, this may be
                less than <parameter>len</parameter> if there were partial characters
                at the end of the input. If the error
                <type>G_CONVERT_ERROR_ILLEGAL_SEQUENCE</type> occurs, the value
                stored will be the byte offset after the last valid
                input sequence.</para><para>Passed as <code>bytes-read</code></para></td></tr><tr><td class="parameter_name"><para>bytes_written</para></td><td class="parameter_description"><para>the number of bytes stored in
                the output buffer (not including the terminating nul).</para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>convert-error-quark</title><informalexample><programlisting>(define-values (%return) (convert-error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>convert-with-fallback</title><informalexample><programlisting>(define-values
  (%return bytes-read bytes-written)
  (convert-with-fallback str to-codeset from-codeset fallback))
</programlisting></informalexample><para>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 <parameter>fallback</parameter> will be honored. Some
systems may do an approximate conversion from <parameter>from_codeset</parameter>
to <parameter>to_codeset</parameter> in their <function>iconv()</function> functions,
in which case GLib will simply return that approximate conversion.
</para>
<para>Note that you should use <function>g_iconv()</function> for streaming conversions.
Despite the fact that <parameter>bytes_read</parameter> 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 <function>g_convert()</function>,
<function>g_convert_with_iconv()</function> or <function>g_convert_with_fallback()</function>. (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.)</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>
               <para>the string to convert.</para></para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>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 <parameter>len</parameter> parameter is unsafe)</para><para>Inferred from <code>str</code></para></td></tr><tr><td class="parameter_name"><para>to_codeset</para></td><td class="parameter_description"><para>name of character set into which to convert <parameter>str</parameter></para><para>Passed as <code>to-codeset</code></para></td></tr><tr><td class="parameter_name"><para>from_codeset</para></td><td class="parameter_description"><para>character set of <parameter>str</parameter>.</para><para>Passed as <code>from-codeset</code></para></td></tr><tr><td class="parameter_name"><para>fallback</para></td><td class="parameter_description"><para>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 <constant>NULL</constant>, characters not in the target encoding will
               be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.</para><para>Passed as <code>fallback</code></para></td></tr><tr><td class="parameter_name"><para>bytes_read</para></td><td class="parameter_description"><para>location to store the number of bytes in
               the input string that were successfully converted, or <constant>NULL</constant>.
               Even if the conversion was successful, this may be
               less than <parameter>len</parameter> if there were partial characters
               at the end of the input.</para><para>Passed as <code>bytes-read</code></para></td></tr><tr><td class="parameter_name"><para>bytes_written</para></td><td class="parameter_description"><para>the number of bytes stored in
                the output buffer (not including the terminating nul).</para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>dataset-destroy</title><informalexample><programlisting>(define-values () (dataset-destroy dataset-location))
</programlisting></informalexample><para>Destroys the dataset, freeing all memory allocated, and calling any
destroy functions set for data elements.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dataset_location</para></td><td class="parameter_description"><para>the location identifying the dataset.</para><para>Passed as <code>dataset-location</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>dataset-foreach</title><informalexample><programlisting>(define-values () (dataset-foreach dataset-location func user-data))
</programlisting></informalexample><para>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 <parameter>dataset_location</parameter> can be protected from any modifications
during invocation of this function, it should not be called.
</para>
<para><parameter>func</parameter> can make changes to the dataset, but the iteration will not
reflect changes made during the <function>g_dataset_foreach()</function> call, other
than skipping over elements that are removed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dataset_location</para></td><td class="parameter_description"><para>the location identifying the dataset.</para><para>Passed as <code>dataset-location</code></para></td></tr><tr><td class="parameter_name"><para>func</para></td><td class="parameter_description"><para>the function to call for each data element.</para><para>Passed as <code>func</code></para></td></tr><tr><td class="parameter_name"><para>user_data</para></td><td class="parameter_description"><para>user data to pass to the function.</para><para>Passed as <code>user-data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>dataset-id-get-data</title><informalexample><programlisting>(define-values (%return) (dataset-id-get-data dataset-location key-id))
</programlisting></informalexample><para>Gets the data element corresponding to a <type>GQuark</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dataset_location</para></td><td class="parameter_description"><para>the location identifying the dataset.</para><para>Passed as <code>dataset-location</code></para></td></tr><tr><td class="parameter_name"><para>key_id</para></td><td class="parameter_description"><para>the <type>GQuark</type> id to identify the data element.</para><para>Passed as <code>key-id</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-get-days-in-month</title><informalexample><programlisting>(define-values (%return) (date-get-days-in-month month year))
</programlisting></informalexample><para>Returns the number of days in a month, taking leap
years into account.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>month</para></td><td class="parameter_description"><para>month</para><para>Passed as <code>month</code></para></td></tr><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para>year</para><para>Passed as <code>year</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-get-monday-weeks-in-year</title><informalexample><programlisting>(define-values (%return) (date-get-monday-weeks-in-year year))
</programlisting></informalexample><para>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.)</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para>a year</para><para>Passed as <code>year</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-get-sunday-weeks-in-year</title><informalexample><programlisting>(define-values (%return) (date-get-sunday-weeks-in-year year))
</programlisting></informalexample><para>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.)</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para>year to count weeks in</para><para>Passed as <code>year</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-is-leap-year?</title><informalexample><programlisting>(define-values (%return) (date-is-leap-year? year))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the year is a leap year.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para>year to check</para><para>Passed as <code>year</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-strftime</title><informalexample><programlisting>(define-values (%return) (date-strftime s slen format date))
</programlisting></informalexample><para>Generates a printed representation of the date, in a
[locale][setlocale]-specific way.
Works just like the platform's C library <function>strftime()</function> function,
but only accepts date-related formats; time-related formats
give undefined results. Date must be valid. Unlike <function>strftime()</function>
(which uses the locale encoding), works on a UTF-8 format
string and stores a UTF-8 result.
</para>
<para>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 <function>g_date_strftime()</function> would
make the \%F provided by the C99 <function>strftime()</function> work on Windows
where the C library only complies to C89.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>s</para></td><td class="parameter_description"><para>destination buffer</para><para>Passed as <code>s</code></para></td></tr><tr><td class="parameter_name"><para>slen</para></td><td class="parameter_description"><para>buffer size</para><para>Passed as <code>slen</code></para></td></tr><tr><td class="parameter_name"><para>format</para></td><td class="parameter_description"><para>format string</para><para>Passed as <code>format</code></para></td></tr><tr><td class="parameter_name"><para>date</para></td><td class="parameter_description"><para>valid <type>GDate</type></para><para>Passed as <code>date</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-time-compare</title><informalexample><programlisting>(define-values (%return) (date-time-compare dt1 dt2))
</programlisting></informalexample><para>A comparison function for <type>GDateTimes</type> that is suitable
as a <type>GCompareFunc</type>. Both <type>GDateTimes</type> must be non-<constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dt1</para></td><td class="parameter_description"><para>first <type>GDateTime</type> to compare</para><para>Passed as <code>dt1</code></para></td></tr><tr><td class="parameter_name"><para>dt2</para></td><td class="parameter_description"><para>second <type>GDateTime</type> to compare</para><para>Passed as <code>dt2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-time-equal?</title><informalexample><programlisting>(define-values (%return) (date-time-equal? dt1 dt2))
</programlisting></informalexample><para>Checks to see if <parameter>dt1</parameter> and <parameter>dt2</parameter> are equal.
</para>
<para>Equal here means that they represent the same moment after converting
them to the same time zone.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dt1</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>dt1</code></para></td></tr><tr><td class="parameter_name"><para>dt2</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>dt2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-time-hash</title><informalexample><programlisting>(define-values (%return) (date-time-hash datetime))
</programlisting></informalexample><para>Hashes <parameter>datetime</parameter> into a <type>guint</type>, suitable for use within <type>GHashTable</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>datetime</para></td><td class="parameter_description"><para>a <type>GDateTime</type></para><para>Passed as <code>datetime</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-valid-day?</title><informalexample><programlisting>(define-values (%return) (date-valid-day? day))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the day of the month is valid (a day is valid if it's
between 1 and 31 inclusive).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>day</para></td><td class="parameter_description"><para>day to check</para><para>Passed as <code>day</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-valid-dmy?</title><informalexample><programlisting>(define-values (%return) (date-valid-dmy? day month year))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the day-month-year triplet forms a valid, existing day
in the range of days <type>GDate</type> understands (Year 1 or later, no more than
a few thousand years in the future).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>day</para></td><td class="parameter_description"><para>day</para><para>Passed as <code>day</code></para></td></tr><tr><td class="parameter_name"><para>month</para></td><td class="parameter_description"><para>month</para><para>Passed as <code>month</code></para></td></tr><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para>year</para><para>Passed as <code>year</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-valid-julian?</title><informalexample><programlisting>(define-values (%return) (date-valid-julian? julian-date))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the Julian day is valid. Anything greater than zero
is basically a valid Julian, though there is a 32-bit limit.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>julian_date</para></td><td class="parameter_description"><para>Julian day to check</para><para>Passed as <code>julian-date</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-valid-month?</title><informalexample><programlisting>(define-values (%return) (date-valid-month? month))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the month value is valid. The 12 <type>GDateMonth</type>
enumeration values are the only valid months.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>month</para></td><td class="parameter_description"><para>month</para><para>Passed as <code>month</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-valid-weekday?</title><informalexample><programlisting>(define-values (%return) (date-valid-weekday? weekday))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the weekday is valid. The seven <type>GDateWeekday</type> enumeration
values are the only valid weekdays.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>weekday</para></td><td class="parameter_description"><para>weekday</para><para>Passed as <code>weekday</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>date-valid-year?</title><informalexample><programlisting>(define-values (%return) (date-valid-year? year))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the year is valid. Any year greater than 0 is valid,
though there is a 16-bit limit to what <type>GDate</type> will understand.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>year</para></td><td class="parameter_description"><para>year</para><para>Passed as <code>year</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>dcgettext</title><informalexample><programlisting>(define-values (%return) (dcgettext domain msgid category))
</programlisting></informalexample><para>This is a variant of <function>g_dgettext()</function> that allows specifying a locale
category instead of always using <code>LC_MESSAGES</code>. See <function>g_dgettext()</function> for
more information about how this functions differs from calling
<function>dcgettext()</function> directly.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>domain</para></td><td class="parameter_description"><para>the translation domain to use, or <constant>NULL</constant> to use
  the domain set with <function>textdomain()</function></para><para>Passed as <code>domain</code></para></td></tr><tr><td class="parameter_name"><para>msgid</para></td><td class="parameter_description"><para>message to translate</para><para>Passed as <code>msgid</code></para></td></tr><tr><td class="parameter_name"><para>category</para></td><td class="parameter_description"><para>a locale category</para><para>Passed as <code>category</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>dgettext</title><informalexample><programlisting>(define-values (%return) (dgettext domain msgid))
</programlisting></informalexample><para>This function is a wrapper of <function>dgettext()</function> which does not translate
the message if the default domain as set with <function>textdomain()</function> has no
translations for the current locale.
</para>
<para>The advantage of using this function over <function>dgettext()</function> 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 <function>textdomain()</function> and <function>setlocale()</function> should
precede any <function>g_dgettext()</function> invocations.  For GTK+, it means calling
<function>textdomain()</function> before gtk_init or its variants.
</para>
<para>This function disables translations if and only if upon its first
call all the following conditions hold:
</para>
<para>- <parameter>domain</parameter> is not <constant>NULL</constant>
</para>
<para>- <function>textdomain()</function> has been called to set a default text domain
</para>
<para>- there is no translations available for the default text domain
  and the current locale
</para>
<para>- current locale is not &quot;C&quot; or any English locales (those
  starting with &quot;en_&quot;)
</para>
<para>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 <function>textdomain()</function> after initializing GTK+.
</para>
<para>Applications should normally not use this function directly,
but use the <function>_()</function> macro for translations.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>domain</para></td><td class="parameter_description"><para>the translation domain to use, or <constant>NULL</constant> to use
  the domain set with <function>textdomain()</function></para><para>Passed as <code>domain</code></para></td></tr><tr><td class="parameter_name"><para>msgid</para></td><td class="parameter_description"><para>message to translate</para><para>Passed as <code>msgid</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>dir-make-tmp</title><informalexample><programlisting>(define-values (%return) (dir-make-tmp tmpl))
</programlisting></informalexample><para>Creates a subdirectory in the preferred directory for temporary
files (as returned by <function>g_get_tmp_dir()</function>).
</para>
<para><parameter>tmpl</parameter> should be a string in the GLib file name encoding containing
a sequence of six 'X' characters, as the parameter to <function>g_mkstemp()</function>.
However, unlike these functions, the template should only be a
basename, no directory components are allowed. If template is
<constant>NULL</constant>, a default template is used.
</para>
<para>Note that in contrast to <function>g_mkdtemp()</function> (and <function>mkdtemp()</function>) <parameter>tmpl</parameter> is not
modified, and might thus be a read-only literal string.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tmpl</para></td><td class="parameter_description"><para>Template for directory name,
    as in <function>g_mkdtemp()</function>, basename only, or <constant>NULL</constant> for a default template</para><para>Passed as <code>tmpl</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>direct-equal?</title><informalexample><programlisting>(define-values (%return) (direct-equal? v1 v2))
</programlisting></informalexample><para>Compares two <type>gpointer</type> arguments and returns <constant>TRUE</constant> if they are equal.
It can be passed to <function>g_hash_table_new()</function> as the <parameter>key_equal_func</parameter>
parameter, when using opaque pointers compared by pointer value as
keys in a <type>GHashTable</type>.
</para>
<para>This equality function is also appropriate for keys that are integers
stored in pointers, such as <code>GINT_TO_POINTER (n)</code>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>v1</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>v1</code></para></td></tr><tr><td class="parameter_name"><para>v2</para></td><td class="parameter_description"><para>a key to compare with <parameter>v1</parameter></para><para>Passed as <code>v2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>direct-hash</title><informalexample><programlisting>(define-values (%return) (direct-hash v))
</programlisting></informalexample><para>Converts a gpointer to a hash value.
It can be passed to <function>g_hash_table_new()</function> as the <parameter>hash_func</parameter> parameter,
when using opaque pointers compared by pointer value as keys in a
<type>GHashTable</type>.
</para>
<para>This hash function is also appropriate for keys that are integers
stored in pointers, such as <code>GINT_TO_POINTER (n)</code>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>v</para></td><td class="parameter_description"><para>a <type>gpointer</type> key</para><para>Passed as <code>v</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>dngettext</title><informalexample><programlisting>(define-values (%return) (dngettext domain msgid msgid-plural n))
</programlisting></informalexample><para>This function is a wrapper of <function>dngettext()</function> which does not translate
the message if the default domain as set with <function>textdomain()</function> has no
translations for the current locale.
</para>
<para>See <function>g_dgettext()</function> for details of how this differs from <function>dngettext()</function>
proper.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>domain</para></td><td class="parameter_description"><para>the translation domain to use, or <constant>NULL</constant> to use
  the domain set with <function>textdomain()</function></para><para>Passed as <code>domain</code></para></td></tr><tr><td class="parameter_name"><para>msgid</para></td><td class="parameter_description"><para>message to translate</para><para>Passed as <code>msgid</code></para></td></tr><tr><td class="parameter_name"><para>msgid_plural</para></td><td class="parameter_description"><para>plural form of the message</para><para>Passed as <code>msgid-plural</code></para></td></tr><tr><td class="parameter_name"><para>n</para></td><td class="parameter_description"><para>the quantity for which translation is needed</para><para>Passed as <code>n</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>double-equal?</title><informalexample><programlisting>(define-values (%return) (double-equal? v1 v2))
</programlisting></informalexample><para>Compares the two <type>gdouble</type> values being pointed to and returns
<constant>TRUE</constant> if they are equal.
It can be passed to <function>g_hash_table_new()</function> as the <parameter>key_equal_func</parameter>
parameter, when using non-<constant>NULL</constant> pointers to doubles as keys in a
<type>GHashTable</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>v1</para></td><td class="parameter_description"><para>a pointer to a <type>gdouble</type> key</para><para>Passed as <code>v1</code></para></td></tr><tr><td class="parameter_name"><para>v2</para></td><td class="parameter_description"><para>a pointer to a <type>gdouble</type> key to compare with <parameter>v1</parameter></para><para>Passed as <code>v2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>double-hash</title><informalexample><programlisting>(define-values (%return) (double-hash v))
</programlisting></informalexample><para>Converts a pointer to a <type>gdouble</type> to a hash value.
It can be passed to <function>g_hash_table_new()</function> as the <parameter>hash_func</parameter> parameter,
It can be passed to <function>g_hash_table_new()</function> as the <parameter>hash_func</parameter> parameter,
when using non-<constant>NULL</constant> pointers to doubles as keys in a <type>GHashTable</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>v</para></td><td class="parameter_description"><para>a pointer to a <type>gdouble</type> key</para><para>Passed as <code>v</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>dpgettext</title><informalexample><programlisting>(define-values (%return) (dpgettext domain msgctxtid msgidoffset))
</programlisting></informalexample><para>This function is a variant of <function>g_dgettext()</function> which supports
a disambiguating message context. GNU gettext uses the
'\004' character to separate the message context and
message id in <parameter>msgctxtid</parameter>.
If 0 is passed as <parameter>msgidoffset</parameter>, this function will fall back to
trying to use the deprecated convention of using &quot;|&quot; as a separation
character.
</para>
<para>This uses <function>g_dgettext()</function> internally. See that functions for differences
with <function>dgettext()</function> proper.
</para>
<para>Applications should normally not use this function directly,
but use the <function>C_()</function> macro for translations with context.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>domain</para></td><td class="parameter_description"><para>the translation domain to use, or <constant>NULL</constant> to use
  the domain set with <function>textdomain()</function></para><para>Passed as <code>domain</code></para></td></tr><tr><td class="parameter_name"><para>msgctxtid</para></td><td class="parameter_description"><para>a combined message context and message id, separated
  by a \004 character</para><para>Passed as <code>msgctxtid</code></para></td></tr><tr><td class="parameter_name"><para>msgidoffset</para></td><td class="parameter_description"><para>the offset of the message id in <parameter>msgctxid</parameter></para><para>Passed as <code>msgidoffset</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>dpgettext2</title><informalexample><programlisting>(define-values (%return) (dpgettext2 domain context msgid))
</programlisting></informalexample><para>This function is a variant of <function>g_dgettext()</function> which supports
a disambiguating message context. GNU gettext uses the
'\004' character to separate the message context and
message id in <parameter>msgctxtid</parameter>.
</para>
<para>This uses <function>g_dgettext()</function> internally. See that functions for differences
with <function>dgettext()</function> proper.
</para>
<para>This function differs from <function>C_()</function> in that it is not a macro and
thus you may use non-string-literals as context and msgid arguments.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>domain</para></td><td class="parameter_description"><para>the translation domain to use, or <constant>NULL</constant> to use
  the domain set with <function>textdomain()</function></para><para>Passed as <code>domain</code></para></td></tr><tr><td class="parameter_name"><para>context</para></td><td class="parameter_description"><para>the message context</para><para>Passed as <code>context</code></para></td></tr><tr><td class="parameter_name"><para>msgid</para></td><td class="parameter_description"><para>the message</para><para>Passed as <code>msgid</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>environ-getenv</title><informalexample><programlisting>(define-values (%return) (environ-getenv envp variable))
</programlisting></informalexample><para>Returns the value of the environment variable <parameter>variable</parameter> in the
provided list <parameter>envp</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>envp</para></td><td class="parameter_description"><para>
    <para>an environment list (eg, as returned from <function>g_get_environ()</function>), or <constant>NULL</constant>
    for an empty environment list</para></para><para>Passed as <code>envp</code></para></td></tr><tr><td class="parameter_name"><para>variable</para></td><td class="parameter_description"><para>the environment variable to get</para><para>Passed as <code>variable</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>environ-setenv</title><informalexample><programlisting>(define-values (%return) (environ-setenv envp variable value overwrite))
</programlisting></informalexample><para>Sets the environment variable <parameter>variable</parameter> in the provided list
<parameter>envp</parameter> to <parameter>value</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>envp</para></td><td class="parameter_description"><para>
    <para>an environment list that can be freed using <function>g_strfreev()</function> (e.g., as
    returned from <function>g_get_environ()</function>), or <constant>NULL</constant> for an empty
    environment list</para></para><para>Passed as <code>envp</code></para></td></tr><tr><td class="parameter_name"><para>variable</para></td><td class="parameter_description"><para>the environment variable to set, must not
    contain '='</para><para>Passed as <code>variable</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>the value for to set the variable to</para><para>Passed as <code>value</code></para></td></tr><tr><td class="parameter_name"><para>overwrite</para></td><td class="parameter_description"><para>whether to change the variable if it already exists</para><para>Passed as <code>overwrite</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>environ-unsetenv</title><informalexample><programlisting>(define-values (%return) (environ-unsetenv envp variable))
</programlisting></informalexample><para>Removes the environment variable <parameter>variable</parameter> from the provided
environment <parameter>envp</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>envp</para></td><td class="parameter_description"><para>
    <para>an environment list that can be freed using <function>g_strfreev()</function> (e.g., as
    returned from <function>g_get_environ()</function>), or <constant>NULL</constant> for an empty environment list</para></para><para>Passed as <code>envp</code></para></td></tr><tr><td class="parameter_name"><para>variable</para></td><td class="parameter_description"><para>the environment variable to remove, must not
    contain '='</para><para>Passed as <code>variable</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>file-error-from-errno</title><informalexample><programlisting>(define-values (%return) (file-error-from-errno err-no))
</programlisting></informalexample><para>Gets a <type>GFileError</type> constant based on the passed-in <parameter>err_no</parameter>.
For example, if you pass in <code>EEXIST</code> this function returns
<type>G_FILE_ERROR_EXIST</type>. Unlike <code>errno</code> values, you can portably
assume that all <type>GFileError</type> values will exist.
</para>
<para>Normally a <type>GFileError</type> value goes into a <type>GError</type> returned
from a function that manipulates files. So you would use
<function>g_file_error_from_errno()</function> when constructing a <type>GError</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>err_no</para></td><td class="parameter_description"><para>an &quot;errno&quot; value</para><para>Passed as <code>err-no</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>file-error-quark</title><informalexample><programlisting>(define-values (%return) (file-error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>file-get-contents</title><informalexample><programlisting>(define-values (%return contents length) (file-get-contents filename))
</programlisting></informalexample><para>Reads an entire file into allocated memory, with good error
checking.
</para>
<para>If the call was successful, it returns <constant>TRUE</constant> and sets <parameter>contents</parameter> to the file
contents and <parameter>length</parameter> to the length of the file contents in bytes. The string
stored in <parameter>contents</parameter> will be nul-terminated, so for text files you can pass
<constant>NULL</constant> for the <parameter>length</parameter> argument. If the call was not successful, it returns
<constant>FALSE</constant> and sets <parameter>error</parameter>. The error domain is <type>G_FILE_ERROR</type>. Possible error
codes are those in the <type>GFileError</type> enumeration. In the error case,
<parameter>contents</parameter> is set to <constant>NULL</constant> and <parameter>length</parameter> is set to zero.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>filename</para></td><td class="parameter_description"><para>name of a file to read contents from, in the GLib file name encoding</para><para>Passed as <code>filename</code></para></td></tr><tr><td class="parameter_name"><para>contents</para></td><td class="parameter_description"><para>location to store an allocated string, use <function>g_free()</function> to free
    the returned string</para><para>Passed as <code>contents</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>location to store length in bytes of the contents, or <constant>NULL</constant></para><para>Inferred from <code>contents</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>file-open-tmp</title><informalexample><programlisting>(define-values (%return name-used) (file-open-tmp tmpl))
</programlisting></informalexample><para>Opens a file for writing in the preferred directory for temporary
files (as returned by <function>g_get_tmp_dir()</function>).
</para>
<para><parameter>tmpl</parameter> should be a string in the GLib file name encoding containing
a sequence of six 'X' characters, as the parameter to <function>g_mkstemp()</function>.
However, unlike these functions, the template should only be a
basename, no directory components are allowed. If template is
<constant>NULL</constant>, a default template is used.
</para>
<para>Note that in contrast to <function>g_mkstemp()</function> (and <function>mkstemp()</function>) <parameter>tmpl</parameter> is not
modified, and might thus be a read-only literal string.
</para>
<para>Upon success, and if <parameter>name_used</parameter> is non-<constant>NULL</constant>, the actual name used
is returned in <parameter>name_used</parameter>. This string should be freed with <function>g_free()</function>
when not needed any longer. The returned name is in the GLib file
name encoding.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tmpl</para></td><td class="parameter_description"><para>Template for file name, as in
    <function>g_mkstemp()</function>, basename only, or <constant>NULL</constant> for a default template</para><para>Passed as <code>tmpl</code></para></td></tr><tr><td class="parameter_name"><para>name_used</para></td><td class="parameter_description"><para>location to store actual name used,
    or <constant>NULL</constant></para><para>Passed as <code>name-used</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>file-read-link</title><informalexample><programlisting>(define-values (%return) (file-read-link filename))
</programlisting></informalexample><para>Reads the contents of the symbolic link <parameter>filename</parameter> like the POSIX
<function>readlink()</function> function.  The returned string is in the encoding used
for filenames. Use <function>g_filename_to_utf8()</function> to convert it to UTF-8.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>filename</para></td><td class="parameter_description"><para>the symbolic link</para><para>Passed as <code>filename</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>file-set-contents?</title><informalexample><programlisting>(define-values (%return) (file-set-contents? filename contents))
</programlisting></informalexample><para>Writes all of <parameter>contents</parameter> to a file named <parameter>filename</parameter>. This is a convenience
wrapper around calling <function>g_file_set_contents()</function> with <code>flags</code> set to
<code>G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING</code> and
<code>mode</code> set to <code>0666</code>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>filename</para></td><td class="parameter_description"><para>name of a file to write <parameter>contents</parameter> to, in the GLib file name
  encoding</para><para>Passed as <code>filename</code></para></td></tr><tr><td class="parameter_name"><para>contents</para></td><td class="parameter_description"><para>string to write to the file</para><para>Passed as <code>contents</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>length of <parameter>contents</parameter>, or -1 if <parameter>contents</parameter> is a nul-terminated string</para><para>Inferred from <code>contents</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>file-set-contents-full?</title><informalexample><programlisting>(define-values
  (%return)
  (file-set-contents-full? filename contents flags mode))
</programlisting></informalexample><para>Writes all of <parameter>contents</parameter> to a file named <parameter>filename</parameter>, with good error checking.
If a file called <parameter>filename</parameter> already exists it will be overwritten.
</para>
<para><parameter>flags</parameter> 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.
</para>
<para>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 <parameter>flags</parameter> has any value other than
<constant>G_FILE_SET_CONTENTS_NONE</constant> then this function may call <code>fsync()</code>.
</para>
<para>If <constant>G_FILE_SET_CONTENTS_CONSISTENT</constant> is set in <parameter>flags</parameter>, the operation is atomic
in the sense that it is first written to a temporary file which is then
renamed to the final name.
</para>
<para>Notes:
</para>
<para>- On UNIX, if <parameter>filename</parameter> already exists hard links to <parameter>filename</parameter> will break.
  Also since the file is recreated, existing permissions, access control
  lists, metadata etc. may be lost. If <parameter>filename</parameter> is a symbolic link,
  the link itself will be replaced, not the linked file.
</para>
<para>- On UNIX, if <parameter>filename</parameter> already exists and is non-empty, and if the system
  supports it (via a journalling filesystem or equivalent), and if
  <constant>G_FILE_SET_CONTENTS_CONSISTENT</constant> is set in <parameter>flags</parameter>, the <code>fsync()</code> call (or
  equivalent) will be used to ensure atomic replacement: <parameter>filename</parameter>
  will contain either its old contents or <parameter>contents</parameter>, even in the face of
  system power loss, the disk being unsafely removed, etc.
</para>
<para>- On UNIX, if <parameter>filename</parameter> does not already exist or is empty, there is a
  possibility that system power loss etc. after calling this function will
  leave <parameter>filename</parameter> empty or full of NUL bytes, depending on the underlying
  filesystem, unless <constant>G_FILE_SET_CONTENTS_DURABLE</constant> and
  <constant>G_FILE_SET_CONTENTS_CONSISTENT</constant> are set in <parameter>flags</parameter>.
</para>
<para>- 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.
</para>
<para>- 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
  <parameter>filename</parameter> already exists and is open.
</para>
<para>If the call was successful, it returns <constant>TRUE</constant>. If the call was not successful,
it returns <constant>FALSE</constant> and sets <parameter>error</parameter>. The error domain is <type>G_FILE_ERROR</type>.
Possible error codes are those in the <type>GFileError</type> enumeration.
</para>
<para>Note that the name for the temporary file is constructed by appending up
to 7 characters to <parameter>filename</parameter>.
</para>
<para>If the file didn’t exist before and is created, it will be given the
permissions from <parameter>mode</parameter>. Otherwise, the permissions of the existing file may
be changed to <parameter>mode</parameter> depending on <parameter>flags</parameter>, or they may remain unchanged.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>filename</para></td><td class="parameter_description"><para>name of a file to write <parameter>contents</parameter> to, in the GLib file name
  encoding</para><para>Passed as <code>filename</code></para></td></tr><tr><td class="parameter_name"><para>contents</para></td><td class="parameter_description"><para>string to write to the file</para><para>Passed as <code>contents</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>length of <parameter>contents</parameter>, or -1 if <parameter>contents</parameter> is a nul-terminated string</para><para>Inferred from <code>contents</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags controlling the safety vs speed of the operation</para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>mode</para></td><td class="parameter_description"><para>file mode, as passed to <code>open()</code>; typically this will be <code>0666</code></para><para>Passed as <code>mode</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>file-test?</title><informalexample><programlisting>(define-values (%return) (file-test? filename test))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if any of the tests in the bitfield <parameter>test</parameter> are
<constant>TRUE</constant>. For example, <code>(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)</code>
will return <constant>TRUE</constant> if the file exists; the check whether it's a
directory doesn't matter since the existence test is <constant>TRUE</constant>. With
the current set of available tests, there's no point passing in
more than one test at a time.
</para>
<para>Apart from <constant>G_FILE_TEST_IS_SYMLINK</constant> all tests follow symbolic links,
so for a symbolic link to a regular file <function>g_file_test()</function> will return
<constant>TRUE</constant> for both <constant>G_FILE_TEST_IS_SYMLINK</constant> and <constant>G_FILE_TEST_IS_REGULAR</constant>.
</para>
<para>Note, that for a dangling symbolic link <function>g_file_test()</function> will return
<constant>TRUE</constant> for <constant>G_FILE_TEST_IS_SYMLINK</constant> and <constant>FALSE</constant> for all other flags.
</para>
<para>You should never use <function>g_file_test()</function> 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 <constant>G_FILE_TEST_IS_SYMLINK</constant>
to know whether it is safe to write to a file without being
tricked into writing into a different location. It doesn't work!
<informalexample><programlisting>
 // DON'T DO THIS
 if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK))
   {
     fd = g_open (filename, O_WRONLY);
     // write to fd
   }
</programlisting></informalexample></para>

<para>Another thing to note is that <constant>G_FILE_TEST_EXISTS</constant> and
<constant>G_FILE_TEST_IS_EXECUTABLE</constant> are implemented using the <function>access()</function>
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.
</para>
<para>On Windows, there are no symlinks, so testing for
<constant>G_FILE_TEST_IS_SYMLINK</constant> will always return <constant>FALSE</constant>. Testing for
<constant>G_FILE_TEST_IS_EXECUTABLE</constant> 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 <code>PATHEXT</code> environment variable.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>filename</para></td><td class="parameter_description"><para>a filename to test in the
    GLib file name encoding</para><para>Passed as <code>filename</code></para></td></tr><tr><td class="parameter_name"><para>test</para></td><td class="parameter_description"><para>bitfield of <type>GFileTest</type> flags</para><para>Passed as <code>test</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>filename-display-basename</title><informalexample><programlisting>(define-values (%return) (filename-display-basename filename))
</programlisting></informalexample><para>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.
</para>
<para>If GLib cannot make sense of the encoding of <parameter>filename</parameter>, 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
&quot;\357\277\275&quot; in octal notation) to find out if <parameter>filename</parameter> was in an invalid
encoding.
</para>
<para>You must pass the whole absolute pathname to this functions so that
translation of well known locations can be done.
</para>
<para>This function is preferred over <function>g_filename_display_name()</function> if you know the
whole path, as it allows translation.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>filename</para></td><td class="parameter_description"><para>an absolute pathname in the
    GLib file name encoding</para><para>Passed as <code>filename</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>filename-display-name</title><informalexample><programlisting>(define-values (%return) (filename-display-name filename))
</programlisting></informalexample><para>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 <function>g_filename_to_utf8()</function>, the result is guaranteed to be non-<constant>NULL</constant>
even if the filename actually isn't in the GLib file name encoding.
</para>
<para>If GLib cannot make sense of the encoding of <parameter>filename</parameter>, 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
&quot;\357\277\275&quot; in octal notation) to find out if <parameter>filename</parameter> was in an invalid
encoding.
</para>
<para>If you know the whole pathname of the file you should use
<function>g_filename_display_basename()</function>, since that allows location-based
translation of filenames.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>filename</para></td><td class="parameter_description"><para>a pathname hopefully in the
    GLib file name encoding</para><para>Passed as <code>filename</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>filename-from-uri</title><informalexample><programlisting>(define-values (%return hostname) (filename-from-uri uri))
</programlisting></informalexample><para>Converts an escaped ASCII-encoded URI to a local filename in the
encoding used for filenames.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a uri describing a filename (escaped, encoded in ASCII).</para><para>Passed as <code>uri</code></para></td></tr><tr><td class="parameter_name"><para>hostname</para></td><td class="parameter_description"><para>Location to store hostname for the URI.
           If there is no hostname in the URI, <constant>NULL</constant> will be
           stored in this location.</para><para>Passed as <code>hostname</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>filename-from-utf8</title><informalexample><programlisting>(define-values
  (%return bytes-read bytes-written)
  (filename-from-utf8 utf8string len))
</programlisting></informalexample><para>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].
</para>
<para>The input string shall not contain nul characters even if the <parameter>len</parameter>
argument is positive. A nul character found inside the string will result
in error <constant>G_CONVERT_ERROR_ILLEGAL_SEQUENCE</constant>. If the filename encoding is
not UTF-8 and the conversion output contains a nul character, the error
<constant>G_CONVERT_ERROR_EMBEDDED_NUL</constant> is set and the function returns <constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>utf8string</para></td><td class="parameter_description"><para>a UTF-8 encoded string.</para><para>Passed as <code>utf8string</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the length of the string, or -1 if the string is
                nul-terminated.</para><para>Passed as <code>len</code></para></td></tr><tr><td class="parameter_name"><para>bytes_read</para></td><td class="parameter_description"><para>location to store the number of bytes in
                the input string that were successfully converted, or <constant>NULL</constant>.
                Even if the conversion was successful, this may be
                less than <parameter>len</parameter> if there were partial characters
                at the end of the input. If the error
                <constant>G_CONVERT_ERROR_ILLEGAL_SEQUENCE</constant> occurs, the value
                stored will be the byte offset after the last valid
                input sequence.</para><para>Passed as <code>bytes-read</code></para></td></tr><tr><td class="parameter_name"><para>bytes_written</para></td><td class="parameter_description"><para>the number of bytes stored in
                the output buffer (not including the terminating nul).</para><para>Passed as <code>bytes-written</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>filename-to-uri</title><informalexample><programlisting>(define-values (%return) (filename-to-uri filename hostname))
</programlisting></informalexample><para>Converts an absolute filename to an escaped ASCII-encoded URI, with the path
component following Section 3.3. of RFC 2396.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>filename</para></td><td class="parameter_description"><para>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</para><para>Passed as <code>filename</code></para></td></tr><tr><td class="parameter_name"><para>hostname</para></td><td class="parameter_description"><para>A UTF-8 encoded hostname, or <constant>NULL</constant> for none.</para><para>Passed as <code>hostname</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>filename-to-utf8</title><informalexample><programlisting>(define-values
  (%return bytes-read bytes-written)
  (filename-to-utf8 opsysstring len))
</programlisting></informalexample><para>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].
</para>
<para>The input string shall not contain nul characters even if the <parameter>len</parameter>
argument is positive. A nul character found inside the string will result
in error <constant>G_CONVERT_ERROR_ILLEGAL_SEQUENCE</constant>.
If the source encoding is not UTF-8 and the conversion output contains a
nul character, the error <constant>G_CONVERT_ERROR_EMBEDDED_NUL</constant> is set and the
function returns <constant>NULL</constant>. Use <function>g_convert()</function> to produce output that
may contain embedded nul characters.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>opsysstring</para></td><td class="parameter_description"><para>a string in the encoding for filenames</para><para>Passed as <code>opsysstring</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>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 <parameter>len</parameter> parameter is unsafe)</para><para>Passed as <code>len</code></para></td></tr><tr><td class="parameter_name"><para>bytes_read</para></td><td class="parameter_description"><para>location to store the number of bytes in the
                input string that were successfully converted, or <constant>NULL</constant>.
                Even if the conversion was successful, this may be
                less than <parameter>len</parameter> if there were partial characters
                at the end of the input. If the error
                <constant>G_CONVERT_ERROR_ILLEGAL_SEQUENCE</constant> occurs, the value
                stored will be the byte offset after the last valid
                input sequence.</para><para>Passed as <code>bytes-read</code></para></td></tr><tr><td class="parameter_name"><para>bytes_written</para></td><td class="parameter_description"><para>the number of bytes stored in the output
                buffer (not including the terminating nul).</para><para>Passed as <code>bytes-written</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>find-program-in-path</title><informalexample><programlisting>(define-values (%return) (find-program-in-path program))
</programlisting></informalexample><para>Locates the first executable named <parameter>program</parameter> in the user's path, in the
same way that <function>execvp()</function> would locate it. Returns an allocated string
with the absolute path name, or <constant>NULL</constant> if the program is not found in
the path. If <parameter>program</parameter> is already an absolute path, returns a copy of
<parameter>program</parameter> if <parameter>program</parameter> exists and is executable, and <constant>NULL</constant> otherwise.
 
On Windows, if <parameter>program</parameter> does not have a file type suffix, tries
with the suffixes .exe, .cmd, .bat and .com, and the suffixes in
the <code>PATHEXT</code> environment variable.
</para>
<para>On Windows, it looks for the file in the same way as <function>CreateProcess()</function>
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 <code>PATH</code> environment variable. If
the program is found, the return value contains the full name
including the type suffix.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>program</para></td><td class="parameter_description"><para>a program name in the GLib file name encoding</para><para>Passed as <code>program</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>format-size</title><informalexample><programlisting>(define-values (%return) (format-size size))
</programlisting></informalexample><para>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 &quot;3.2 MB&quot;. 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.
</para>
<para>The prefix units base is 1000 (i.e. 1 kB is 1000 bytes).
</para>
<para>This string should be freed with <function>g_free()</function> when not needed any longer.
</para>
<para>See <function>g_format_size_full()</function> for more options about how the size might be
formatted.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>size</para></td><td class="parameter_description"><para>a size in bytes</para><para>Passed as <code>size</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>format-size-full</title><informalexample><programlisting>(define-values (%return) (format-size-full size flags))
</programlisting></informalexample><para>Formats a size.
</para>
<para>This function is similar to <function>g_format_size()</function> but allows for flags
that modify the output. See <type>GFormatSizeFlags</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>size</para></td><td class="parameter_description"><para>a size in bytes</para><para>Passed as <code>size</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para><type>GFormatSizeFlags</type> to modify the output</para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-application-name</title><informalexample><programlisting>(define-values (%return) (get-application-name))
</programlisting></informalexample><para>Gets a human-readable name for the application, as set by
<function>g_set_application_name()</function>. This name should be localized if
possible, and is intended for display to the user.  Contrast with
<function>g_get_prgname()</function>, which gets a non-localized name. If
<function>g_set_application_name()</function> has not been called, returns the result of
<function>g_get_prgname()</function> (which may be <constant>NULL</constant> if <function>g_set_prgname()</function> has also not
been called).</para></refsect2><refsect2><title>get-charset</title><informalexample><programlisting>(define-values (%return charset) (get-charset))
</programlisting></informalexample><para>Obtains the character set for the [current locale][setlocale]; you
might use this character set as an argument to <function>g_convert()</function>, to convert
from the current locale's encoding to some other encoding. (Frequently
<function>g_locale_to_utf8()</function> and <function>g_locale_from_utf8()</function> are nice shortcuts, though.)
</para>
<para>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 &quot;narrow&quot; versions of C library and Win32 functions that
handle file names. It might be different from the character set
used by the C library's current locale.
</para>
<para>On Linux, the character set is found by consulting <function>nl_langinfo()</function> if
available. If not, the environment variables <code>LC_ALL</code>, <code>LC_CTYPE</code>, <code>LANG</code>
and <code>CHARSET</code> are queried in order.
</para>
<para>The return value is <constant>TRUE</constant> if the locale's encoding is UTF-8, in that
case you can perhaps avoid calling <function>g_convert()</function>.
</para>
<para>The string returned in <parameter>charset</parameter> is not allocated, and should not be
freed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>charset</para></td><td class="parameter_description"><para>return location for character set
  name, or <constant>NULL</constant>.</para><para>Passed as <code>charset</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-codeset</title><informalexample><programlisting>(define-values (%return) (get-codeset))
</programlisting></informalexample><para>Gets the character set for the current locale.</para></refsect2><refsect2><title>get-console-charset</title><informalexample><programlisting>(define-values (%return charset) (get-console-charset))
</programlisting></informalexample><para>Obtains the character set used by the console attached to the process,
which is suitable for printing output to the terminal.
</para>
<para>Usually this matches the result returned by <function>g_get_charset()</function>, 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.
</para>
<para>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.
</para>
<para>The return value is <constant>TRUE</constant> if the locale's encoding is UTF-8, in that
case you can perhaps avoid calling <function>g_convert()</function>.
</para>
<para>The string returned in <parameter>charset</parameter> is not allocated, and should not be
freed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>charset</para></td><td class="parameter_description"><para>return location for character set
  name, or <constant>NULL</constant>.</para><para>Passed as <code>charset</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-current-dir</title><informalexample><programlisting>(define-values (%return) (get-current-dir))
</programlisting></informalexample><para>Gets the current directory.
</para>
<para>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.
</para>
<para>Since GLib 2.40, this function will return the value of the &quot;PWD&quot;
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.</para></refsect2><refsect2><title>get-environ</title><informalexample><programlisting>(define-values (%return) (get-environ))
</programlisting></informalexample><para>Gets the list of environment variables for the current process.
</para>
<para>The list is <constant>NULL</constant> terminated and each item in the list is of the
form 'NAME=VALUE'.
</para>
<para>This is equivalent to direct access to the 'environ' global variable,
except portable.
</para>
<para>The return value is freshly allocated and it should be freed with
<function>g_strfreev()</function> when it is no longer needed.</para></refsect2><refsect2><title>get-filename-charsets</title><informalexample><programlisting>(define-values (%return filename-charsets) (get-filename-charsets))
</programlisting></informalexample><para>Determines the preferred character sets used for filenames.
The first character set from the <parameter>charsets</parameter> is the filename encoding, the
subsequent character sets are used when trying to generate a displayable
representation of a filename, see <function>g_filename_display_name()</function>.
</para>
<para>On Unix, the character sets are determined by consulting the
environment variables <code>G_FILENAME_ENCODING</code> and <code>G_BROKEN_FILENAMES</code>.
On Windows, the character set used in the GLib API is always UTF-8
and said environment variables have no effect.
</para>
<para><code>G_FILENAME_ENCODING</code> may be set to a comma-separated list of
character set names. The special token &quot;\@locale&quot; is taken
to  mean the character set for the [current locale][setlocale].
If <code>G_FILENAME_ENCODING</code> is not set, but <code>G_BROKEN_FILENAMES</code> 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.
</para>
<para>The returned <parameter>charsets</parameter> belong to GLib and must not be freed.
</para>
<para>Note that on Unix, regardless of the locale character set or
<code>G_FILENAME_ENCODING</code> value, the actual file names present
on a system might be in any random encoding or just gibberish.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>filename_charsets</para></td><td class="parameter_description"><para>
   <para>return location for the <constant>NULL</constant>-terminated list of encoding names</para></para><para>Passed as <code>filename-charsets</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-home-dir</title><informalexample><programlisting>(define-values (%return) (get-home-dir))
</programlisting></informalexample><para>Gets the current user's home directory.
</para>
<para>As with most UNIX tools, this function will return the value of the
<code>HOME</code> environment variable if it is set to an existing absolute path
name, falling back to the <code>passwd</code> file in the case that it is unset.
</para>
<para>If the path given in <code>HOME</code> is non-absolute, does not exist, or is
not a directory, the result is undefined.
</para>
<para>Before version 2.36 this function would ignore the <code>HOME</code> environment
variable, taking the value from the <code>passwd</code> 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).
</para>
<para>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 <code>HOME</code> environment variable yourself
or unset it before calling any functions in GLib.</para></refsect2><refsect2><title>get-host-name</title><informalexample><programlisting>(define-values (%return) (get-host-name))
</programlisting></informalexample><para>Return a name for the machine.
</para>
<para>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 &quot;localhost&quot; is
returned.
</para>
<para>The encoding of the returned string is UTF-8.</para></refsect2><refsect2><title>get-language-names</title><informalexample><programlisting>(define-values (%return) (get-language-names))
</programlisting></informalexample><para>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 &quot;C&quot;.
</para>
<para>For example, if LANGUAGE=de:en_US, then the returned list is
&quot;de&quot;, &quot;en_US&quot;, &quot;en&quot;, &quot;C&quot;.
</para>
<para>This function consults the environment variables <code>LANGUAGE</code>, <code>LC_ALL</code>,
<code>LC_MESSAGES</code> and <code>LANG</code> to find the list of locales specified by the
user.</para></refsect2><refsect2><title>get-language-names-with-category</title><informalexample><programlisting>(define-values (%return) (get-language-names-with-category category-name))
</programlisting></informalexample><para>Computes a list of applicable locale names with a locale category name,
which can be used to construct the fallback locale-dependent filenames
or search paths. The returned list is sorted from most desirable to
least desirable and always contains the default locale &quot;C&quot;.
</para>
<para>This function consults the environment variables <code>LANGUAGE</code>, <code>LC_ALL</code>,
<parameter>category_name</parameter>, and <code>LANG</code> to find the list of locales specified by the
user.
</para>
<para><function>g_get_language_names()</function> returns g_get_language_names_with_category(&quot;LC_MESSAGES&quot;).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>category_name</para></td><td class="parameter_description"><para>a locale category name</para><para>Passed as <code>category-name</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-locale-variants</title><informalexample><programlisting>(define-values (%return) (get-locale-variants locale))
</programlisting></informalexample><para>Returns a list of derived variants of <parameter>locale</parameter>, 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
[<code>setlocale(3)</code>](man:setlocale) for information about locales and their format.
</para>
<para><parameter>locale</parameter> itself is guaranteed to be returned in the output.
</para>
<para>For example, if <parameter>locale</parameter> is <code>fr_BE</code>, then the returned list
is <code>fr_BE</code>, <code>fr</code>. If <parameter>locale</parameter> is <code>en_GB.UTF-8@euro</code>, then the returned list
is <code>en_GB.UTF-8@euro</code>, <code>en_GB.UTF-8</code>, <code>en_GB@euro</code>, <code>en_GB</code>, <code>en.UTF-8@euro</code>,
<code>en.UTF-8</code>, <code>en@euro</code>, <code>en</code>.
</para>
<para>If you need the list of variants for the current locale,
use <function>g_get_language_names()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>locale</para></td><td class="parameter_description"><para>a locale identifier</para><para>Passed as <code>locale</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-monotonic-time</title><informalexample><programlisting>(define-values (%return) (get-monotonic-time))
</programlisting></informalexample><para>Queries the system monotonic time.
</para>
<para>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.
</para>
<para>We try to use the clock that corresponds as closely as possible to
the passage of time as measured by system calls such as <function>poll()</function> but it
may not always be possible to do this.</para></refsect2><refsect2><title>get-num-processors</title><informalexample><programlisting>(define-values (%return) (get-num-processors))
</programlisting></informalexample><para>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 <function>g_thread_pool_new()</function> for CPU bound tasks and
similar cases.</para></refsect2><refsect2><title>get-os-info</title><informalexample><programlisting>(define-values (%return) (get-os-info key-name))
</programlisting></informalexample><para>Get information about the operating system.
</para>
<para>On Linux this comes from the <code>/etc/os-release</code> file. On other systems, it may
come from a variety of sources. You can either use the standard key names
like <constant>G_OS_INFO_KEY_NAME</constant> or pass any UTF-8 string key name. For example,
<code>/etc/os-release</code> 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 <constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>key_name</para></td><td class="parameter_description"><para>a key for the OS info being requested, for example <constant>G_OS_INFO_KEY_NAME</constant>.</para><para>Passed as <code>key-name</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>get-prgname</title><informalexample><programlisting>(define-values (%return) (get-prgname))
</programlisting></informalexample><para>Gets the name of the program. This name should not be localized,
in contrast to <function>g_get_application_name()</function>.
</para>
<para>If you are using <type>GApplication</type> the program name is set in
<function>g_application_run()</function>. In case of GDK or GTK+ it is set in
<function>gdk_init()</function>, which is called by <function>gtk_init()</function> and the
<type>“startup”</type> handler. The program name is found by
taking the last component of <parameter>argv</parameter>[0].</para></refsect2><refsect2><title>get-real-name</title><informalexample><programlisting>(define-values (%return) (get-real-name))
</programlisting></informalexample><para>Gets the real name of the user. This usually comes from the user's
entry in the <code>passwd</code> 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 &quot;Unknown&quot; is
returned.</para></refsect2><refsect2><title>get-real-time</title><informalexample><programlisting>(define-values (%return) (get-real-time))
</programlisting></informalexample><para>Queries the system wall-clock time.
</para>
<para>This call is functionally equivalent to <function>g_get_current_time()</function> except
that the return value is often more convenient than dealing with a
<type>GTimeVal</type>.
</para>
<para>You should only use this call if you are actually interested in the real
wall-clock time.  <function>g_get_monotonic_time()</function> is probably more useful for
measuring intervals.</para></refsect2><refsect2><title>get-system-config-dirs</title><informalexample><programlisting>(define-values (%return) (get-system-config-dirs))
</programlisting></informalexample><para>Returns an ordered list of base directories in which to access
system-wide configuration information.
</para>
<para>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 <code>XDG_CONFIG_DIRS</code>.
</para>
<para>On Windows it follows XDG Base Directory Specification if <code>XDG_CONFIG_DIRS</code> is defined.
If <code>XDG_CONFIG_DIRS</code> is undefined, the directory that contains application
data for all users is used instead. A typical path is
<code>C:\Documents and Settings\All Users\Application Data</code>.
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.</para></refsect2><refsect2><title>get-system-data-dirs</title><informalexample><programlisting>(define-values (%return) (get-system-data-dirs))
</programlisting></informalexample><para>Returns an ordered list of base directories in which to access
system-wide application data.
</para>
<para>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 <code>XDG_DATA_DIRS</code>.
</para>
<para>On Windows it follows XDG Base Directory Specification if <code>XDG_DATA_DIRS</code> is defined.
If <code>XDG_DATA_DIRS</code> 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.
</para>
<para>Then follows the &quot;share&quot; subfolder in the installation folder for
the package containing the DLL that calls this function, if it can
be determined.
</para>
<para>Finally the list contains the &quot;share&quot; subfolder in the installation
folder for GLib, and in the installation folder for the package the
application's .exe file belongs to.
</para>
<para>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 &quot;bin&quot;, its parent is used, otherwise the folder
itself.
</para>
<para>Note that on Windows the returned list can vary depending on where
this function is called.</para></refsect2><refsect2><title>get-tmp-dir</title><informalexample><programlisting>(define-values (%return) (get-tmp-dir))
</programlisting></informalexample><para>Gets the directory to use for temporary files.
</para>
<para>On UNIX, this is taken from the <code>TMPDIR</code> environment variable.
If the variable is not set, <code>P_tmpdir</code> is
used, as defined by the system C library. Failing that, a
hard-coded default of &quot;/tmp&quot; is returned.
</para>
<para>On Windows, the <code>TEMP</code> environment variable is used, with the
root directory of the Windows installation (eg: &quot;C:\&quot;) used
as a default.
</para>
<para>The encoding of the returned string is system-defined. On Windows,
it is always UTF-8. The return value is never <constant>NULL</constant> or the empty
string.</para></refsect2><refsect2><title>get-user-cache-dir</title><informalexample><programlisting>(define-values (%return) (get-user-cache-dir))
</programlisting></informalexample><para>Returns a base directory in which to store non-essential, cached
data specific to particular user.
</para>
<para>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 <code>XDG_CACHE_HOME</code>.
</para>
<para>On Windows it follows XDG Base Directory Specification if <code>XDG_CACHE_HOME</code> is defined.
If <code>XDG_CACHE_HOME</code> is undefined, the directory that serves as a common
repository for temporary Internet files is used instead. A typical path is
<code>C:\Documents and Settings\username\Local Settings\Temporary Internet Files</code>.
See the [documentation for <code>CSIDL_INTERNET_CACHE</code>](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_internet_cache).</para></refsect2><refsect2><title>get-user-config-dir</title><informalexample><programlisting>(define-values (%return) (get-user-config-dir))
</programlisting></informalexample><para>Returns a base directory in which to store user-specific application
configuration information such as user preferences and settings.
</para>
<para>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 <code>XDG_CONFIG_HOME</code>.
</para>
<para>On Windows it follows XDG Base Directory Specification if <code>XDG_CONFIG_HOME</code> is defined.
If <code>XDG_CONFIG_HOME</code> is undefined, the folder to use for local (as opposed
to roaming) application data is used instead. See the
[documentation for <code>CSIDL_LOCAL_APPDATA</code>](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 <function>g_get_user_data_dir()</function> returns.</para></refsect2><refsect2><title>get-user-data-dir</title><informalexample><programlisting>(define-values (%return) (get-user-data-dir))
</programlisting></informalexample><para>Returns a base directory in which to access application data such
as icons that is customized for a particular user.
</para>
<para>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 <code>XDG_DATA_HOME</code>.
</para>
<para>On Windows it follows XDG Base Directory Specification if <code>XDG_DATA_HOME</code>
is defined. If <code>XDG_DATA_HOME</code> is undefined, the folder to use for local (as
opposed to roaming) application data is used instead. See the
[documentation for <code>CSIDL_LOCAL_APPDATA</code>](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 <function>g_get_user_config_dir()</function> returns.</para></refsect2><refsect2><title>get-user-name</title><informalexample><programlisting>(define-values (%return) (get-user-name))
</programlisting></informalexample><para>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.</para></refsect2><refsect2><title>get-user-runtime-dir</title><informalexample><programlisting>(define-values (%return) (get-user-runtime-dir))
</programlisting></informalexample><para>Returns a directory that is unique to the current user on the local
system.
</para>
<para>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 <code>XDG_RUNTIME_DIR</code> environment variable.
In the case that this variable is not set, we return the value of
<function>g_get_user_cache_dir()</function>, after verifying that it exists.</para></refsect2><refsect2><title>get-user-special-dir</title><informalexample><programlisting>(define-values (%return) (get-user-special-dir directory))
</programlisting></informalexample><para>Returns the full path of a special directory using its logical id.
</para>
<para>On UNIX this is done using the XDG special user directories.
For compatibility with existing practise, <constant>G_USER_DIRECTORY_DESKTOP</constant>
falls back to <code>$HOME/Desktop</code> when XDG special user directories have
not been set up.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>directory</para></td><td class="parameter_description"><para>the logical id of special directory</para><para>Passed as <code>directory</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>getenv</title><informalexample><programlisting>(define-values (%return) (getenv variable))
</programlisting></informalexample><para>Returns the value of an environment variable.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>variable</para></td><td class="parameter_description"><para>the environment variable to get</para><para>Passed as <code>variable</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table-add?</title><informalexample><programlisting>(define-values (%return) (hash-table-add? hash-table key))
</programlisting></informalexample><para>This is a convenience function for using a <type>GHashTable</type> as a set.  It
is equivalent to calling <function>g_hash_table_replace()</function> with <parameter>key</parameter> as both the
key and the value.
</para>
<para>In particular, this means that if <parameter>key</parameter> already exists in the hash table, then
the old copy of <parameter>key</parameter> in the hash table is freed and <parameter>key</parameter> replaces it in the
table.
</para>
<para>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.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key to insert</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table-contains?</title><informalexample><programlisting>(define-values (%return) (hash-table-contains? hash-table key))
</programlisting></informalexample><para>Checks if <parameter>key</parameter> is in <parameter>hash_table</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key to check</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table-destroy</title><informalexample><programlisting>(define-values () (hash-table-destroy hash-table))
</programlisting></informalexample><para>Destroys all keys and values in the <type>GHashTable</type> and decrements its
reference count by 1. If keys and/or values are dynamically allocated,
you should either free them first or create the <type>GHashTable</type> with destroy
notifiers using <function>g_hash_table_new_full()</function>. In the latter case the destroy
functions you supplied will be called on all keys and values during the
destruction phase.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table-insert?</title><informalexample><programlisting>(define-values (%return) (hash-table-insert? hash-table key value))
</programlisting></informalexample><para>Inserts a new key and value into a <type>GHashTable</type>.
</para>
<para>If the key already exists in the <type>GHashTable</type> its current
value is replaced with the new value. If you supplied a
<parameter>value_destroy_func</parameter> when creating the <type>GHashTable</type>, the old
value is freed using that function. If you supplied a
<parameter>key_destroy_func</parameter> when creating the <type>GHashTable</type>, the passed
key is freed using that function.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key to insert</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>the value to associate with the key</para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table-lookup</title><informalexample><programlisting>(define-values (%return) (hash-table-lookup hash-table key))
</programlisting></informalexample><para>Looks up a key in a <type>GHashTable</type>. Note that this function cannot
distinguish between a key that is not present and one which is present
and has the value <constant>NULL</constant>. If you need this distinction, use
<function>g_hash_table_lookup_extended()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to look up</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table-lookup-extended</title><informalexample><programlisting>(define-values
  (%return orig-key value)
  (hash-table-lookup-extended hash-table lookup-key))
</programlisting></informalexample><para>Looks up a key in the <type>GHashTable</type>, returning the original key and the
associated value and a <type>gboolean</type> which is <constant>TRUE</constant> if the key was found. This
is useful if you need to free the memory allocated for the original key,
for example before calling <function>g_hash_table_remove()</function>.
</para>
<para>You can actually pass <constant>NULL</constant> for <parameter>lookup_key</parameter> to test
whether the <constant>NULL</constant> key exists, provided the hash and equal functions
of <parameter>hash_table</parameter> are <constant>NULL</constant>-safe.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>lookup_key</para></td><td class="parameter_description"><para>the key to look up</para><para>Passed as <code>lookup-key</code></para></td></tr><tr><td class="parameter_name"><para>orig_key</para></td><td class="parameter_description"><para>return location for the original key</para><para>Passed as <code>orig-key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>return location for the value associated
with the key</para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table-remove?</title><informalexample><programlisting>(define-values (%return) (hash-table-remove? hash-table key))
</programlisting></informalexample><para>Removes a key and its associated value from a <type>GHashTable</type>.
</para>
<para>If the <type>GHashTable</type> was created using <function>g_hash_table_new_full()</function>, 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to remove</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table-remove-all</title><informalexample><programlisting>(define-values () (hash-table-remove-all hash-table))
</programlisting></informalexample><para>Removes all keys and their associated values from a <type>GHashTable</type>.
</para>
<para>If the <type>GHashTable</type> was created using <function>g_hash_table_new_full()</function>,
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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table-replace?</title><informalexample><programlisting>(define-values (%return) (hash-table-replace? hash-table key value))
</programlisting></informalexample><para>Inserts a new key and value into a <type>GHashTable</type> similar to
<function>g_hash_table_insert()</function>. The difference is that if the key
already exists in the <type>GHashTable</type>, it gets replaced by the
new key. If you supplied a <parameter>value_destroy_func</parameter> when creating
the <type>GHashTable</type>, the old value is freed using that function.
If you supplied a <parameter>key_destroy_func</parameter> when creating the
<type>GHashTable</type>, the old key is freed using that function.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>a key to insert</para><para>Passed as <code>key</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>the value to associate with the key</para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table-size</title><informalexample><programlisting>(define-values (%return) (hash-table-size hash-table))
</programlisting></informalexample><para>Returns the number of elements contained in the <type>GHashTable</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table-steal?</title><informalexample><programlisting>(define-values (%return) (hash-table-steal? hash-table key))
</programlisting></informalexample><para>Removes a key and its associated value from a <type>GHashTable</type> without
calling the key and value destroy functions.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>key</para></td><td class="parameter_description"><para>the key to remove</para><para>Passed as <code>key</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table-steal-all</title><informalexample><programlisting>(define-values () (hash-table-steal-all hash-table))
</programlisting></informalexample><para>Removes all keys and their associated values from a <type>GHashTable</type>
without calling the key and value destroy functions.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table-steal-extended</title><informalexample><programlisting>(define-values
  (%return stolen-key stolen-value)
  (hash-table-steal-extended hash-table lookup-key))
</programlisting></informalexample><para>Looks up a key in the <type>GHashTable</type>, stealing the original key and the
associated value and returning <constant>TRUE</constant> if the key was found. If the key was
not found, <constant>FALSE</constant> is returned.
</para>
<para>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 <function>g_hash_table_steal()</function>.
</para>
<para>You can pass <constant>NULL</constant> for <parameter>lookup_key</parameter>, provided the hash and equal functions
of <parameter>hash_table</parameter> are <constant>NULL</constant>-safe.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr><tr><td class="parameter_name"><para>lookup_key</para></td><td class="parameter_description"><para>the key to look up</para><para>Passed as <code>lookup-key</code></para></td></tr><tr><td class="parameter_name"><para>stolen_key</para></td><td class="parameter_description"><para>return location for the
   original key</para><para>Passed as <code>stolen-key</code></para></td></tr><tr><td class="parameter_name"><para>stolen_value</para></td><td class="parameter_description"><para>return location
   for the value associated with the key</para><para>Passed as <code>stolen-value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hash-table-unref</title><informalexample><programlisting>(define-values () (hash-table-unref hash-table))
</programlisting></informalexample><para>Atomically decrements the reference count of <parameter>hash_table</parameter> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hash_table</para></td><td class="parameter_description"><para>a valid <type>GHashTable</type></para><para>Passed as <code>hash-table</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hostname-is-ascii-encoded?</title><informalexample><programlisting>(define-values (%return) (hostname-is-ascii-encoded? hostname))
</programlisting></informalexample><para>Tests if <parameter>hostname</parameter> contains segments with an ASCII-compatible
encoding of an Internationalized Domain Name. If this returns
<constant>TRUE</constant>, you should decode the hostname with <function>g_hostname_to_unicode()</function>
before displaying it to the user.
</para>
<para>Note that a hostname might contain a mix of encoded and unencoded
segments, and so it is possible for <function>g_hostname_is_non_ascii()</function> and
<function>g_hostname_is_ascii_encoded()</function> to both return <constant>TRUE</constant> for a name.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hostname</para></td><td class="parameter_description"><para>a hostname</para><para>Passed as <code>hostname</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hostname-is-ip-address?</title><informalexample><programlisting>(define-values (%return) (hostname-is-ip-address? hostname))
</programlisting></informalexample><para>Tests if <parameter>hostname</parameter> is the string form of an IPv4 or IPv6 address.
(Eg, &quot;192.168.0.1&quot;.)
</para>
<para>Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hostname</para></td><td class="parameter_description"><para>a hostname (or IP address in string form)</para><para>Passed as <code>hostname</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hostname-is-non-ascii?</title><informalexample><programlisting>(define-values (%return) (hostname-is-non-ascii? hostname))
</programlisting></informalexample><para>Tests if <parameter>hostname</parameter> contains Unicode characters. If this returns
<constant>TRUE</constant>, you need to encode the hostname with <function>g_hostname_to_ascii()</function>
before using it in non-IDN-aware contexts.
</para>
<para>Note that a hostname might contain a mix of encoded and unencoded
segments, and so it is possible for <function>g_hostname_is_non_ascii()</function> and
<function>g_hostname_is_ascii_encoded()</function> to both return <constant>TRUE</constant> for a name.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hostname</para></td><td class="parameter_description"><para>a hostname</para><para>Passed as <code>hostname</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hostname-to-ascii</title><informalexample><programlisting>(define-values (%return) (hostname-to-ascii hostname))
</programlisting></informalexample><para>Converts <parameter>hostname</parameter> to its canonical ASCII form; an ASCII-only
string containing no uppercase letters and not ending with a
trailing dot.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hostname</para></td><td class="parameter_description"><para>a valid UTF-8 or ASCII hostname</para><para>Passed as <code>hostname</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>hostname-to-unicode</title><informalexample><programlisting>(define-values (%return) (hostname-to-unicode hostname))
</programlisting></informalexample><para>Converts <parameter>hostname</parameter> 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.
</para>
<para>Of course if <parameter>hostname</parameter> is not an internationalized hostname, then
the canonical presentation form will be entirely ASCII.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>hostname</para></td><td class="parameter_description"><para>a valid UTF-8 or ASCII hostname</para><para>Passed as <code>hostname</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>idle-add</title><informalexample><programlisting>(define-values (%return) (idle-add priority function data notify))
</programlisting></informalexample><para>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, <type>G_PRIORITY_DEFAULT_IDLE</type>.  If the function
returns <constant>FALSE</constant> it is automatically removed from the list of event
sources and will not be called again.
</para>
<para>See [memory management of sources][mainloop-memory-management] for details
on how to handle the return value and memory management of <parameter>data</parameter>.
</para>
<para>This internally creates a main loop source using <function>g_idle_source_new()</function>
and attaches it to the global <type>GMainContext</type> using <function>g_source_attach()</function>, 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>notify</para></td><td class="parameter_description"><para></para><para>Passed as <code>notify</code></para></td></tr><tr><td class="parameter_name"><para>priority</para></td><td class="parameter_description"><para></para><para>Passed as <code>priority</code></para></td></tr><tr><td class="parameter_name"><para>function</para></td><td class="parameter_description"><para>function to call</para><para>Passed as <code>function</code></para></td></tr><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>data to pass to <parameter>function</parameter>.</para><para>Passed as <code>data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>idle-remove-by-data?</title><informalexample><programlisting>(define-values (%return) (idle-remove-by-data? data))
</programlisting></informalexample><para>Removes the idle function with the given data.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>the data for the idle source's callback.</para><para>Passed as <code>data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>idle-source-new</title><informalexample><programlisting>(define-values (%return) (idle-source-new))
</programlisting></informalexample><para>Creates a new idle source.
</para>
<para>The source will not initially be associated with any <type>GMainContext</type>
and must be added to one with <function>g_source_attach()</function> before it will be
executed. Note that the default priority for idle sources is
<constant>G_PRIORITY_DEFAULT_IDLE</constant>, as compared to other sources which
have a default priority of <constant>G_PRIORITY_DEFAULT</constant>.</para></refsect2><refsect2><title>int64-equal?</title><informalexample><programlisting>(define-values (%return) (int64-equal? v1 v2))
</programlisting></informalexample><para>Compares the two <type>gint64</type> values being pointed to and returns
<constant>TRUE</constant> if they are equal.
It can be passed to <function>g_hash_table_new()</function> as the <parameter>key_equal_func</parameter>
parameter, when using non-<constant>NULL</constant> pointers to 64-bit integers as keys in a
<type>GHashTable</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>v1</para></td><td class="parameter_description"><para>a pointer to a <type>gint64</type> key</para><para>Passed as <code>v1</code></para></td></tr><tr><td class="parameter_name"><para>v2</para></td><td class="parameter_description"><para>a pointer to a <type>gint64</type> key to compare with <parameter>v1</parameter></para><para>Passed as <code>v2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>int64-hash</title><informalexample><programlisting>(define-values (%return) (int64-hash v))
</programlisting></informalexample><para>Converts a pointer to a <type>gint64</type> to a hash value.
</para>
<para>It can be passed to <function>g_hash_table_new()</function> as the <parameter>hash_func</parameter> parameter,
when using non-<constant>NULL</constant> pointers to 64-bit integer values as keys in a
<type>GHashTable</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>v</para></td><td class="parameter_description"><para>a pointer to a <type>gint64</type> key</para><para>Passed as <code>v</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>int-equal?</title><informalexample><programlisting>(define-values (%return) (int-equal? v1 v2))
</programlisting></informalexample><para>Compares the two <type>gint</type> values being pointed to and returns
<constant>TRUE</constant> if they are equal.
It can be passed to <function>g_hash_table_new()</function> as the <parameter>key_equal_func</parameter>
parameter, when using non-<constant>NULL</constant> pointers to integers as keys in a
<type>GHashTable</type>.
</para>
<para>Note that this function acts on pointers to <type>gint</type>, not on <type>gint</type>
directly: if your hash table's keys are of the form
<code>GINT_TO_POINTER (n)</code>, use <function>g_direct_equal()</function> instead.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>v1</para></td><td class="parameter_description"><para>a pointer to a <type>gint</type> key</para><para>Passed as <code>v1</code></para></td></tr><tr><td class="parameter_name"><para>v2</para></td><td class="parameter_description"><para>a pointer to a <type>gint</type> key to compare with <parameter>v1</parameter></para><para>Passed as <code>v2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>int-hash</title><informalexample><programlisting>(define-values (%return) (int-hash v))
</programlisting></informalexample><para>Converts a pointer to a <type>gint</type> to a hash value.
It can be passed to <function>g_hash_table_new()</function> as the <parameter>hash_func</parameter> parameter,
when using non-<constant>NULL</constant> pointers to integer values as keys in a <type>GHashTable</type>.
</para>
<para>Note that this function acts on pointers to <type>gint</type>, not on <type>gint</type>
directly: if your hash table's keys are of the form
<code>GINT_TO_POINTER (n)</code>, use <function>g_direct_hash()</function> instead.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>v</para></td><td class="parameter_description"><para>a pointer to a <type>gint</type> key</para><para>Passed as <code>v</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>intern-static-string</title><informalexample><programlisting>(define-values (%return) (intern-static-string string))
</programlisting></informalexample><para>Returns a canonical representation for <parameter>string</parameter>. Interned strings
can be compared for equality by comparing the pointers, instead of
using <function>strcmp()</function>. <function>g_intern_static_string()</function> does not copy the string,
therefore <parameter>string</parameter> must not be freed or modified.
</para>
<para>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++.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a static string</para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>intern-string</title><informalexample><programlisting>(define-values (%return) (intern-string string))
</programlisting></informalexample><para>Returns a canonical representation for <parameter>string</parameter>. Interned strings
can be compared for equality by comparing the pointers, instead of
using <function>strcmp()</function>.
</para>
<para>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++.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>io-add-watch</title><informalexample><programlisting>(define-values
  (%return)
  (io-add-watch channel priority condition func user-data notify))
</programlisting></informalexample><para>Adds the <type>GIOChannel</type> into the default main loop context
with the default priority.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>notify</para></td><td class="parameter_description"><para></para><para>Passed as <code>notify</code></para></td></tr><tr><td class="parameter_name"><para>priority</para></td><td class="parameter_description"><para></para><para>Passed as <code>priority</code></para></td></tr><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type></para><para>Passed as <code>channel</code></para></td></tr><tr><td class="parameter_name"><para>condition</para></td><td class="parameter_description"><para>the condition to watch for</para><para>Passed as <code>condition</code></para></td></tr><tr><td class="parameter_name"><para>func</para></td><td class="parameter_description"><para>the function to call when the condition is satisfied</para><para>Passed as <code>func</code></para></td></tr><tr><td class="parameter_name"><para>user_data</para></td><td class="parameter_description"><para>user data to pass to <parameter>func</parameter></para><para>Passed as <code>user-data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>io-channel-error-from-errno</title><informalexample><programlisting>(define-values (%return) (io-channel-error-from-errno en))
</programlisting></informalexample><para>Converts an <code>errno</code> error number to a <type>GIOChannelError</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>en</para></td><td class="parameter_description"><para>an <code>errno</code> error number, e.g. <code>EINVAL</code></para><para>Passed as <code>en</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>io-channel-error-quark</title><informalexample><programlisting>(define-values (%return) (io-channel-error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>io-create-watch</title><informalexample><programlisting>(define-values (%return) (io-create-watch channel condition))
</programlisting></informalexample><para>Creates a <type>GSource</type> that's dispatched when <parameter>condition</parameter> is met for the
given <parameter>channel</parameter>. For example, if condition is <type>G_IO_IN</type>, the source will
be dispatched when there's data available for reading.
</para>
<para>The callback function invoked by the <type>GSource</type> should be added with
<function>g_source_set_callback()</function>, but it has type <type>GIOFunc</type> (not <type>GSourceFunc</type>).
</para>
<para><function>g_io_add_watch()</function> 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.
</para>
<para>On Windows, polling a <type>GSource</type> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>channel</para></td><td class="parameter_description"><para>a <type>GIOChannel</type> to watch</para><para>Passed as <code>channel</code></para></td></tr><tr><td class="parameter_name"><para>condition</para></td><td class="parameter_description"><para>conditions to watch for</para><para>Passed as <code>condition</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>key-file-error-quark</title><informalexample><programlisting>(define-values (%return) (key-file-error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>listenv</title><informalexample><programlisting>(define-values (%return) (listenv))
</programlisting></informalexample><para>Gets the names of all variables set in the environment.
</para>
<para>Programs that want to be portable to Windows should typically use
this function and <function>g_getenv()</function> 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 <function>g_getenv()</function> provide.</para></refsect2><refsect2><title>locale-from-utf8</title><informalexample><programlisting>(define-values
  (%return bytes-read bytes-written)
  (locale-from-utf8 utf8string len))
</programlisting></informalexample><para>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.
</para>
<para>The input string shall not contain nul characters even if the <parameter>len</parameter>
argument is positive. A nul character found inside the string will result
in error <constant>G_CONVERT_ERROR_ILLEGAL_SEQUENCE</constant>. Use <function>g_convert()</function> to convert
input that may contain embedded nul characters.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>utf8string</para></td><td class="parameter_description"><para>a UTF-8 encoded string</para><para>Passed as <code>utf8string</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the length of the string, or -1 if the string is
                nul-terminated.</para><para>Passed as <code>len</code></para></td></tr><tr><td class="parameter_name"><para>bytes_read</para></td><td class="parameter_description"><para>location to store the number of bytes in the
                input string that were successfully converted, or <constant>NULL</constant>.
                Even if the conversion was successful, this may be
                less than <parameter>len</parameter> if there were partial characters
                at the end of the input. If the error
                <constant>G_CONVERT_ERROR_ILLEGAL_SEQUENCE</constant> occurs, the value
                stored will be the byte offset after the last valid
                input sequence.</para><para>Passed as <code>bytes-read</code></para></td></tr><tr><td class="parameter_name"><para>bytes_written</para></td><td class="parameter_description"><para>the number of bytes stored in the output
                buffer (not including the terminating nul).</para><para>Inferred from <code>%return</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>locale-to-utf8</title><informalexample><programlisting>(define-values
  (%return bytes-read bytes-written)
  (locale-to-utf8 opsysstring))
</programlisting></informalexample><para>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.
</para>
<para>If the source encoding is not UTF-8 and the conversion output contains a
nul character, the error <constant>G_CONVERT_ERROR_EMBEDDED_NUL</constant> is set and the
function returns <constant>NULL</constant>.
If the source encoding is UTF-8, an embedded nul character is treated with
the <constant>G_CONVERT_ERROR_ILLEGAL_SEQUENCE</constant> error for backward compatibility with
earlier versions of this library. Use <function>g_convert()</function> to produce output that
may contain embedded nul characters.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>opsysstring</para></td><td class="parameter_description"><para>a string in the
                encoding of the current locale. On Windows
                this means the system codepage.</para><para>Passed as <code>opsysstring</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>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 <parameter>len</parameter> parameter is unsafe)</para><para>Inferred from <code>opsysstring</code></para></td></tr><tr><td class="parameter_name"><para>bytes_read</para></td><td class="parameter_description"><para>location to store the number of bytes in the
                input string that were successfully converted, or <constant>NULL</constant>.
                Even if the conversion was successful, this may be
                less than <parameter>len</parameter> if there were partial characters
                at the end of the input. If the error
                <constant>G_CONVERT_ERROR_ILLEGAL_SEQUENCE</constant> occurs, the value
                stored will be the byte offset after the last valid
                input sequence.</para><para>Passed as <code>bytes-read</code></para></td></tr><tr><td class="parameter_name"><para>bytes_written</para></td><td class="parameter_description"><para>the number of bytes stored in the output
                buffer (not including the terminating nul).</para><para>Passed as <code>bytes-written</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>log-default-handler</title><informalexample><programlisting>(define-values
  ()
  (log-default-handler log-domain log-level message unused-data))
</programlisting></informalexample><para>The default log handler set up by GLib; <function>g_log_set_default_handler()</function>
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 <function>G_BREAKPOINT()</function>. It automatically
prints a new-line character after the message, so one does not need to be
manually included in <parameter>message</parameter>.
</para>
<para>The behavior of this log handler can be influenced by a number of
environment variables:
</para>
<para>- <code>G_MESSAGES_PREFIXED</code>: A :-separated list of log levels for which
  messages should be prefixed by the program name and PID of the
  application.
</para>
<para>- <code>G_MESSAGES_DEBUG</code>: A space-separated list of log domains for
  which debug and informational messages are printed. By default
  these messages are not printed.
</para>
<para>stderr is used for levels <constant>G_LOG_LEVEL_ERROR</constant>, <constant>G_LOG_LEVEL_CRITICAL</constant>,
<constant>G_LOG_LEVEL_WARNING</constant> and <constant>G_LOG_LEVEL_MESSAGE</constant>. stdout is used for
the rest.
</para>
<para>This has no effect if structured logging is enabled; see
[Using Structured Logging][using-structured-logging].</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>log_domain</para></td><td class="parameter_description"><para>the log domain of the message, or <constant>NULL</constant> for the
default &quot;&quot; application domain</para><para>Passed as <code>log-domain</code></para></td></tr><tr><td class="parameter_name"><para>log_level</para></td><td class="parameter_description"><para>the level of the message</para><para>Passed as <code>log-level</code></para></td></tr><tr><td class="parameter_name"><para>message</para></td><td class="parameter_description"><para>the message</para><para>Passed as <code>message</code></para></td></tr><tr><td class="parameter_name"><para>unused_data</para></td><td class="parameter_description"><para>data passed from <function>g_log()</function> which is unused</para><para>Passed as <code>unused-data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>log-remove-handler</title><informalexample><programlisting>(define-values () (log-remove-handler log-domain handler-id))
</programlisting></informalexample><para>Removes the log handler.
</para>
<para>This has no effect if structured logging is enabled; see
[Using Structured Logging][using-structured-logging].</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>log_domain</para></td><td class="parameter_description"><para>the log domain</para><para>Passed as <code>log-domain</code></para></td></tr><tr><td class="parameter_name"><para>handler_id</para></td><td class="parameter_description"><para>the id of the handler, which was returned
    in <function>g_log_set_handler()</function></para><para>Passed as <code>handler-id</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>log-set-always-fatal</title><informalexample><programlisting>(define-values (%return) (log-set-always-fatal fatal-mask))
</programlisting></informalexample><para>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.
<constant>G_LOG_LEVEL_ERROR</constant> is always fatal.
</para>
<para>You can also make some message levels fatal at runtime by setting
the <code>G_DEBUG</code> environment variable (see
[Running GLib Applications](glib-running.html)).
</para>
<para>Libraries should not call this function, as it affects all messages logged
by a process, including those from other libraries.
</para>
<para>Structured log messages (using <function>g_log_structured()</function> and
<function>g_log_structured_array()</function>) 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].</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>fatal_mask</para></td><td class="parameter_description"><para>the mask containing bits set for each level
    of error which is to be fatal</para><para>Passed as <code>fatal-mask</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>log-set-fatal-mask</title><informalexample><programlisting>(define-values (%return) (log-set-fatal-mask log-domain fatal-mask))
</programlisting></informalexample><para>Sets the log levels which are fatal in the given domain.
<constant>G_LOG_LEVEL_ERROR</constant> is always fatal.
</para>
<para>This has no effect on structured log messages (using <function>g_log_structured()</function> or
<function>g_log_structured_array()</function>). To change the fatal behaviour for specific log
messages, programs must install a custom log writer function using
<function>g_log_set_writer_func()</function>. See
[Using Structured Logging][using-structured-logging].
</para>
<para>This function is mostly intended to be used with
<constant>G_LOG_LEVEL_CRITICAL</constant>.  You should typically not set
<constant>G_LOG_LEVEL_WARNING</constant>, <constant>G_LOG_LEVEL_MESSAGE</constant>, <constant>G_LOG_LEVEL_INFO</constant> or
<constant>G_LOG_LEVEL_DEBUG</constant> as fatal except inside of test programs.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>log_domain</para></td><td class="parameter_description"><para>the log domain</para><para>Passed as <code>log-domain</code></para></td></tr><tr><td class="parameter_name"><para>fatal_mask</para></td><td class="parameter_description"><para>the new fatal mask</para><para>Passed as <code>fatal-mask</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>log-set-handler</title><informalexample><programlisting>(define-values
  (%return)
  (log-set-handler log-domain log-levels log-func user-data destroy))
</programlisting></informalexample><para>Sets the log handler for a domain and a set of log levels.
To handle fatal and recursive messages the <parameter>log_levels</parameter> parameter
must be combined with the <type>G_LOG_FLAG_FATAL</type> and <type>G_LOG_FLAG_RECURSION</type>
bit flags.
</para>
<para>Note that since the <type>G_LOG_LEVEL_ERROR</type> log level is always fatal, if
you want to set a handler for this log level you must combine it with
<type>G_LOG_FLAG_FATAL</type>.
</para>
<para>This has no effect if structured logging is enabled; see
[Using Structured Logging][using-structured-logging].
</para>
<para>Here is an example for adding a log handler for all warning messages
in the default domain:
<informalexample><programlisting>
g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
                   | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
</programlisting></informalexample></para>

<para>This example adds a log handler for all critical messages from GTK+:
<informalexample><programlisting>
g_log_set_handler (&quot;Gtk&quot;, G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
                   | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
</programlisting></informalexample></para>

<para>This example adds a log handler for all messages from GLib:
<informalexample><programlisting>
g_log_set_handler (&quot;GLib&quot;, G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
                   | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
</programlisting></informalexample></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>destroy</para></td><td class="parameter_description"><para></para><para>Passed as <code>destroy</code></para></td></tr><tr><td class="parameter_name"><para>log_domain</para></td><td class="parameter_description"><para>the log domain, or <constant>NULL</constant> for the default &quot;&quot;
    application domain</para><para>Passed as <code>log-domain</code></para></td></tr><tr><td class="parameter_name"><para>log_levels</para></td><td class="parameter_description"><para>the log levels to apply the log handler for.
    To handle fatal and recursive messages as well, combine
    the log levels with the <type>G_LOG_FLAG_FATAL</type> and
    <type>G_LOG_FLAG_RECURSION</type> bit flags.</para><para>Passed as <code>log-levels</code></para></td></tr><tr><td class="parameter_name"><para>log_func</para></td><td class="parameter_description"><para>the log handler function</para><para>Passed as <code>log-func</code></para></td></tr><tr><td class="parameter_name"><para>user_data</para></td><td class="parameter_description"><para>data passed to the log handler</para><para>Passed as <code>user-data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>log-variant</title><informalexample><programlisting>(define-values () (log-variant log-domain log-level fields))
</programlisting></informalexample><para>Log a message with structured data, accepting the data within a <type>GVariant</type>. This
version is especially useful for use in other languages, via introspection.
</para>
<para>The only mandatory item in the <parameter>fields</parameter> dictionary is the &quot;MESSAGE&quot; which must
contain the text shown to the user.
</para>
<para>The values in the <parameter>fields</parameter> dictionary are likely to be of type String
(<type>G_VARIANT_TYPE_STRING</type>). Array of bytes (<type>G_VARIANT_TYPE_BYTESTRING</type>) 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
<constant>G_MAXSSIZE</constant>. Otherwise it will be truncated to this size. For other types
<function>g_variant_print()</function> will be used to convert the value into a string.
</para>
<para>For more details on its usage and about the parameters, see <function>g_log_structured()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>log_domain</para></td><td class="parameter_description"><para>log domain, usually <constant>G_LOG_DOMAIN</constant></para><para>Passed as <code>log-domain</code></para></td></tr><tr><td class="parameter_name"><para>log_level</para></td><td class="parameter_description"><para>log level, either from <type>GLogLevelFlags</type>, or a user-defined
   level</para><para>Passed as <code>log-level</code></para></td></tr><tr><td class="parameter_name"><para>fields</para></td><td class="parameter_description"><para>a dictionary (<type>GVariant</type> of the type <constant>G_VARIANT_TYPE_VARDICT</constant>)
containing the key-value pairs of message data.</para><para>Passed as <code>fields</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>log-writer-default-set-use-stderr</title><informalexample><programlisting>(define-values () (log-writer-default-set-use-stderr use-stderr))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>use_stderr</para></td><td class="parameter_description"><para></para><para>Passed as <code>use-stderr</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>log-writer-default-would-drop?</title><informalexample><programlisting>(define-values
  (%return)
  (log-writer-default-would-drop? log-level log-domain))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>log_level</para></td><td class="parameter_description"><para></para><para>Passed as <code>log-level</code></para></td></tr><tr><td class="parameter_name"><para>log_domain</para></td><td class="parameter_description"><para></para><para>Passed as <code>log-domain</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>log-writer-is-journald?</title><informalexample><programlisting>(define-values (%return) (log-writer-is-journald? output-fd))
</programlisting></informalexample><para>Check whether the given <parameter>output_fd</parameter> file descriptor is a connection to the
systemd journal, or something else (like a log file or <code>stdout</code> or
<code>stderr</code>).
</para>
<para>Invalid file descriptors are accepted and return <constant>FALSE</constant>, which allows for
the following construct without needing any additional error handling:
<informalexample><programlisting>
  is_journald = g_log_writer_is_journald (fileno (stderr));
</programlisting></informalexample></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>output_fd</para></td><td class="parameter_description"><para>output file descriptor to check</para><para>Passed as <code>output-fd</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>log-writer-supports-color?</title><informalexample><programlisting>(define-values (%return) (log-writer-supports-color? output-fd))
</programlisting></informalexample><para>Check whether the given <parameter>output_fd</parameter> file descriptor supports ANSI color
escape sequences. If so, they can safely be used when formatting log
messages.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>output_fd</para></td><td class="parameter_description"><para>output file descriptor to check</para><para>Passed as <code>output-fd</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>main-context-default</title><informalexample><programlisting>(define-values (%return) (main-context-default))
</programlisting></informalexample><para>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 &quot;main&quot; main loop. See also
<function>g_main_context_get_thread_default()</function>.</para></refsect2><refsect2><title>main-context-get-thread-default</title><informalexample><programlisting>(define-values (%return) (main-context-get-thread-default))
</programlisting></informalexample><para>Gets the thread-default <type>GMainContext</type> 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
<function>g_main_context_ref_thread_default()</function> to get a <type>GMainContext</type> to add
their <type>GSources</type> 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 <constant>NULL</constant> if you are running in the default thread.)
</para>
<para>If you need to hold a reference on the context, use
<function>g_main_context_ref_thread_default()</function> instead.</para></refsect2><refsect2><title>main-context-ref-thread-default</title><informalexample><programlisting>(define-values (%return) (main-context-ref-thread-default))
</programlisting></informalexample><para>Gets the thread-default <type>GMainContext</type> for this thread, as with
<function>g_main_context_get_thread_default()</function>, but also adds a reference to
it with <function>g_main_context_ref()</function>. In addition, unlike
<function>g_main_context_get_thread_default()</function>, if the thread-default context
is the global default context, this will return that <type>GMainContext</type>
(with a ref added to it) rather than returning <constant>NULL</constant>.</para></refsect2><refsect2><title>main-current-source</title><informalexample><programlisting>(define-values (%return) (main-current-source))
</programlisting></informalexample><para>Returns the currently firing source for this thread.</para></refsect2><refsect2><title>main-depth</title><informalexample><programlisting>(define-values (%return) (main-depth))
</programlisting></informalexample><para>Returns the depth of the stack of calls to
<function>g_main_context_dispatch()</function> on any <type>GMainContext</type> in the current thread.
 That is, when called from the toplevel, it gives 0. When
called from within a callback from <function>g_main_context_iteration()</function>
(or <function>g_main_loop_run()</function>, etc.) it returns 1. When called from within
a callback to a recursive call to <function>g_main_context_iteration()</function>,
it returns 2. And so forth.
</para>
<para>This function is useful in a situation like the following:
Imagine an extremely simple &quot;garbage collected&quot; system.
</para>
<para><informalexample><programlisting>
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-&gt;next);
    g_free (l-&gt;data);
  g_list_free (free_list);
  free_list = NULL;
 }

[...]

while (TRUE);
 {
   g_main_context_iteration (NULL, TRUE);
   free_allocated_memory();
  }
</programlisting></informalexample></para>

<para>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 <function>free_allocated_memory()</function>, but that
doesn't work, since the idle function could be called from a
recursive callback. This can be fixed by using <function>g_main_depth()</function>
</para>
<para><informalexample><programlisting>
gpointer
allocate_memory (gsize size)
{
  FreeListBlock *block = g_new (FreeListBlock, 1);
  block-&gt;mem = g_malloc (size);
  block-&gt;depth = g_main_depth ();
  free_list = g_list_prepend (free_list, block);
  return block-&gt;mem;
}

void
free_allocated_memory (void)
{
  GList *l;
  
  int depth = g_main_depth ();
  for (l = free_list; l; );
    {
      GList *next = l-&gt;next;
      FreeListBlock *block = l-&gt;data;
      if (block-&gt;depth &gt; depth)
        {
          g_free (block-&gt;mem);
          g_free (block);
          free_list = g_list_delete_link (free_list, l);
        }
              
      l = next;
    }
  }
</programlisting></informalexample></para>

<para>There is a temptation to use <function>g_main_depth()</function> 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 <function>g_main_depth()</function> 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:
</para>
<para>1. Use <function>gtk_widget_set_sensitive()</function> or modal dialogs to prevent
   the user from interacting with elements while the main
   loop is recursing.
</para>
<para>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.</para></refsect2><refsect2><title>malloc</title><informalexample><programlisting>(define-values (%return) (malloc n-bytes))
</programlisting></informalexample><para>Allocates <parameter>n_bytes</parameter> bytes of memory.
If <parameter>n_bytes</parameter> is 0 it returns <constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>n_bytes</para></td><td class="parameter_description"><para>the number of bytes to allocate</para><para>Passed as <code>n-bytes</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>malloc0</title><informalexample><programlisting>(define-values (%return) (malloc0 n-bytes))
</programlisting></informalexample><para>Allocates <parameter>n_bytes</parameter> bytes of memory, initialized to 0's.
If <parameter>n_bytes</parameter> is 0 it returns <constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>n_bytes</para></td><td class="parameter_description"><para>the number of bytes to allocate</para><para>Passed as <code>n-bytes</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>malloc0-n</title><informalexample><programlisting>(define-values (%return) (malloc0-n n-blocks n-block-bytes))
</programlisting></informalexample><para>This function is similar to <function>g_malloc0()</function>, allocating (<parameter>n_blocks</parameter> * <parameter>n_block_bytes</parameter>) bytes,
but care is taken to detect possible overflow during multiplication.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>n_blocks</para></td><td class="parameter_description"><para>the number of blocks to allocate</para><para>Passed as <code>n-blocks</code></para></td></tr><tr><td class="parameter_name"><para>n_block_bytes</para></td><td class="parameter_description"><para>the size of each block in bytes</para><para>Passed as <code>n-block-bytes</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>malloc-n</title><informalexample><programlisting>(define-values (%return) (malloc-n n-blocks n-block-bytes))
</programlisting></informalexample><para>This function is similar to <function>g_malloc()</function>, allocating (<parameter>n_blocks</parameter> * <parameter>n_block_bytes</parameter>) bytes,
but care is taken to detect possible overflow during multiplication.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>n_blocks</para></td><td class="parameter_description"><para>the number of blocks to allocate</para><para>Passed as <code>n-blocks</code></para></td></tr><tr><td class="parameter_name"><para>n_block_bytes</para></td><td class="parameter_description"><para>the size of each block in bytes</para><para>Passed as <code>n-block-bytes</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>markup-error-quark</title><informalexample><programlisting>(define-values (%return) (markup-error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>markup-escape-text</title><informalexample><programlisting>(define-values (%return) (markup-escape-text text length))
</programlisting></informalexample><para>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.
</para>
<para>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.
</para>
<para>Note also that this function will produce character references in
the range of &amp;#x1; ... &amp;#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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>text</para></td><td class="parameter_description"><para>some valid UTF-8 text</para><para>Passed as <code>text</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>length of <parameter>text</parameter> in bytes, or -1 if the text is nul-terminated</para><para>Passed as <code>length</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>memdup</title><informalexample><programlisting>(define-values (%return) (memdup mem byte-size))
</programlisting></informalexample><para>Allocates <parameter>byte_size</parameter> bytes of memory, and copies <parameter>byte_size</parameter> bytes into it
from <parameter>mem</parameter>. If <parameter>mem</parameter> is <constant>NULL</constant> it returns <constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>mem</para></td><td class="parameter_description"><para>the memory to copy.</para><para>Passed as <code>mem</code></para></td></tr><tr><td class="parameter_name"><para>byte_size</para></td><td class="parameter_description"><para>the number of bytes to copy.</para><para>Passed as <code>byte-size</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>memdup2</title><informalexample><programlisting>(define-values (%return) (memdup2 mem byte-size))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>mem</para></td><td class="parameter_description"><para></para><para>Passed as <code>mem</code></para></td></tr><tr><td class="parameter_name"><para>byte_size</para></td><td class="parameter_description"><para></para><para>Passed as <code>byte-size</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>mkdir-with-parents</title><informalexample><programlisting>(define-values (%return) (mkdir-with-parents pathname mode))
</programlisting></informalexample><para>Create a directory if it doesn't already exist. Create intermediate
parent directories as needed, too.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>pathname</para></td><td class="parameter_description"><para>a pathname in the GLib file name encoding</para><para>Passed as <code>pathname</code></para></td></tr><tr><td class="parameter_name"><para>mode</para></td><td class="parameter_description"><para>permissions to use for newly created directories</para><para>Passed as <code>mode</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>nullify-pointer</title><informalexample><programlisting>(define-values () (nullify-pointer nullify-location))
</programlisting></informalexample><para>Set the pointer at the specified location to <constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>nullify_location</para></td><td class="parameter_description"><para>the memory address of the pointer.</para><para>Passed as <code>nullify-location</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>number-parser-error-quark</title><informalexample><programlisting>(define-values (%return) (number-parser-error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>on-error-query</title><informalexample><programlisting>(define-values () (on-error-query prg-name))
</programlisting></informalexample><para>Prompts the user with
<code>[E]xit, [H]alt, show [S]tack trace or [P]roceed</code>.
This function is intended to be used for debugging use only.
The following example shows how it can be used together with
the <function>g_log()</function> functions.
</para>
<para><informalexample><programlisting>
#include &lt;glib.h&gt;

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);
  ...
</programlisting></informalexample></para>

<para>If &quot;[E]xit&quot; is selected, the application terminates with a call
to _exit(0).
</para>
<para>If &quot;[S]tack&quot; trace is selected, <function>g_on_error_stack_trace()</function> is called.
This invokes gdb, which attaches to the current process and shows
a stack trace. The prompt is then shown again.
</para>
<para>If &quot;[P]roceed&quot; is selected, the function returns.
</para>
<para>This function may cause different actions on non-UNIX platforms.
</para>
<para>On Windows consider using the <code>G_DEBUGGER</code> environment
variable (see [Running GLib Applications](glib-running.html)) and
calling <function>g_on_error_stack_trace()</function> instead.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>prg_name</para></td><td class="parameter_description"><para>the program name, needed by gdb for the &quot;[S]tack trace&quot;
    option. If <parameter>prg_name</parameter> is <constant>NULL</constant>, <function>g_get_prgname()</function> is called to get
    the program name (which will work correctly if <function>gdk_init()</function> or
    <function>gtk_init()</function> has been called)</para><para>Passed as <code>prg-name</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>on-error-stack-trace</title><informalexample><programlisting>(define-values () (on-error-stack-trace prg-name))
</programlisting></informalexample><para>Invokes gdb, which attaches to the current process and shows a
stack trace. Called by <function>g_on_error_query()</function> when the &quot;[S]tack trace&quot;
option is selected. You can get the current process's program name
with <function>g_get_prgname()</function>, assuming that you have called <function>gtk_init()</function> or
<function>gdk_init()</function>.
</para>
<para>This function may cause different actions on non-UNIX platforms.
</para>
<para>When running on Windows, this function is *not* called by
<function>g_on_error_query()</function>. If called directly, it will raise an
exception, which will crash the program. If the <code>G_DEBUGGER</code> environment
variable is set, a debugger will be invoked to attach and
handle that exception (see [Running GLib Applications](glib-running.html)).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>prg_name</para></td><td class="parameter_description"><para>the program name, needed by gdb for the &quot;[S]tack trace&quot;
    option</para><para>Passed as <code>prg-name</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>once-init-enter?</title><informalexample><programlisting>(define-values (%return) (once-init-enter? location))
</programlisting></informalexample><para>Function to be called when starting a critical initialization
section. The argument <parameter>location</parameter> 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
<function>g_once_init_leave()</function> and the unique address <parameter>value_location</parameter>, 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:
</para>
<para><informalexample><programlisting>
  static gsize initialization_value = 0;

  if (g_once_init_enter (&amp;initialization_value))
    {
      gsize setup_value = 42; // initialization code here

      g_once_init_leave (&amp;initialization_value, setup_value);
    }

  // use initialization_value here
</programlisting></informalexample></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>location</para></td><td class="parameter_description"><para>location of a static initializable variable
   containing 0</para><para>Passed as <code>location</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>once-init-leave</title><informalexample><programlisting>(define-values () (once-init-leave location result))
</programlisting></informalexample><para>Counterpart to <function>g_once_init_enter()</function>. 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 <function>g_once_init_enter()</function> on this
initialization variable.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>location</para></td><td class="parameter_description"><para>location of a static initializable variable
   containing 0</para><para>Passed as <code>location</code></para></td></tr><tr><td class="parameter_name"><para>result</para></td><td class="parameter_description"><para>new non-0 value for *<parameter>value_location</parameter></para><para>Passed as <code>result</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>option-error-quark</title><informalexample><programlisting>(define-values (%return) (option-error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>path-get-basename</title><informalexample><programlisting>(define-values (%return) (path-get-basename file-name))
</programlisting></informalexample><para>Gets the last component of the filename.
</para>
<para>If <parameter>file_name</parameter> ends with a directory separator it gets the component
before the last slash. If <parameter>file_name</parameter> consists only of directory
separators (and on Windows, possibly a drive letter), a single
separator is returned. If <parameter>file_name</parameter> is empty, it gets &quot;.&quot;.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>file_name</para></td><td class="parameter_description"><para>the name of the file</para><para>Passed as <code>file-name</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>path-get-dirname</title><informalexample><programlisting>(define-values (%return) (path-get-dirname file-name))
</programlisting></informalexample><para>Gets the directory components of a file name. For example, the directory
component of <code>/usr/bin/test</code> is <code>/usr/bin</code>. The directory component of <code>/</code>
is <code>/</code>.
</para>
<para>If the file name has no directory components &quot;.&quot; is returned.
The returned string should be freed when no longer needed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>file_name</para></td><td class="parameter_description"><para>the name of the file</para><para>Passed as <code>file-name</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>path-is-absolute?</title><informalexample><programlisting>(define-values (%return) (path-is-absolute? file-name))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> if the given <parameter>file_name</parameter> is an absolute file name.
Note that this is a somewhat vague concept on Windows.
</para>
<para>On POSIX systems, an absolute file name is well-defined. It always
starts from the single root directory. For example &quot;/usr/local&quot;.
</para>
<para>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 &quot;\Users\tml&quot; or begins with the root on a drive,
for example &quot;C:\Windows&quot;. The first case also includes UNC paths
such as &quot;\\\\myserver\docs\foo&quot;. In all cases, either slashes or
backslashes are accepted.
</para>
<para>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.
</para>
<para>File names relative the current directory on some specific drive,
such as &quot;D:foo/bar&quot;, are not interpreted as absolute by this
function, but they obviously are not relative to the normal current
directory as returned by <function>getcwd()</function> or <function>g_get_current_dir()</function>
either. Such paths should be avoided, or need to be handled using
Windows-specific code.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>file_name</para></td><td class="parameter_description"><para>a file name</para><para>Passed as <code>file-name</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>path-skip-root</title><informalexample><programlisting>(define-values (%return) (path-skip-root file-name))
</programlisting></informalexample><para>Returns a pointer into <parameter>file_name</parameter> after the root component,
i.e. after the &quot;/&quot; in UNIX or &quot;C:\&quot; under Windows. If <parameter>file_name</parameter>
is not an absolute path it returns <constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>file_name</para></td><td class="parameter_description"><para>a file name</para><para>Passed as <code>file-name</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>pattern-match?</title><informalexample><programlisting>(define-values
  (%return)
  (pattern-match? pspec string-length string string-reversed))
</programlisting></informalexample><para>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 <constant>NULL</constant>, this is more efficient if the reversed
version of the string to be matched is not at hand, as
<function>g_pattern_match()</function> will only construct it if the compiled pattern
requires reverse matches.
</para>
<para>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 <function>g_pattern_match()</function>.
</para>
<para>Note also that the reverse of a UTF-8 encoded string can in general
not be obtained by <function>g_strreverse()</function>. This works only if the string
does not contain any multibyte characters. GLib offers the
<function>g_utf8_strreverse()</function> function to reverse UTF-8 encoded strings.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>pspec</para></td><td class="parameter_description"><para>a <type>GPatternSpec</type></para><para>Passed as <code>pspec</code></para></td></tr><tr><td class="parameter_name"><para>string_length</para></td><td class="parameter_description"><para>the length of <parameter>string</parameter> (in bytes, i.e. <function>strlen()</function>,
    not <function>g_utf8_strlen()</function>)</para><para>Passed as <code>string-length</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the UTF-8 encoded string to match</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>string_reversed</para></td><td class="parameter_description"><para>the reverse of <parameter>string</parameter> or <constant>NULL</constant></para><para>Passed as <code>string-reversed</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>pattern-match-simple?</title><informalexample><programlisting>(define-values (%return) (pattern-match-simple? pattern string))
</programlisting></informalexample><para>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 <function>g_pattern_spec_new()</function> and call
<function>g_pattern_match_string()</function> repeatedly.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>pattern</para></td><td class="parameter_description"><para>the UTF-8 encoded pattern</para><para>Passed as <code>pattern</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the UTF-8 encoded string to match</para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>pattern-match-string?</title><informalexample><programlisting>(define-values (%return) (pattern-match-string? pspec string))
</programlisting></informalexample><para>Matches a string against a compiled pattern. If the string is to be
matched against more than one pattern, consider using
<function>g_pattern_match()</function> instead while supplying the reversed string.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>pspec</para></td><td class="parameter_description"><para>a <type>GPatternSpec</type></para><para>Passed as <code>pspec</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the UTF-8 encoded string to match</para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>pointer-bit-lock</title><informalexample><programlisting>(define-values () (pointer-bit-lock address lock-bit))
</programlisting></informalexample><para>This is equivalent to g_bit_lock, but working on pointers (or other
pointer-sized values).
</para>
<para>For portability reasons, you may only lock on the bottom 32 bits of
the pointer.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>address</para></td><td class="parameter_description"><para>a pointer to a <type>gpointer</type>-sized value</para><para>Passed as <code>address</code></para></td></tr><tr><td class="parameter_name"><para>lock_bit</para></td><td class="parameter_description"><para>a bit value between 0 and 31</para><para>Passed as <code>lock-bit</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>pointer-bit-trylock?</title><informalexample><programlisting>(define-values (%return) (pointer-bit-trylock? address lock-bit))
</programlisting></informalexample><para>This is equivalent to g_bit_trylock, but working on pointers (or
other pointer-sized values).
</para>
<para>For portability reasons, you may only lock on the bottom 32 bits of
the pointer.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>address</para></td><td class="parameter_description"><para>a pointer to a <type>gpointer</type>-sized value</para><para>Passed as <code>address</code></para></td></tr><tr><td class="parameter_name"><para>lock_bit</para></td><td class="parameter_description"><para>a bit value between 0 and 31</para><para>Passed as <code>lock-bit</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>pointer-bit-unlock</title><informalexample><programlisting>(define-values () (pointer-bit-unlock address lock-bit))
</programlisting></informalexample><para>This is equivalent to g_bit_unlock, but working on pointers (or other
pointer-sized values).
</para>
<para>For portability reasons, you may only lock on the bottom 32 bits of
the pointer.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>address</para></td><td class="parameter_description"><para>a pointer to a <type>gpointer</type>-sized value</para><para>Passed as <code>address</code></para></td></tr><tr><td class="parameter_name"><para>lock_bit</para></td><td class="parameter_description"><para>a bit value between 0 and 31</para><para>Passed as <code>lock-bit</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>poll</title><informalexample><programlisting>(define-values (%return) (poll fds nfds timeout))
</programlisting></informalexample><para>Polls <parameter>fds</parameter>, as with the <function>poll()</function> system call, but portably. (On
systems that don't have <function>poll()</function>, it is emulated using <function>select()</function>.)
This is used internally by <type>GMainContext</type>, 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.
</para>
<para>Each element of <parameter>fds</parameter> is a <type>GPollFD</type> describing a single file
descriptor to poll. The <parameter>fd</parameter> field indicates the file descriptor,
and the <parameter>events</parameter> field indicates the events to poll for. On return,
the <parameter>revents</parameter> fields will be filled with the events that actually
occurred.
</para>
<para>On POSIX systems, the file descriptors in <parameter>fds</parameter> can be any sort of
file descriptor, but the situation is much more complicated on
Windows. If you need to use <function>g_poll()</function> in code that has to run on
Windows, the easiest solution is to construct all of your
<type>GPollFDs</type> with <function>g_io_channel_win32_make_pollfd()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>fds</para></td><td class="parameter_description"><para>file descriptors to poll</para><para>Passed as <code>fds</code></para></td></tr><tr><td class="parameter_name"><para>nfds</para></td><td class="parameter_description"><para>the number of file descriptors in <parameter>fds</parameter></para><para>Passed as <code>nfds</code></para></td></tr><tr><td class="parameter_name"><para>timeout</para></td><td class="parameter_description"><para>amount of time to wait, in milliseconds, or -1 to wait forever</para><para>Passed as <code>timeout</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>prefix-error-literal</title><informalexample><programlisting>(define-values () (prefix-error-literal err prefix))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>err</para></td><td class="parameter_description"><para></para><para>Passed as <code>err</code></para></td></tr><tr><td class="parameter_name"><para>prefix</para></td><td class="parameter_description"><para></para><para>Passed as <code>prefix</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>propagate-error</title><informalexample><programlisting>(define-values (dest) (propagate-error src))
</programlisting></informalexample><para>If <parameter>dest</parameter> is <constant>NULL</constant>, free <parameter>src</parameter>; otherwise, moves <parameter>src</parameter> into *<parameter>dest</parameter>.
The error variable <parameter>dest</parameter> points to must be <constant>NULL</constant>.
</para>
<para><parameter>src</parameter> must be non-<constant>NULL</constant>.
</para>
<para>Note that <parameter>src</parameter> is no longer valid after this call. If you want
to keep using the same GError*, you need to set it to <constant>NULL</constant>
after calling this function on it.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dest</para></td><td class="parameter_description"><para>error return location</para><para>Passed as <code>dest</code></para></td></tr><tr><td class="parameter_name"><para>src</para></td><td class="parameter_description"><para>error to move into the return location</para><para>Passed as <code>src</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>quark-from-static-string</title><informalexample><programlisting>(define-values (%return) (quark-from-static-string string))
</programlisting></informalexample><para>Gets the <type>GQuark</type> identifying the given (static) string. If the
string does not currently have an associated <type>GQuark</type>, a new <type>GQuark</type>
is created, linked to the given string.
</para>
<para>Note that this function is identical to <function>g_quark_from_string()</function> except
that if a new <type>GQuark</type> 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).
</para>
<para>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++.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>quark-from-string</title><informalexample><programlisting>(define-values (%return) (quark-from-string string))
</programlisting></informalexample><para>Gets the <type>GQuark</type> identifying the given string. If the string does
not currently have an associated <type>GQuark</type>, a new <type>GQuark</type> is created,
using a copy of the string.
</para>
<para>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++.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>quark-to-string</title><informalexample><programlisting>(define-values (%return) (quark-to-string quark))
</programlisting></informalexample><para>Gets the string associated with the given <type>GQuark</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>quark</para></td><td class="parameter_description"><para>a <type>GQuark</type>.</para><para>Passed as <code>quark</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>quark-try-string</title><informalexample><programlisting>(define-values (%return) (quark-try-string string))
</programlisting></informalexample><para>Gets the <type>GQuark</type> associated with the given string, or 0 if string is
<constant>NULL</constant> or it has no associated <type>GQuark</type>.
</para>
<para>If you want the GQuark to be created if it doesn't already exist,
use <function>g_quark_from_string()</function> or <function>g_quark_from_static_string()</function>.
</para>
<para>This function must not be used before library constructors have finished
running.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>random-double</title><informalexample><programlisting>(define-values (%return) (random-double))
</programlisting></informalexample><para>Returns a random <type>gdouble</type> equally distributed over the range [0..1).</para></refsect2><refsect2><title>random-double-range</title><informalexample><programlisting>(define-values (%return) (random-double-range begin end))
</programlisting></informalexample><para>Returns a random <type>gdouble</type> equally distributed over the range
[<parameter>begin</parameter>..<parameter>end</parameter>).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>begin</para></td><td class="parameter_description"><para>lower closed bound of the interval</para><para>Passed as <code>begin</code></para></td></tr><tr><td class="parameter_name"><para>end</para></td><td class="parameter_description"><para>upper open bound of the interval</para><para>Passed as <code>end</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>random-int</title><informalexample><programlisting>(define-values (%return) (random-int))
</programlisting></informalexample><para>Return a random <type>guint32</type> equally distributed over the range
[0..2^32-1].</para></refsect2><refsect2><title>random-int-range</title><informalexample><programlisting>(define-values (%return) (random-int-range begin end))
</programlisting></informalexample><para>Returns a random <type>gint32</type> equally distributed over the range
[<parameter>begin</parameter>..<parameter>end</parameter>-1].</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>begin</para></td><td class="parameter_description"><para>lower closed bound of the interval</para><para>Passed as <code>begin</code></para></td></tr><tr><td class="parameter_name"><para>end</para></td><td class="parameter_description"><para>upper open bound of the interval</para><para>Passed as <code>end</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>random-set-seed</title><informalexample><programlisting>(define-values () (random-set-seed seed))
</programlisting></informalexample><para>Sets the seed for the global random number generator, which is used
by the g_random_* functions, to <parameter>seed</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>seed</para></td><td class="parameter_description"><para>a value to reinitialize the global random number generator</para><para>Passed as <code>seed</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>rc-box-acquire</title><informalexample><programlisting>(define-values (%return) (rc-box-acquire mem-block))
</programlisting></informalexample><para>Acquires a reference on the data pointed by <parameter>mem_block</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>mem_block</para></td><td class="parameter_description"><para>a pointer to reference counted data</para><para>Passed as <code>mem-block</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>rc-box-alloc</title><informalexample><programlisting>(define-values (%return) (rc-box-alloc block-size))
</programlisting></informalexample><para>Allocates <parameter>block_size</parameter> bytes of memory, and adds reference
counting semantics to it.
</para>
<para>The data will be freed when its reference count drops to
zero.
</para>
<para>The allocated data is guaranteed to be suitably aligned for any
built-in type.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>block_size</para></td><td class="parameter_description"><para>the size of the allocation, must be greater than 0</para><para>Passed as <code>block-size</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>rc-box-alloc0</title><informalexample><programlisting>(define-values (%return) (rc-box-alloc0 block-size))
</programlisting></informalexample><para>Allocates <parameter>block_size</parameter> bytes of memory, and adds reference
counting semantics to it.
</para>
<para>The contents of the returned data is set to zero.
</para>
<para>The data will be freed when its reference count drops to
zero.
</para>
<para>The allocated data is guaranteed to be suitably aligned for any
built-in type.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>block_size</para></td><td class="parameter_description"><para>the size of the allocation, must be greater than 0</para><para>Passed as <code>block-size</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>rc-box-dup</title><informalexample><programlisting>(define-values (%return) (rc-box-dup block-size mem-block))
</programlisting></informalexample><para>Allocates a new block of data with reference counting
semantics, and copies <parameter>block_size</parameter> bytes of <parameter>mem_block</parameter>
into it.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>block_size</para></td><td class="parameter_description"><para>the number of bytes to copy, must be greater than 0</para><para>Passed as <code>block-size</code></para></td></tr><tr><td class="parameter_name"><para>mem_block</para></td><td class="parameter_description"><para>the memory to copy</para><para>Passed as <code>mem-block</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>rc-box-get-size</title><informalexample><programlisting>(define-values (%return) (rc-box-get-size mem-block))
</programlisting></informalexample><para>Retrieves the size of the reference counted data pointed by <parameter>mem_block</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>mem_block</para></td><td class="parameter_description"><para>a pointer to reference counted data</para><para>Passed as <code>mem-block</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>rc-box-release</title><informalexample><programlisting>(define-values () (rc-box-release mem-block))
</programlisting></informalexample><para>Releases a reference on the data pointed by <parameter>mem_block</parameter>.
</para>
<para>If the reference was the last one, it will free the
resources allocated for <parameter>mem_block</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>mem_block</para></td><td class="parameter_description"><para>a pointer to reference counted data</para><para>Passed as <code>mem-block</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>rc-box-release-full</title><informalexample><programlisting>(define-values () (rc-box-release-full mem-block clear-func))
</programlisting></informalexample><para>Releases a reference on the data pointed by <parameter>mem_block</parameter>.
</para>
<para>If the reference was the last one, it will call <parameter>clear_func</parameter>
to clear the contents of <parameter>mem_block</parameter>, and then will free the
resources allocated for <parameter>mem_block</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>mem_block</para></td><td class="parameter_description"><para>a pointer to reference counted data</para><para>Passed as <code>mem-block</code></para></td></tr><tr><td class="parameter_name"><para>clear_func</para></td><td class="parameter_description"><para>a function to call when clearing the data</para><para>Passed as <code>clear-func</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>realloc</title><informalexample><programlisting>(define-values (%return) (realloc mem n-bytes))
</programlisting></informalexample><para>Reallocates the memory pointed to by <parameter>mem</parameter>, so that it now has space for
<parameter>n_bytes</parameter> bytes of memory. It returns the new address of the memory, which may
have been moved. <parameter>mem</parameter> may be <constant>NULL</constant>, in which case it's considered to
have zero-length. <parameter>n_bytes</parameter> may be 0, in which case <constant>NULL</constant> will be returned
and <parameter>mem</parameter> will be freed unless it is <constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>mem</para></td><td class="parameter_description"><para>the memory to reallocate</para><para>Passed as <code>mem</code></para></td></tr><tr><td class="parameter_name"><para>n_bytes</para></td><td class="parameter_description"><para>new size of the memory in bytes</para><para>Passed as <code>n-bytes</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>realloc-n</title><informalexample><programlisting>(define-values (%return) (realloc-n mem n-blocks n-block-bytes))
</programlisting></informalexample><para>This function is similar to <function>g_realloc()</function>, allocating (<parameter>n_blocks</parameter> * <parameter>n_block_bytes</parameter>) bytes,
but care is taken to detect possible overflow during multiplication.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>mem</para></td><td class="parameter_description"><para>the memory to reallocate</para><para>Passed as <code>mem</code></para></td></tr><tr><td class="parameter_name"><para>n_blocks</para></td><td class="parameter_description"><para>the number of blocks to allocate</para><para>Passed as <code>n-blocks</code></para></td></tr><tr><td class="parameter_name"><para>n_block_bytes</para></td><td class="parameter_description"><para>the size of each block in bytes</para><para>Passed as <code>n-block-bytes</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref-count-compare?</title><informalexample><programlisting>(define-values (%return) (ref-count-compare? rc val))
</programlisting></informalexample><para>Compares the current value of <parameter>rc</parameter> with <parameter>val</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>rc</para></td><td class="parameter_description"><para>the address of a reference count variable</para><para>Passed as <code>rc</code></para></td></tr><tr><td class="parameter_name"><para>val</para></td><td class="parameter_description"><para>the value to compare</para><para>Passed as <code>val</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref-count-dec?</title><informalexample><programlisting>(define-values (%return) (ref-count-dec? rc))
</programlisting></informalexample><para>Decreases the reference count.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>rc</para></td><td class="parameter_description"><para>the address of a reference count variable</para><para>Passed as <code>rc</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref-count-inc</title><informalexample><programlisting>(define-values () (ref-count-inc rc))
</programlisting></informalexample><para>Increases the reference count.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>rc</para></td><td class="parameter_description"><para>the address of a reference count variable</para><para>Passed as <code>rc</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref-count-init</title><informalexample><programlisting>(define-values () (ref-count-init rc))
</programlisting></informalexample><para>Initializes a reference count variable.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>rc</para></td><td class="parameter_description"><para>the address of a reference count variable</para><para>Passed as <code>rc</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref-string-acquire</title><informalexample><programlisting>(define-values (%return) (ref-string-acquire str))
</programlisting></informalexample><para>Acquires a reference on a string.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a reference counted string</para><para>Passed as <code>str</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref-string-length</title><informalexample><programlisting>(define-values (%return) (ref-string-length str))
</programlisting></informalexample><para>Retrieves the length of <parameter>str</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a reference counted string</para><para>Passed as <code>str</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref-string-new</title><informalexample><programlisting>(define-values (%return) (ref-string-new str))
</programlisting></informalexample><para>Creates a new reference counted string and copies the contents of <parameter>str</parameter>
into it.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a NUL-terminated string</para><para>Passed as <code>str</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref-string-new-intern</title><informalexample><programlisting>(define-values (%return) (ref-string-new-intern str))
</programlisting></informalexample><para>Creates a new reference counted string and copies the content of <parameter>str</parameter>
into it.
</para>
<para>If you call this function multiple times with the same <parameter>str</parameter>, or with
the same contents of <parameter>str</parameter>, it will return a new reference, instead of
creating a new string.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a NUL-terminated string</para><para>Passed as <code>str</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref-string-new-len</title><informalexample><programlisting>(define-values (%return) (ref-string-new-len str len))
</programlisting></informalexample><para>Creates a new reference counted string and copies the contents of <parameter>str</parameter>
into it, up to <parameter>len</parameter> bytes.
</para>
<para>Since this function does not stop at nul bytes, it is the caller's
responsibility to ensure that <parameter>str</parameter> has at least <parameter>len</parameter> addressable bytes.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>length of <parameter>str</parameter> to use, or -1 if <parameter>str</parameter> is nul-terminated</para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ref-string-release</title><informalexample><programlisting>(define-values () (ref-string-release str))
</programlisting></informalexample><para>Releases a reference on a string; if it was the last reference, the
resources allocated by the string are freed as well.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a reference counted string</para><para>Passed as <code>str</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>regex-check-replacement</title><informalexample><programlisting>(define-values (%return has-references) (regex-check-replacement replacement))
</programlisting></informalexample><para>Checks whether <parameter>replacement</parameter> is a valid replacement string
(see <function>g_regex_replace()</function>), i.e. that all escape sequences in
it are valid.
</para>
<para>If <parameter>has_references</parameter> is not <constant>NULL</constant> then <parameter>replacement</parameter> 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 <type>GMatchInfo</type> object.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>replacement</para></td><td class="parameter_description"><para>the replacement string</para><para>Passed as <code>replacement</code></para></td></tr><tr><td class="parameter_name"><para>has_references</para></td><td class="parameter_description"><para>location to store information about
  references in <parameter>replacement</parameter> or <constant>NULL</constant></para><para>Passed as <code>has-references</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>regex-error-quark</title><informalexample><programlisting>(define-values (%return) (regex-error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>regex-escape-nul</title><informalexample><programlisting>(define-values (%return) (regex-escape-nul string length))
</programlisting></informalexample><para>Escapes the nul characters in <parameter>string</parameter> to &quot;\x00&quot;.  It can be used
to compile a regex with embedded nul characters.
</para>
<para>For completeness, <parameter>length</parameter> can be -1 for a nul-terminated string.
In this case the output string will be of course equal to <parameter>string</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to escape</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of <parameter>string</parameter></para><para>Passed as <code>length</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>regex-escape-string</title><informalexample><programlisting>(define-values (%return) (regex-escape-string string))
</programlisting></informalexample><para>Escapes the special characters used for regular expressions
in <parameter>string</parameter>, for instance &quot;a.b*c&quot; becomes &quot;a\.b\*c&quot;. This
function is useful to dynamically generate regular expressions.
</para>
<para><parameter>string</parameter> can contain nul characters that are replaced with &quot;\0&quot;,
in this case remember to specify the correct length of <parameter>string</parameter>
in <parameter>length</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to escape</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of <parameter>string</parameter>, in bytes, or -1 if <parameter>string</parameter> is nul-terminated</para><para>Inferred from <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>regex-match-simple?</title><informalexample><programlisting>(define-values
  (%return)
  (regex-match-simple? pattern string compile-options match-options))
</programlisting></informalexample><para>Scans for a match in <parameter>string</parameter> for <parameter>pattern</parameter>.
</para>
<para>This function is equivalent to <function>g_regex_match()</function> but it does not
require to compile the pattern with <function>g_regex_new()</function>, avoiding some
lines of code when you need just to do a match without extracting
substrings, capture counts, and so on.
</para>
<para>If this function is to be called on the same <parameter>pattern</parameter> more than
once, it's more efficient to compile the pattern once with
<function>g_regex_new()</function> and then use <function>g_regex_match()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>pattern</para></td><td class="parameter_description"><para>the regular expression</para><para>Passed as <code>pattern</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to scan for matches</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>compile_options</para></td><td class="parameter_description"><para>compile options for the regular expression, or 0</para><para>Passed as <code>compile-options</code></para></td></tr><tr><td class="parameter_name"><para>match_options</para></td><td class="parameter_description"><para>match options, or 0</para><para>Passed as <code>match-options</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>regex-split-simple</title><informalexample><programlisting>(define-values
  (%return)
  (regex-split-simple pattern string compile-options match-options))
</programlisting></informalexample><para>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.
</para>
<para>This function is equivalent to <function>g_regex_split()</function> but it does
not require to compile the pattern with <function>g_regex_new()</function>, avoiding
some lines of code when you need just to do a split without
extracting substrings, capture counts, and so on.
</para>
<para>If this function is to be called on the same <parameter>pattern</parameter> more than
once, it's more efficient to compile the pattern once with
<function>g_regex_new()</function> and then use <function>g_regex_split()</function>.
</para>
<para>As a special case, the result of splitting the empty string &quot;&quot;
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.
</para>
<para>A pattern that can match empty strings splits <parameter>string</parameter> into
separate characters wherever it matches the empty string between
characters. For example splitting &quot;ab c&quot; using as a separator
&quot;\s*&quot;, you will get &quot;a&quot;, &quot;b&quot; and &quot;c&quot;.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>pattern</para></td><td class="parameter_description"><para>the regular expression</para><para>Passed as <code>pattern</code></para></td></tr><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to scan for matches</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>compile_options</para></td><td class="parameter_description"><para>compile options for the regular expression, or 0</para><para>Passed as <code>compile-options</code></para></td></tr><tr><td class="parameter_name"><para>match_options</para></td><td class="parameter_description"><para>match options, or 0</para><para>Passed as <code>match-options</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>reload-user-special-dirs-cache</title><informalexample><programlisting>(define-values () (reload-user-special-dirs-cache))
</programlisting></informalexample><para>Resets the cache used for <function>g_get_user_special_dir()</function>, so
that the latest on-disk version is used. Call this only
if you just changed the data on disk yourself.
</para>
<para>Due to thread safety issues this may cause leaking of strings
that were previously returned from <function>g_get_user_special_dir()</function>
that can't be freed. We ensure to only leak the data for
the directories that actually changed value though.</para></refsect2><refsect2><title>rmdir</title><informalexample><programlisting>(define-values (%return) (rmdir filename))
</programlisting></informalexample><para>A wrapper for the POSIX <function>rmdir()</function> function. The <function>rmdir()</function> function
deletes a directory from the filesystem.
</para>
<para>See your C library manual for more details about how <function>rmdir()</function> works
on your system.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>filename</para></td><td class="parameter_description"><para>a pathname in the GLib file name encoding
    (UTF-8 on Windows)</para><para>Passed as <code>filename</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-application-name</title><informalexample><programlisting>(define-values () (set-application-name application-name))
</programlisting></informalexample><para>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 <function>g_set_prgname()</function>, which sets a non-localized name.
<function>g_set_prgname()</function> will be called automatically by <function>gtk_init()</function>,
but <function>g_set_application_name()</function> will not.
</para>
<para>Note that for thread safety reasons, this function can only
be called once.
</para>
<para>The application name will be used in contexts such as error messages,
or when displaying an application's name in the task list.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>application_name</para></td><td class="parameter_description"><para>localized name of the application</para><para>Passed as <code>application-name</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-error-literal</title><informalexample><programlisting>(define-values (err) (set-error-literal domain code message))
</programlisting></informalexample><para>Does nothing if <parameter>err</parameter> is <constant>NULL</constant>; if <parameter>err</parameter> is non-<constant>NULL</constant>, then *<parameter>err</parameter>
must be <constant>NULL</constant>. A new <type>GError</type> is created and assigned to *<parameter>err</parameter>.
Unlike <function>g_set_error()</function>, <parameter>message</parameter> is not a <function>printf()</function>-style format string.
Use this function if <parameter>message</parameter> contains text you don't have control over,
that could include <function>printf()</function> escape sequences.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>err</para></td><td class="parameter_description"><para>a return location for a <type>GError</type></para><para>Passed as <code>err</code></para></td></tr><tr><td class="parameter_name"><para>domain</para></td><td class="parameter_description"><para>error domain</para><para>Passed as <code>domain</code></para></td></tr><tr><td class="parameter_name"><para>code</para></td><td class="parameter_description"><para>error code</para><para>Passed as <code>code</code></para></td></tr><tr><td class="parameter_name"><para>message</para></td><td class="parameter_description"><para>error message</para><para>Passed as <code>message</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>set-prgname</title><informalexample><programlisting>(define-values () (set-prgname prgname))
</programlisting></informalexample><para>Sets the name of the program. This name should not be localized,
in contrast to <function>g_set_application_name()</function>.
</para>
<para>If you are using <type>GApplication</type> the program name is set in
<function>g_application_run()</function>. In case of GDK or GTK+ it is set in
<function>gdk_init()</function>, which is called by <function>gtk_init()</function> and the
<type>“startup”</type> handler. The program name is found by
taking the last component of <parameter>argv</parameter>[0].
</para>
<para>Note that for thread-safety reasons this function can only be called once.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>prgname</para></td><td class="parameter_description"><para>the name of the program.</para><para>Passed as <code>prgname</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>setenv?</title><informalexample><programlisting>(define-values (%return) (setenv? variable value overwrite))
</programlisting></informalexample><para>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.
</para>
<para>Note that on some systems, when variables are overwritten, the memory
used for the previous variables and its value isn't reclaimed.
</para>
<para>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 <function>g_setenv()</function> while another thread is calling <function>getenv()</function>. (And note
that many functions, such as <function>gettext()</function>, call <function>getenv()</function> 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).
</para>
<para>If you need to set up the environment for a child process, you can
use <function>g_get_environ()</function> to get an environment array, modify that with
<function>g_environ_setenv()</function> and <function>g_environ_unsetenv()</function>, and then pass that
array directly to <function>execvpe()</function>, <function>g_spawn_async()</function>, or the like.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>variable</para></td><td class="parameter_description"><para>the environment variable to set, must not
    contain '='.</para><para>Passed as <code>variable</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para>the value for to set the variable to.</para><para>Passed as <code>value</code></para></td></tr><tr><td class="parameter_name"><para>overwrite</para></td><td class="parameter_description"><para>whether to change the variable if it already exists.</para><para>Passed as <code>overwrite</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>shell-error-quark</title><informalexample><programlisting>(define-values (%return) (shell-error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>shell-parse-argv</title><informalexample><programlisting>(define-values (%return argcp argvp) (shell-parse-argv command-line))
</programlisting></informalexample><para>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 <type>G_SHELL_ERROR</type>
domain. Free the returned vector with <function>g_strfreev()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>command_line</para></td><td class="parameter_description"><para>command line to parse</para><para>Passed as <code>command-line</code></para></td></tr><tr><td class="parameter_name"><para>argcp</para></td><td class="parameter_description"><para>return location for number of args</para><para>Inferred from <code>argvp</code></para></td></tr><tr><td class="parameter_name"><para>argvp</para></td><td class="parameter_description"><para>
  <para>return location for array of args</para></para><para>Passed as <code>argvp</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>shell-quote</title><informalexample><programlisting>(define-values (%return) (shell-quote unquoted-string))
</programlisting></informalexample><para>Quotes a string so that the shell (/bin/sh) will interpret the
quoted string to mean <parameter>unquoted_string</parameter>. 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 <function>g_free()</function>. The
quoting style used is undefined (single or double quotes may be
used).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>unquoted_string</para></td><td class="parameter_description"><para>a literal string</para><para>Passed as <code>unquoted-string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>shell-unquote</title><informalexample><programlisting>(define-values (%return) (shell-unquote quoted-string))
</programlisting></informalexample><para>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
<function>g_shell_quote()</function>. If it fails, it returns <constant>NULL</constant> and sets the
error. The <parameter>quoted_string</parameter> need not actually contain quoted or
escaped text; <function>g_shell_unquote()</function> 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 <function>g_free()</function>. Possible
errors are in the <type>G_SHELL_ERROR</type> domain.
</para>
<para>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 $, `, &quot;, \, and newline to
be escaped with backslash. Otherwise double quotes preserve things
literally.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>quoted_string</para></td><td class="parameter_description"><para>shell-quoted string</para><para>Passed as <code>quoted-string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>slice-alloc</title><informalexample><programlisting>(define-values (%return) (slice-alloc block-size))
</programlisting></informalexample><para>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 <function>malloc()</function> 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 [<code>G_SLICE=always-malloc</code>][G_SLICE]
environment variable.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>block_size</para></td><td class="parameter_description"><para>the number of bytes to allocate</para><para>Passed as <code>block-size</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>slice-alloc0</title><informalexample><programlisting>(define-values (%return) (slice-alloc0 block-size))
</programlisting></informalexample><para>Allocates a block of memory via <function>g_slice_alloc()</function> and initializes
the returned memory to 0. Note that the underlying slice allocation
mechanism can be changed with the [<code>G_SLICE=always-malloc</code>][G_SLICE]
environment variable.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>block_size</para></td><td class="parameter_description"><para>the number of bytes to allocate</para><para>Passed as <code>block-size</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>slice-copy</title><informalexample><programlisting>(define-values (%return) (slice-copy block-size mem-block))
</programlisting></informalexample><para>Allocates a block of memory from the slice allocator
and copies <parameter>block_size</parameter> bytes into it from <parameter>mem_block</parameter>.
</para>
<para><parameter>mem_block</parameter> must be non-<constant>NULL</constant> if <parameter>block_size</parameter> is non-zero.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>block_size</para></td><td class="parameter_description"><para>the number of bytes to allocate</para><para>Passed as <code>block-size</code></para></td></tr><tr><td class="parameter_name"><para>mem_block</para></td><td class="parameter_description"><para>the memory to copy</para><para>Passed as <code>mem-block</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>slice-free1</title><informalexample><programlisting>(define-values () (slice-free1 block-size mem-block))
</programlisting></informalexample><para>Frees a block of memory.
</para>
<para>The memory must have been allocated via <function>g_slice_alloc()</function> or
<function>g_slice_alloc0()</function> and the <parameter>block_size</parameter> has to match the size
specified upon allocation. Note that the exact release behaviour
can be changed with the [<code>G_DEBUG=gc-friendly</code>][G_DEBUG] environment
variable, also see [<code>G_SLICE</code>][G_SLICE] for related debugging options.
</para>
<para>If <parameter>mem_block</parameter> is <constant>NULL</constant>, this function does nothing.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>block_size</para></td><td class="parameter_description"><para>the size of the block</para><para>Passed as <code>block-size</code></para></td></tr><tr><td class="parameter_name"><para>mem_block</para></td><td class="parameter_description"><para>a pointer to the block to free</para><para>Passed as <code>mem-block</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>slice-free-chain-with-offset</title><informalexample><programlisting>(define-values
  ()
  (slice-free-chain-with-offset block-size mem-chain next-offset))
</programlisting></informalexample><para>Frees a linked list of memory blocks of structure type <parameter>type</parameter>.
</para>
<para>The memory blocks must be equal-sized, allocated via
<function>g_slice_alloc()</function> or <function>g_slice_alloc0()</function> and linked together by a
<parameter>next</parameter> pointer (similar to <type>GSList</type>). The offset of the <parameter>next</parameter>
field in each block is passed as third argument.
Note that the exact release behaviour can be changed with the
[<code>G_DEBUG=gc-friendly</code>][G_DEBUG] environment variable, also see
[<code>G_SLICE</code>][G_SLICE] for related debugging options.
</para>
<para>If <parameter>mem_chain</parameter> is <constant>NULL</constant>, this function does nothing.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>block_size</para></td><td class="parameter_description"><para>the size of the blocks</para><para>Passed as <code>block-size</code></para></td></tr><tr><td class="parameter_name"><para>mem_chain</para></td><td class="parameter_description"><para>a pointer to the first block of the chain</para><para>Passed as <code>mem-chain</code></para></td></tr><tr><td class="parameter_name"><para>next_offset</para></td><td class="parameter_description"><para>the offset of the <parameter>next</parameter> field in the blocks</para><para>Passed as <code>next-offset</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>slice-get-config</title><informalexample><programlisting>(define-values (%return) (slice-get-config ckey))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>ckey</para></td><td class="parameter_description"><para></para><para>Passed as <code>ckey</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>slice-get-config-state</title><informalexample><programlisting>(define-values (%return) (slice-get-config-state ckey address n-values))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>ckey</para></td><td class="parameter_description"><para></para><para>Passed as <code>ckey</code></para></td></tr><tr><td class="parameter_name"><para>address</para></td><td class="parameter_description"><para></para><para>Passed as <code>address</code></para></td></tr><tr><td class="parameter_name"><para>n_values</para></td><td class="parameter_description"><para></para><para>Passed as <code>n-values</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>slice-set-config</title><informalexample><programlisting>(define-values () (slice-set-config ckey value))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>ckey</para></td><td class="parameter_description"><para></para><para>Passed as <code>ckey</code></para></td></tr><tr><td class="parameter_name"><para>value</para></td><td class="parameter_description"><para></para><para>Passed as <code>value</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>source-remove?</title><informalexample><programlisting>(define-values (%return) (source-remove? tag))
</programlisting></informalexample><para>Removes the source with the given ID from the default main context. You must
use <function>g_source_destroy()</function> for sources added to a non-default main context.
</para>
<para>The ID of a <type>GSource</type> is given by <function>g_source_get_id()</function>, or will be
returned by the functions <function>g_source_attach()</function>, <function>g_idle_add()</function>,
<function>g_idle_add_full()</function>, <function>g_timeout_add()</function>, <function>g_timeout_add_full()</function>,
<function>g_child_watch_add()</function>, <function>g_child_watch_add_full()</function>, <function>g_io_add_watch()</function>, and
<function>g_io_add_watch_full()</function>.
</para>
<para>It is a programmer error to attempt to remove a non-existent source.
</para>
<para>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 <function>g_idle_add()</function>: 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tag</para></td><td class="parameter_description"><para>the ID of the source to remove.</para><para>Passed as <code>tag</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>source-remove-by-user-data?</title><informalexample><programlisting>(define-values (%return) (source-remove-by-user-data? user-data))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>user_data</para></td><td class="parameter_description"><para>the user_data for the callback.</para><para>Passed as <code>user-data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>source-set-name-by-id</title><informalexample><programlisting>(define-values () (source-set-name-by-id tag name))
</programlisting></informalexample><para>Sets the name of a source using its ID.
</para>
<para>This is a convenience utility to set source names from the return
value of <function>g_idle_add()</function>, <function>g_timeout_add()</function>, etc.
</para>
<para>It is a programmer error to attempt to set the name of a non-existent
source.
</para>
<para>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 <function>g_idle_add()</function>: 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>tag</para></td><td class="parameter_description"><para>a <type>GSource</type> ID</para><para>Passed as <code>tag</code></para></td></tr><tr><td class="parameter_name"><para>name</para></td><td class="parameter_description"><para>debug name for the source</para><para>Passed as <code>name</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>spaced-primes-closest</title><informalexample><programlisting>(define-values (%return) (spaced-primes-closest num))
</programlisting></informalexample><para>Gets the smallest prime number from a built-in array of primes which
is larger than <parameter>num</parameter>. This is used within GLib to calculate the optimum
size of a <type>GHashTable</type>.
</para>
<para>The built-in array of primes ranges from 11 to 13845163 such that
each prime is approximately 1.5-2 times the previous prime.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>num</para></td><td class="parameter_description"><para>a <type>guint</type></para><para>Passed as <code>num</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>spawn-async</title><informalexample><programlisting>(define-values
  (%return child-pid)
  (spawn-async working-directory argv envp flags child-setup user-data))
</programlisting></informalexample><para>See <function>g_spawn_async_with_pipes()</function> for a full description; this function
simply calls the <function>g_spawn_async_with_pipes()</function> without any pipes.
</para>
<para>You should call <function>g_spawn_close_pid()</function> on the returned child process
reference when you don't need it any more.
</para>
<para>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 <type>GdkAppLaunchContext</type>,
<type>GAppLaunchContext</type>, or set the <constant>DISPLAY</constant> environment variable.
</para>
<para>Note that the returned <parameter>child_pid</parameter> on Windows is a handle to the child
process and not its identifier. Process handles and process identifiers
are different concepts on Windows.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>working_directory</para></td><td class="parameter_description"><para>child's current working
    directory, or <constant>NULL</constant> to inherit parent's</para><para>Passed as <code>working-directory</code></para></td></tr><tr><td class="parameter_name"><para>argv</para></td><td class="parameter_description"><para>
    <para>child's argument vector</para></para><para>Passed as <code>argv</code></para></td></tr><tr><td class="parameter_name"><para>envp</para></td><td class="parameter_description"><para>
    <para>child's environment, or <constant>NULL</constant> to inherit parent's</para></para><para>Passed as <code>envp</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags from <type>GSpawnFlags</type></para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>child_setup</para></td><td class="parameter_description"><para>function to run in the child just before <function>exec()</function></para><para>Passed as <code>child-setup</code></para></td></tr><tr><td class="parameter_name"><para>user_data</para></td><td class="parameter_description"><para>user data for <parameter>child_setup</parameter></para><para>Passed as <code>user-data</code></para></td></tr><tr><td class="parameter_name"><para>child_pid</para></td><td class="parameter_description"><para>return location for child process reference, or <constant>NULL</constant></para><para>Passed as <code>child-pid</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>spawn-async-with-fds</title><informalexample><programlisting>(define-values
  (%return child-pid)
  (spawn-async-with-fds
    working-directory
    argv
    envp
    flags
    child-setup
    user-data
    stdin-fd
    stdout-fd
    stderr-fd))
</programlisting></informalexample><para>Identical to <function>g_spawn_async_with_pipes()</function> but instead of
creating pipes for the stdin/stdout/stderr, you can pass existing
file descriptors into this function through the <parameter>stdin_fd</parameter>,
<parameter>stdout_fd</parameter> and <parameter>stderr_fd</parameter> parameters. The following <parameter>flags</parameter>
also have their behaviour slightly tweaked as a result:
</para>
<para><constant>G_SPAWN_STDOUT_TO_DEV_NULL</constant> 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, <parameter>standard_output</parameter> must be -1.
<constant>G_SPAWN_STDERR_TO_DEV_NULL</constant> 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, <parameter>standard_error</parameter> must be -1.
<constant>G_SPAWN_CHILD_INHERITS_STDIN</constant> 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, <parameter>standard_input</parameter> must be -1.
</para>
<para>It is valid to pass the same fd in multiple parameters (e.g. you can pass
a single fd for both stdout and stderr).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>working_directory</para></td><td class="parameter_description"><para>child's current working directory, or <constant>NULL</constant> to inherit parent's, in the GLib file name encoding</para><para>Passed as <code>working-directory</code></para></td></tr><tr><td class="parameter_name"><para>argv</para></td><td class="parameter_description"><para>child's argument vector, in the GLib file name encoding</para><para>Passed as <code>argv</code></para></td></tr><tr><td class="parameter_name"><para>envp</para></td><td class="parameter_description"><para>child's environment, or <constant>NULL</constant> to inherit parent's, in the GLib file name encoding</para><para>Passed as <code>envp</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags from <type>GSpawnFlags</type></para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>child_setup</para></td><td class="parameter_description"><para>function to run in the child just before <function>exec()</function></para><para>Passed as <code>child-setup</code></para></td></tr><tr><td class="parameter_name"><para>user_data</para></td><td class="parameter_description"><para>user data for <parameter>child_setup</parameter></para><para>Passed as <code>user-data</code></para></td></tr><tr><td class="parameter_name"><para>child_pid</para></td><td class="parameter_description"><para>return location for child process ID, or <constant>NULL</constant></para><para>Passed as <code>child-pid</code></para></td></tr><tr><td class="parameter_name"><para>stdin_fd</para></td><td class="parameter_description"><para>file descriptor to use for child's stdin, or -1</para><para>Passed as <code>stdin-fd</code></para></td></tr><tr><td class="parameter_name"><para>stdout_fd</para></td><td class="parameter_description"><para>file descriptor to use for child's stdout, or -1</para><para>Passed as <code>stdout-fd</code></para></td></tr><tr><td class="parameter_name"><para>stderr_fd</para></td><td class="parameter_description"><para>file descriptor to use for child's stderr, or -1</para><para>Passed as <code>stderr-fd</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>spawn-async-with-pipes</title><informalexample><programlisting>(define-values
  (%return child-pid standard-input standard-output standard-error)
  (spawn-async-with-pipes
    working-directory
    argv
    envp
    flags
    child-setup
    user-data))
</programlisting></informalexample><para>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, <parameter>argv</parameter>.
<parameter>argv</parameter> should be a <constant>NULL</constant>-terminated array of strings, to be passed
as the argument vector for the child. The first string in <parameter>argv</parameter>
is of course the name of the program to execute. By default, the
name of the program must be a full path. If <parameter>flags</parameter> contains the
<constant>G_SPAWN_SEARCH_PATH</constant> flag, the <code>PATH</code> environment variable is
used to search for the executable. If <parameter>flags</parameter> contains the
<constant>G_SPAWN_SEARCH_PATH_FROM_ENVP</constant> flag, the <code>PATH</code> variable from
<parameter>envp</parameter> is used to search for the executable. If both the
<constant>G_SPAWN_SEARCH_PATH</constant> and <constant>G_SPAWN_SEARCH_PATH_FROM_ENVP</constant> flags
are set, the <code>PATH</code> variable from <parameter>envp</parameter> takes precedence over
the environment variable.
</para>
<para>If the program name is not a full path and <constant>G_SPAWN_SEARCH_PATH</constant> flag is not
used, then the program will be run from the current directory (or
<parameter>working_directory</parameter>, if specified); this might be unexpected or even
dangerous in some cases when the current directory is world-writable.
</para>
<para>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 <function>wmain()</function> instead of
<function>main()</function>. <function>wmain()</function> has a wide character argument vector as parameter.
</para>
<para>At least currently, mingw doesn't support <function>wmain()</function>, so if you use
mingw to develop the spawned program, it should call
<function>g_win32_get_command_line()</function> to get arguments in UTF-8.
</para>
<para>On Windows the low-level child process creation API <function>CreateProcess()</function>
doesn't use argument vectors, but a command line. The C runtime
library's spawn*() family of functions (which <function>g_spawn_async_with_pipes()</function>
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 <function>main()</function>. Complications arise when you have argument vector
elements that contain spaces or double quotes. The <code>spawn*()</code> 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, <function>g_spawn_async_with_pipes()</function> will do quoting and escaping on
argument vector elements that need it before calling the C runtime
<function>spawn()</function> function.
</para>
<para>The returned <parameter>child_pid</parameter> on Windows is a handle to the child
process, not its identifier. Process handles and process
identifiers are different concepts on Windows.
</para>
<para><parameter>envp</parameter> is a <constant>NULL</constant>-terminated array of strings, where each string
has the form <code>KEY=VALUE</code>. This will become the child's environment.
If <parameter>envp</parameter> is <constant>NULL</constant>, the child inherits its parent's environment.
</para>
<para><parameter>flags</parameter> should be the bitwise OR of any flags you want to affect the
function's behaviour. The <constant>G_SPAWN_DO_NOT_REAP_CHILD</constant> means that the
child will not automatically be reaped; you must use a child watch
(<function>g_child_watch_add()</function>) 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 <function>g_spawn_close_pid()</function> on the <parameter>child_pid</parameter>, in order to
free resources which may be associated with the child process. (On Unix,
using a child watch is equivalent to calling <function>waitpid()</function> or handling
the <constant>SIGCHLD</constant> signal manually. On Windows, calling <function>g_spawn_close_pid()</function>
is equivalent to calling <function>CloseHandle()</function> on the process handle returned
in <parameter>child_pid</parameter>). See <function>g_child_watch_add()</function>.
</para>
<para>Open UNIX file descriptors marked as <code>FD_CLOEXEC</code> will be automatically
closed in the child process. <constant>G_SPAWN_LEAVE_DESCRIPTORS_OPEN</constant> means that
other open file descriptors will be inherited by the child; otherwise all
descriptors except stdin/stdout/stderr will be closed before calling <function>exec()</function>
in the child. <constant>G_SPAWN_SEARCH_PATH</constant> means that <parameter>argv</parameter>[0] need not be an
absolute path, it will be looked for in the <code>PATH</code> environment
variable. <constant>G_SPAWN_SEARCH_PATH_FROM_ENVP</constant> means need not be an
absolute path, it will be looked for in the <code>PATH</code> variable from
<parameter>envp</parameter>. If both <constant>G_SPAWN_SEARCH_PATH</constant> and <constant>G_SPAWN_SEARCH_PATH_FROM_ENVP</constant>
are used, the value from <parameter>envp</parameter> takes precedence over the environment.
<constant>G_SPAWN_STDOUT_TO_DEV_NULL</constant> 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, <parameter>standard_output</parameter> must be <constant>NULL</constant>.
<constant>G_SPAWN_STDERR_TO_DEV_NULL</constant> 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, <parameter>standard_error</parameter> must be <constant>NULL</constant>.
<constant>G_SPAWN_CHILD_INHERITS_STDIN</constant> means that the child will inherit the parent's
standard input (by default, the child's standard input is attached to
<code>/dev/null</code>). If you use this flag, <parameter>standard_input</parameter> must be <constant>NULL</constant>.
<constant>G_SPAWN_FILE_AND_ARGV_ZERO</constant> means that the first element of <parameter>argv</parameter> is
the file to execute, while the remaining elements are the actual
argument vector to pass to the file. Normally <function>g_spawn_async_with_pipes()</function>
uses <parameter>argv</parameter>[0] as the file to execute, and passes all of <parameter>argv</parameter> to the child.
</para>
<para><parameter>child_setup</parameter> and <parameter>user_data</parameter> 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 <function>exec()</function>.
That is, <parameter>child_setup</parameter> is called just before calling <function>exec()</function> in the
child. Obviously actions taken in this function will only affect
the child, not the parent.
</para>
<para>On Windows, there is no separate <function>fork()</function> and <function>exec()</function> functionality.
Child processes are created and run with a single API call,
<function>CreateProcess()</function>. There is no sensible thing <parameter>child_setup</parameter>
could be used for on Windows so it is ignored and not called.
</para>
<para>If non-<constant>NULL</constant>, <parameter>child_pid</parameter> 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 <function>g_child_watch_add()</function> (or <function>waitpid()</function>) if you specified the
<constant>G_SPAWN_DO_NOT_REAP_CHILD</constant> flag. On Windows, <parameter>child_pid</parameter> will be
filled with a handle to the child process only if you specified the
<constant>G_SPAWN_DO_NOT_REAP_CHILD</constant> 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
<function>GetExitCodeProcess()</function>. You should close the handle with <function>CloseHandle()</function>
or <function>g_spawn_close_pid()</function> when you no longer need it.
</para>
<para>If non-<constant>NULL</constant>, the <parameter>standard_input</parameter>, <parameter>standard_output</parameter>, <parameter>standard_error</parameter>
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 <function>g_spawn_async_with_pipes()</function> must close these file descriptors
when they are no longer in use. If these parameters are <constant>NULL</constant>, the
corresponding pipe won't be created.
</para>
<para>If <parameter>standard_input</parameter> is <constant>NULL</constant>, the child's standard input is attached to
<code>/dev/null</code> unless <constant>G_SPAWN_CHILD_INHERITS_STDIN</constant> is set.
</para>
<para>If <parameter>standard_error</parameter> is NULL, the child's standard error goes to the same
location as the parent's standard error unless <constant>G_SPAWN_STDERR_TO_DEV_NULL</constant>
is set.
</para>
<para>If <parameter>standard_output</parameter> is NULL, the child's standard output goes to the same
location as the parent's standard output unless <constant>G_SPAWN_STDOUT_TO_DEV_NULL</constant>
is set.
</para>
<para><parameter>error</parameter> can be <constant>NULL</constant> to ignore errors, or non-<constant>NULL</constant> to report errors.
If an error is set, the function returns <constant>FALSE</constant>. Errors are reported
even if they occur in the child (for example if the executable in
<parameter>argv</parameter>[0] is not found). Typically the <code>message</code> field of returned
errors should be displayed to users. Possible errors are those from
the <type>G_SPAWN_ERROR</type> domain.
</para>
<para>If an error occurs, <parameter>child_pid</parameter>, <parameter>standard_input</parameter>, <parameter>standard_output</parameter>,
and <parameter>standard_error</parameter> will not be filled with valid values.
</para>
<para>If <parameter>child_pid</parameter> is not <constant>NULL</constant> and an error does not occur then the returned
process reference must be closed using <function>g_spawn_close_pid()</function>.
</para>
<para>On modern UNIX platforms, GLib can use an efficient process launching
codepath driven internally by <function>posix_spawn()</function>. 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:
</para>
<para>1. <constant>G_SPAWN_DO_NOT_REAP_CHILD</constant> is set
2. <constant>G_SPAWN_LEAVE_DESCRIPTORS_OPEN</constant> is set
3. <constant>G_SPAWN_SEARCH_PATH_FROM_ENVP</constant> is not set
4. <parameter>working_directory</parameter> is <constant>NULL</constant>
5. <parameter>child_setup</parameter> is <constant>NULL</constant>
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.
</para>
<para>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 <type>GdkAppLaunchContext</type>,
<type>GAppLaunchContext</type>, or set the <constant>DISPLAY</constant> environment variable.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>working_directory</para></td><td class="parameter_description"><para>child's current working
    directory, or <constant>NULL</constant> to inherit parent's, in the GLib file name encoding</para><para>Passed as <code>working-directory</code></para></td></tr><tr><td class="parameter_name"><para>argv</para></td><td class="parameter_description"><para>child's argument
    vector, in the GLib file name encoding</para><para>Passed as <code>argv</code></para></td></tr><tr><td class="parameter_name"><para>envp</para></td><td class="parameter_description"><para>
    <para>child's environment, or <constant>NULL</constant> to inherit parent's, in the GLib file
    name encoding</para></para><para>Passed as <code>envp</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags from <type>GSpawnFlags</type></para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>child_setup</para></td><td class="parameter_description"><para>function to run in the child just before <function>exec()</function></para><para>Passed as <code>child-setup</code></para></td></tr><tr><td class="parameter_name"><para>user_data</para></td><td class="parameter_description"><para>user data for <parameter>child_setup</parameter></para><para>Passed as <code>user-data</code></para></td></tr><tr><td class="parameter_name"><para>child_pid</para></td><td class="parameter_description"><para>return location for child process ID, or <constant>NULL</constant></para><para>Passed as <code>child-pid</code></para></td></tr><tr><td class="parameter_name"><para>standard_input</para></td><td class="parameter_description"><para>return location for file descriptor to write to child's stdin, or <constant>NULL</constant></para><para>Passed as <code>standard-input</code></para></td></tr><tr><td class="parameter_name"><para>standard_output</para></td><td class="parameter_description"><para>return location for file descriptor to read child's stdout, or <constant>NULL</constant></para><para>Passed as <code>standard-output</code></para></td></tr><tr><td class="parameter_name"><para>standard_error</para></td><td class="parameter_description"><para>return location for file descriptor to read child's stderr, or <constant>NULL</constant></para><para>Passed as <code>standard-error</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>spawn-check-exit-status?</title><informalexample><programlisting>(define-values (%return) (spawn-check-exit-status? wait-status))
</programlisting></informalexample><para>Set <parameter>error</parameter> if <parameter>exit_status</parameter> indicates the child exited abnormally
(e.g. with a nonzero exit code, or via a fatal signal).
</para>
<para>The <function>g_spawn_sync()</function> and <function>g_child_watch_add()</function> 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 <function>waitpid()</function> returns,
and on Windows it is guaranteed to be the result of <function>GetExitCodeProcess()</function>.
</para>
<para>Prior to the introduction of this function in GLib 2.34, interpreting
<parameter>exit_status</parameter> required use of platform-specific APIs, which is problematic
for software using GLib as a cross-platform layer.
</para>
<para>Additionally, many programs simply want to determine whether or not
the child exited successfully, and either propagate a <type>GError</type> or
print a message to standard error. In that common case, this function
can be used. Note that the error message in <parameter>error</parameter> will contain
human-readable information about the exit status.
</para>
<para>The <parameter>domain</parameter> and <parameter>code</parameter> of <parameter>error</parameter> have special semantics in the case
where the process has an &quot;exit code&quot;, as opposed to being killed by
a signal. On Unix, this happens if <function>WIFEXITED()</function> would be true of
<parameter>exit_status</parameter>. On Windows, it is always the case.
</para>
<para>The special semantics are that the actual exit code will be the
code set in <parameter>error</parameter>, and the domain will be <constant>G_SPAWN_EXIT_ERROR</constant>.
This allows you to differentiate between different exit codes.
</para>
<para>If the process was terminated by some means other than an exit
status, the domain will be <constant>G_SPAWN_ERROR</constant>, and the code will be
<constant>G_SPAWN_ERROR_FAILED</constant>.
</para>
<para>This function just offers convenience; you can of course also check
the available platform via a macro such as <constant>G_OS_UNIX</constant>, and use
<function>WIFEXITED()</function> and <function>WEXITSTATUS()</function> on <parameter>exit_status</parameter> directly. Do not attempt
to scan or parse the error message string; it may be translated and/or
change in future versions of GLib.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>wait_status</para></td><td class="parameter_description"><para></para><para>Passed as <code>wait-status</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>spawn-check-wait-status?</title><informalexample><programlisting>(define-values (%return) (spawn-check-wait-status? wait-status))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>wait_status</para></td><td class="parameter_description"><para></para><para>Passed as <code>wait-status</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>spawn-close-pid</title><informalexample><programlisting>(define-values () (spawn-close-pid pid))
</programlisting></informalexample><para>On some platforms, notably Windows, the <type>GPid</type> type represents a resource
which must be closed to prevent resource leaking. <function>g_spawn_close_pid()</function>
is provided for this purpose. It should be used on all platforms, even
though it doesn't do anything under UNIX.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>pid</para></td><td class="parameter_description"><para>The process reference to close</para><para>Passed as <code>pid</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>spawn-command-line-async?</title><informalexample><programlisting>(define-values (%return) (spawn-command-line-async? command-line))
</programlisting></informalexample><para>A simple version of <function>g_spawn_async()</function> that parses a command line with
<function>g_shell_parse_argv()</function> and passes it to <function>g_spawn_async()</function>. Runs a
command line in the background. Unlike <function>g_spawn_async()</function>, the
<constant>G_SPAWN_SEARCH_PATH</constant> flag is enabled, other flags are not. Note
that <constant>G_SPAWN_SEARCH_PATH</constant> can have security implications, so
consider using <function>g_spawn_async()</function> directly if appropriate. Possible
errors are those from <function>g_shell_parse_argv()</function> and <function>g_spawn_async()</function>.
</para>
<para>The same concerns on Windows apply as for <function>g_spawn_command_line_sync()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>command_line</para></td><td class="parameter_description"><para>a command line</para><para>Passed as <code>command-line</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>spawn-command-line-sync</title><informalexample><programlisting>(define-values
  (%return standard-output standard-error)
  (spawn-command-line-sync command-line wait-status))
</programlisting></informalexample><para>A simple version of <function>g_spawn_sync()</function> with little-used parameters
removed, taking a command line instead of an argument vector.  See
<function>g_spawn_sync()</function> for full details. <parameter>command_line</parameter> will be parsed by
<function>g_shell_parse_argv()</function>. Unlike <function>g_spawn_sync()</function>, the <constant>G_SPAWN_SEARCH_PATH</constant> flag
is enabled. Note that <constant>G_SPAWN_SEARCH_PATH</constant> can have security
implications, so consider using <function>g_spawn_sync()</function> directly if
appropriate. Possible errors are those from <function>g_spawn_sync()</function> and those
from <function>g_shell_parse_argv()</function>.
</para>
<para>If <parameter>exit_status</parameter> is non-<constant>NULL</constant>, the platform-specific exit status of
the child is stored there; see the documentation of
<function>g_spawn_check_exit_status()</function> for how to use and interpret this.
</para>
<para>On Windows, please note the implications of <function>g_shell_parse_argv()</function>
parsing <parameter>command_line</parameter>. 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 <parameter>command_line</parameter> containing
canonical Windows paths, like &quot;c:\\program files\\app\\app.exe&quot;, as
the backslashes will be eaten, and the space will act as a
separator. You need to enclose such paths with single quotes, like
&quot;'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'&quot;.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>command_line</para></td><td class="parameter_description"><para>a command line</para><para>Passed as <code>command-line</code></para></td></tr><tr><td class="parameter_name"><para>standard_output</para></td><td class="parameter_description"><para>return location for child output</para><para>Passed as <code>standard-output</code></para></td></tr><tr><td class="parameter_name"><para>standard_error</para></td><td class="parameter_description"><para>return location for child errors</para><para>Passed as <code>standard-error</code></para></td></tr><tr><td class="parameter_name"><para>wait_status</para></td><td class="parameter_description"><para></para><para>Passed as <code>wait-status</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>spawn-error-quark</title><informalexample><programlisting>(define-values (%return) (spawn-error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>spawn-exit-error-quark</title><informalexample><programlisting>(define-values (%return) (spawn-exit-error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>spawn-sync</title><informalexample><programlisting>(define-values
  (%return standard-output standard-error)
  (spawn-sync
    working-directory
    argv
    envp
    flags
    child-setup
    user-data
    wait-status))
</programlisting></informalexample><para>Executes a child synchronously (waits for the child to exit before returning).
All output from the child is stored in <parameter>standard_output</parameter> and <parameter>standard_error</parameter>,
if those parameters are non-<constant>NULL</constant>. Note that you must set the
<constant>G_SPAWN_STDOUT_TO_DEV_NULL</constant> and <constant>G_SPAWN_STDERR_TO_DEV_NULL</constant> flags when
passing <constant>NULL</constant> for <parameter>standard_output</parameter> and <parameter>standard_error</parameter>.
</para>
<para>If <parameter>exit_status</parameter> is non-<constant>NULL</constant>, the platform-specific exit status of
the child is stored there; see the documentation of
<function>g_spawn_check_exit_status()</function> for how to use and interpret this.
Note that it is invalid to pass <constant>G_SPAWN_DO_NOT_REAP_CHILD</constant> in
<parameter>flags</parameter>, and on POSIX platforms, the same restrictions as for
<function>g_child_watch_source_new()</function> apply.
</para>
<para>If an error occurs, no data is returned in <parameter>standard_output</parameter>,
<parameter>standard_error</parameter>, or <parameter>exit_status</parameter>.
</para>
<para>This function calls <function>g_spawn_async_with_pipes()</function> internally; see that
function for full details on the other parameters and details on
how these functions work on Windows.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>working_directory</para></td><td class="parameter_description"><para>child's current working
    directory, or <constant>NULL</constant> to inherit parent's</para><para>Passed as <code>working-directory</code></para></td></tr><tr><td class="parameter_name"><para>argv</para></td><td class="parameter_description"><para>
    <para>child's argument vector</para></para><para>Passed as <code>argv</code></para></td></tr><tr><td class="parameter_name"><para>envp</para></td><td class="parameter_description"><para>
    <para>child's environment, or <constant>NULL</constant> to inherit parent's</para></para><para>Passed as <code>envp</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags from <type>GSpawnFlags</type></para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>child_setup</para></td><td class="parameter_description"><para>function to run in the child just before <function>exec()</function></para><para>Passed as <code>child-setup</code></para></td></tr><tr><td class="parameter_name"><para>user_data</para></td><td class="parameter_description"><para>user data for <parameter>child_setup</parameter></para><para>Passed as <code>user-data</code></para></td></tr><tr><td class="parameter_name"><para>standard_output</para></td><td class="parameter_description"><para>return location for child output, or <constant>NULL</constant></para><para>Passed as <code>standard-output</code></para></td></tr><tr><td class="parameter_name"><para>standard_error</para></td><td class="parameter_description"><para>return location for child error messages, or <constant>NULL</constant></para><para>Passed as <code>standard-error</code></para></td></tr><tr><td class="parameter_name"><para>wait_status</para></td><td class="parameter_description"><para></para><para>Passed as <code>wait-status</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>stpcpy</title><informalexample><programlisting>(define-values (%return) (stpcpy dest src))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dest</para></td><td class="parameter_description"><para>destination buffer.</para><para>Passed as <code>dest</code></para></td></tr><tr><td class="parameter_name"><para>src</para></td><td class="parameter_description"><para>source string.</para><para>Passed as <code>src</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>str-equal?</title><informalexample><programlisting>(define-values (%return) (str-equal? v1 v2))
</programlisting></informalexample><para>Compares two strings for byte-by-byte equality and returns <constant>TRUE</constant>
if they are equal. It can be passed to <function>g_hash_table_new()</function> as the
<parameter>key_equal_func</parameter> parameter, when using non-<constant>NULL</constant> strings as keys in a
<type>GHashTable</type>.
</para>
<para>This function is typically used for hash table comparisons, but can be used
for general purpose comparisons of non-<constant>NULL</constant> strings. For a <constant>NULL</constant>-safe string
comparison function, see <function>g_strcmp0()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>v1</para></td><td class="parameter_description"><para>a key</para><para>Passed as <code>v1</code></para></td></tr><tr><td class="parameter_name"><para>v2</para></td><td class="parameter_description"><para>a key to compare with <parameter>v1</parameter></para><para>Passed as <code>v2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>str-has-prefix?</title><informalexample><programlisting>(define-values (%return) (str-has-prefix? str prefix))
</programlisting></informalexample><para>Looks whether the string <parameter>str</parameter> begins with <parameter>prefix</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a nul-terminated string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>prefix</para></td><td class="parameter_description"><para>the nul-terminated prefix to look for</para><para>Passed as <code>prefix</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>str-has-suffix?</title><informalexample><programlisting>(define-values (%return) (str-has-suffix? str suffix))
</programlisting></informalexample><para>Looks whether the string <parameter>str</parameter> ends with <parameter>suffix</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a nul-terminated string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>suffix</para></td><td class="parameter_description"><para>the nul-terminated suffix to look for</para><para>Passed as <code>suffix</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>str-hash</title><informalexample><programlisting>(define-values (%return) (str-hash v))
</programlisting></informalexample><para>Converts a string to a hash value.
</para>
<para>This function implements the widely used &quot;djb&quot; 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: <code>hash = hash * 33 + c</code>. This function
uses the signed value of each byte.
</para>
<para>It can be passed to <function>g_hash_table_new()</function> as the <parameter>hash_func</parameter> parameter,
when using non-<constant>NULL</constant> strings as keys in a <type>GHashTable</type>.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>v</para></td><td class="parameter_description"><para>a string key</para><para>Passed as <code>v</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>str-is-ascii?</title><informalexample><programlisting>(define-values (%return) (str-is-ascii? str))
</programlisting></informalexample><para>Determines if a string is pure ASCII. A string is pure ASCII if it
contains no bytes with the high bit set.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>str</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>str-match-string?</title><informalexample><programlisting>(define-values
  (%return)
  (str-match-string? search-term potential-hit accept-alternates))
</programlisting></informalexample><para>Checks if a search conducted for <parameter>search_term</parameter> should match
<parameter>potential_hit</parameter>.
</para>
<para>This function calls <function>g_str_tokenize_and_fold()</function> on both
<parameter>search_term</parameter> and <parameter>potential_hit</parameter>.  ASCII alternates are never taken
for <parameter>search_term</parameter> but will be taken for <parameter>potential_hit</parameter> according to
the value of <parameter>accept_alternates</parameter>.
</para>
<para>A hit occurs when each folded token in <parameter>search_term</parameter> is a prefix of a
folded token from <parameter>potential_hit</parameter>.
</para>
<para>Depending on how you're performing the search, it will typically be
faster to call <function>g_str_tokenize_and_fold()</function> on each string in
your corpus and build an index on the returned folded tokens, then
call <function>g_str_tokenize_and_fold()</function> on the search term and
perform lookups into that index.
</para>
<para>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).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>search_term</para></td><td class="parameter_description"><para>the search term from the user</para><para>Passed as <code>search-term</code></para></td></tr><tr><td class="parameter_name"><para>potential_hit</para></td><td class="parameter_description"><para>the text that may be a hit</para><para>Passed as <code>potential-hit</code></para></td></tr><tr><td class="parameter_name"><para>accept_alternates</para></td><td class="parameter_description"><para><constant>TRUE</constant> to accept ASCII alternates</para><para>Passed as <code>accept-alternates</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>str-to-ascii</title><informalexample><programlisting>(define-values (%return) (str-to-ascii str from-locale))
</programlisting></informalexample><para>Transliterate <parameter>str</parameter> to plain ASCII.
</para>
<para>For best results, <parameter>str</parameter> should be in composed normalised form.
</para>
<para>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.
</para>
<para>If the source language of <parameter>str</parameter> is known, it can used to improve the
accuracy of the translation by passing it as <parameter>from_locale</parameter>.  It should
be a valid POSIX locale string (of the form
<code>language[_territory][.codeset][@modifier]</code>).
</para>
<para>If <parameter>from_locale</parameter> is <constant>NULL</constant> then the current locale is used.
</para>
<para>If you want to do translation for no specific locale, and you want it
to be done independently of the currently locale, specify <code>&quot;C&quot;</code> for
<parameter>from_locale</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a string, in UTF-8</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>from_locale</para></td><td class="parameter_description"><para>the source locale, if known</para><para>Passed as <code>from-locale</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>str-tokenize-and-fold</title><informalexample><programlisting>(define-values
  (%return ascii-alternates)
  (str-tokenize-and-fold string translit-locale))
</programlisting></informalexample><para>Tokenises <parameter>string</parameter> and performs folding on each token.
</para>
<para>A token is a non-empty sequence of alphanumeric characters in the
source string, separated by non-alphanumeric characters.  An
&quot;alphanumeric&quot; character for this purpose is one that matches
<function>g_unichar_isalnum()</function> or <function>g_unichar_ismark()</function>.
</para>
<para>Each token is then (Unicode) normalised and case-folded.  If
<parameter>ascii_alternates</parameter> is non-<constant>NULL</constant> and some of the returned tokens
contain non-ASCII characters, ASCII alternatives will be generated.
</para>
<para>The number of ASCII alternatives that are generated and the method
for doing so is unspecified, but <parameter>translit_locale</parameter> (if specified) may
improve the transliteration if the language of the source string is
known.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>translit_locale</para></td><td class="parameter_description"><para>the language code (like 'de' or
  'en_GB') from which <parameter>string</parameter> originates</para><para>Passed as <code>translit-locale</code></para></td></tr><tr><td class="parameter_name"><para>ascii_alternates</para></td><td class="parameter_description"><para>a
  return location for ASCII alternates</para><para>Passed as <code>ascii-alternates</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strcanon</title><informalexample><programlisting>(define-values (%return) (strcanon string valid-chars substitutor))
</programlisting></informalexample><para>For each character in <parameter>string</parameter>, if the character is not in <parameter>valid_chars</parameter>,
replaces the character with <parameter>substitutor</parameter>. Modifies <parameter>string</parameter> in place,
and return <parameter>string</parameter> itself, not a copy. The return value is to allow
nesting such as
<informalexample><programlisting>
  g_ascii_strup (g_strcanon (str, &quot;abc&quot;, '?'))
</programlisting></informalexample></para>

<para>In order to modify a copy, you may use <code>g_strdup()</code>:
<informalexample><programlisting>
  reformatted = g_strcanon (g_strdup (const_str), &quot;abc&quot;, '?');
  ...
  g_free (reformatted);
</programlisting></informalexample></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a nul-terminated array of bytes</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>valid_chars</para></td><td class="parameter_description"><para>bytes permitted in <parameter>string</parameter></para><para>Passed as <code>valid-chars</code></para></td></tr><tr><td class="parameter_name"><para>substitutor</para></td><td class="parameter_description"><para>replacement character for disallowed bytes</para><para>Passed as <code>substitutor</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strchomp</title><informalexample><programlisting>(define-values (%return) (strchomp string))
</programlisting></informalexample><para>Removes trailing whitespace from a string.
</para>
<para>This function doesn't allocate or reallocate any memory;
it modifies <parameter>string</parameter> in place. Therefore, it cannot be used
on statically allocated strings.
</para>
<para>The pointer to <parameter>string</parameter> is returned to allow the nesting of functions.
</para>
<para>Also see <function>g_strchug()</function> and <function>g_strstrip()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a string to remove the trailing whitespace from</para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strchug</title><informalexample><programlisting>(define-values (%return) (strchug string))
</programlisting></informalexample><para>Removes leading whitespace from a string, by moving the rest
of the characters forward.
</para>
<para>This function doesn't allocate or reallocate any memory;
it modifies <parameter>string</parameter> in place. Therefore, it cannot be used on
statically allocated strings.
</para>
<para>The pointer to <parameter>string</parameter> is returned to allow the nesting of functions.
</para>
<para>Also see <function>g_strchomp()</function> and <function>g_strstrip()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a string to remove the leading whitespace from</para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strcmp0</title><informalexample><programlisting>(define-values (%return) (strcmp0 str1 str2))
</programlisting></informalexample><para>Compares <parameter>str1</parameter> and <parameter>str2</parameter> like <function>strcmp()</function>. Handles <constant>NULL</constant>
gracefully by sorting it before non-<constant>NULL</constant> strings.
Comparing two <constant>NULL</constant> pointers returns 0.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str1</para></td><td class="parameter_description"><para>a C string or <constant>NULL</constant></para><para>Passed as <code>str1</code></para></td></tr><tr><td class="parameter_name"><para>str2</para></td><td class="parameter_description"><para>another C string or <constant>NULL</constant></para><para>Passed as <code>str2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strcompress</title><informalexample><programlisting>(define-values (%return) (strcompress source))
</programlisting></informalexample><para>Replaces all escaped characters with their one byte equivalent.
</para>
<para>This function does the reverse conversion of <function>g_strescape()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a string to compress</para><para>Passed as <code>source</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strdelimit</title><informalexample><programlisting>(define-values (%return) (strdelimit string delimiters new-delimiter))
</programlisting></informalexample><para>Converts any delimiter characters in <parameter>string</parameter> to <parameter>new_delimiter</parameter>.
Any characters in <parameter>string</parameter> which are found in <parameter>delimiters</parameter> are
changed to the <parameter>new_delimiter</parameter> character. Modifies <parameter>string</parameter> in place,
and returns <parameter>string</parameter> itself, not a copy. The return value is to
allow nesting such as
<informalexample><programlisting>
  g_ascii_strup (g_strdelimit (str, &quot;abc&quot;, '?'))
</programlisting></informalexample></para>

<para>In order to modify a copy, you may use <code>g_strdup()</code>:
<informalexample><programlisting>
  reformatted = g_strdelimit (g_strdup (const_str), &quot;abc&quot;, '?');
  ...
  g_free (reformatted);
</programlisting></informalexample></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to convert</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>delimiters</para></td><td class="parameter_description"><para>a string containing the current delimiters,
    or <constant>NULL</constant> to use the standard delimiters defined in <type>G_STR_DELIMITERS</type></para><para>Passed as <code>delimiters</code></para></td></tr><tr><td class="parameter_name"><para>new_delimiter</para></td><td class="parameter_description"><para>the new delimiter character</para><para>Passed as <code>new-delimiter</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strdup</title><informalexample><programlisting>(define-values (%return) (strdup str))
</programlisting></informalexample><para>Duplicates a string. If <parameter>str</parameter> is <constant>NULL</constant> it returns <constant>NULL</constant>.
The returned string should be freed with <function>g_free()</function>
when no longer needed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>the string to duplicate</para><para>Passed as <code>str</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strerror</title><informalexample><programlisting>(define-values (%return) (strerror errnum))
</programlisting></informalexample><para>Returns a string corresponding to the given error code, e.g. &quot;no
such process&quot;. Unlike <function>strerror()</function>, this always returns a string in
UTF-8 encoding, and the pointer is guaranteed to remain valid for
the lifetime of the process.
</para>
<para>Note that the string may be translated according to the current locale.
</para>
<para>The value of <constant>errno</constant> 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:
<informalexample><programlisting>
  int saved_errno;

  ret = read (blah);
  saved_errno = errno;

  g_strerror (saved_errno);
</programlisting></informalexample></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>errnum</para></td><td class="parameter_description"><para>the system error number. See the standard C <constant>errno</constant>
    documentation</para><para>Passed as <code>errnum</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strescape</title><informalexample><programlisting>(define-values (%return) (strescape source exceptions))
</programlisting></informalexample><para>Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\'
and '&quot;' in the string <parameter>source</parameter> 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 <parameter>exceptions</parameter> are not escaped.
</para>
<para><function>g_strcompress()</function> does the reverse conversion.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>source</para></td><td class="parameter_description"><para>a string to escape</para><para>Passed as <code>source</code></para></td></tr><tr><td class="parameter_name"><para>exceptions</para></td><td class="parameter_description"><para>a string of characters not to escape in <parameter>source</parameter></para><para>Passed as <code>exceptions</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strfreev</title><informalexample><programlisting>(define-values () (strfreev str-array))
</programlisting></informalexample><para>Frees a <constant>NULL</constant>-terminated array of strings, as well as each
string it contains.
</para>
<para>If <parameter>str_array</parameter> is <constant>NULL</constant>, this function simply returns.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str_array</para></td><td class="parameter_description"><para>a <constant>NULL</constant>-terminated array of strings to free</para><para>Passed as <code>str-array</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>string-new</title><informalexample><programlisting>(define-values (%return) (string-new init))
</programlisting></informalexample><para>Creates a new <type>GString</type>, initialized with the given string.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>init</para></td><td class="parameter_description"><para>the initial text to copy into the string, or <constant>NULL</constant> to
start with an empty string</para><para>Passed as <code>init</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>string-new-len</title><informalexample><programlisting>(define-values (%return) (string-new-len init len))
</programlisting></informalexample><para>Creates a new <type>GString</type> with <parameter>len</parameter> bytes of the <parameter>init</parameter> buffer.
Because a length is provided, <parameter>init</parameter> need not be nul-terminated,
and can contain embedded nul bytes.
</para>
<para>Since this function does not stop at nul bytes, it is the caller's
responsibility to ensure that <parameter>init</parameter> has at least <parameter>len</parameter> addressable
bytes.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>init</para></td><td class="parameter_description"><para>initial contents of the string</para><para>Passed as <code>init</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>length of <parameter>init</parameter> to use</para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>string-sized-new</title><informalexample><programlisting>(define-values (%return) (string-sized-new dfl-size))
</programlisting></informalexample><para>Creates a new <type>GString</type>, with enough space for <parameter>dfl_size</parameter>
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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dfl_size</para></td><td class="parameter_description"><para>the default size of the space allocated to
    hold the string</para><para>Passed as <code>dfl-size</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strip-context</title><informalexample><programlisting>(define-values (%return) (strip-context msgid msgval))
</programlisting></informalexample><para>An auxiliary function for <function>gettext()</function> support (see <function>Q_()</function>).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>msgid</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>msgid</code></para></td></tr><tr><td class="parameter_name"><para>msgval</para></td><td class="parameter_description"><para>another string</para><para>Passed as <code>msgval</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strjoinv</title><informalexample><programlisting>(define-values (%return) (strjoinv separator str-array))
</programlisting></informalexample><para>Joins a number of strings together to form one long string, with the
optional <parameter>separator</parameter> inserted between each of them. The returned string
should be freed with <function>g_free()</function>.
</para>
<para>If <parameter>str_array</parameter> has no items, the return value will be an
empty string. If <parameter>str_array</parameter> contains a single item, <parameter>separator</parameter> will not
appear in the resulting string.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>separator</para></td><td class="parameter_description"><para>a string to insert between each of the
    strings, or <constant>NULL</constant></para><para>Passed as <code>separator</code></para></td></tr><tr><td class="parameter_name"><para>str_array</para></td><td class="parameter_description"><para>a <constant>NULL</constant>-terminated array of strings to join</para><para>Passed as <code>str-array</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strlcat</title><informalexample><programlisting>(define-values (%return) (strlcat dest src dest-size))
</programlisting></informalexample><para>Portability wrapper that calls <function>strlcat()</function> on systems which have it,
and emulates it otherwise. Appends nul-terminated <parameter>src</parameter> string to <parameter>dest</parameter>,
guaranteeing nul-termination for <parameter>dest</parameter>. The total size of <parameter>dest</parameter> won't
exceed <parameter>dest_size</parameter>.
</para>
<para>At most <parameter>dest_size</parameter> - 1 characters will be copied. Unlike <function>strncat()</function>,
<parameter>dest_size</parameter> is the full size of dest, not the space left over. This
function does not allocate memory. It always nul-terminates (unless
<parameter>dest_size</parameter> == 0 or there were no nul characters in the <parameter>dest_size</parameter>
characters of dest to start with).
</para>
<para>Caveat: this is supposedly a more secure alternative to <function>strcat()</function> or
<function>strncat()</function>, but for real security <function>g_strconcat()</function> is harder to mess up.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dest</para></td><td class="parameter_description"><para>destination buffer, already containing one nul-terminated string</para><para>Passed as <code>dest</code></para></td></tr><tr><td class="parameter_name"><para>src</para></td><td class="parameter_description"><para>source buffer</para><para>Passed as <code>src</code></para></td></tr><tr><td class="parameter_name"><para>dest_size</para></td><td class="parameter_description"><para>length of <parameter>dest</parameter> buffer in bytes (not length of existing string
    inside <parameter>dest</parameter>)</para><para>Passed as <code>dest-size</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strlcpy</title><informalexample><programlisting>(define-values (%return) (strlcpy dest src dest-size))
</programlisting></informalexample><para>Portability wrapper that calls <function>strlcpy()</function> on systems which have it,
and emulates <function>strlcpy()</function> otherwise. Copies <parameter>src</parameter> to <parameter>dest</parameter>; <parameter>dest</parameter> is
guaranteed to be nul-terminated; <parameter>src</parameter> must be nul-terminated;
<parameter>dest_size</parameter> is the buffer size, not the number of bytes to copy.
</para>
<para>At most <parameter>dest_size</parameter> - 1 characters will be copied. Always nul-terminates
(unless <parameter>dest_size</parameter> is 0). This function does not allocate memory. Unlike
<function>strncpy()</function>, this function doesn't pad <parameter>dest</parameter> (so it's often faster). It
returns the size of the attempted result, strlen (src), so if
<parameter>retval</parameter> &gt;= <parameter>dest_size</parameter>, truncation occurred.
</para>
<para>Caveat: <function>strlcpy()</function> is supposedly more secure than <function>strcpy()</function> or <function>strncpy()</function>,
but if you really want to avoid screwups, <function>g_strdup()</function> is an even better
idea.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dest</para></td><td class="parameter_description"><para>destination buffer</para><para>Passed as <code>dest</code></para></td></tr><tr><td class="parameter_name"><para>src</para></td><td class="parameter_description"><para>source buffer</para><para>Passed as <code>src</code></para></td></tr><tr><td class="parameter_name"><para>dest_size</para></td><td class="parameter_description"><para>length of <parameter>dest</parameter> in bytes</para><para>Passed as <code>dest-size</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strndup</title><informalexample><programlisting>(define-values (%return) (strndup str n))
</programlisting></informalexample><para>Duplicates the first <parameter>n</parameter> bytes of a string, returning a newly-allocated
buffer <parameter>n</parameter> + 1 bytes long which will always be nul-terminated. If <parameter>str</parameter>
is less than <parameter>n</parameter> bytes long the buffer is padded with nuls. If <parameter>str</parameter> is
<constant>NULL</constant> it returns <constant>NULL</constant>. The returned value should be freed when no longer
needed.
</para>
<para>To copy a number of characters from a UTF-8 encoded string,
use <function>g_utf8_strncpy()</function> instead.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>the string to duplicate</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>n</para></td><td class="parameter_description"><para>the maximum number of bytes to copy from <parameter>str</parameter></para><para>Passed as <code>n</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strnfill</title><informalexample><programlisting>(define-values (%return) (strnfill length fill-char))
</programlisting></informalexample><para>Creates a new string <parameter>length</parameter> bytes long filled with <parameter>fill_char</parameter>.
The returned string should be freed when no longer needed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of the new string</para><para>Passed as <code>length</code></para></td></tr><tr><td class="parameter_name"><para>fill_char</para></td><td class="parameter_description"><para>the byte to fill the string with</para><para>Passed as <code>fill-char</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strreverse</title><informalexample><programlisting>(define-values (%return) (strreverse string))
</programlisting></informalexample><para>Reverses all of the bytes in a string. For example,
<code>g_strreverse (&quot;abcdef&quot;)</code> will result in &quot;fedcba&quot;.
</para>
<para>Note that <function>g_strreverse()</function> doesn't work on UTF-8 strings
containing multibyte characters. For that purpose, use
<function>g_utf8_strreverse()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>the string to reverse</para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strrstr</title><informalexample><programlisting>(define-values (%return) (strrstr haystack needle))
</programlisting></informalexample><para>Searches the string <parameter>haystack</parameter> for the last occurrence
of the string <parameter>needle</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>haystack</para></td><td class="parameter_description"><para>a nul-terminated string</para><para>Passed as <code>haystack</code></para></td></tr><tr><td class="parameter_name"><para>needle</para></td><td class="parameter_description"><para>the nul-terminated string to search for</para><para>Passed as <code>needle</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strrstr-len</title><informalexample><programlisting>(define-values (%return) (strrstr-len haystack haystack-len needle))
</programlisting></informalexample><para>Searches the string <parameter>haystack</parameter> for the last occurrence
of the string <parameter>needle</parameter>, limiting the length of the search
to <parameter>haystack_len</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>haystack</para></td><td class="parameter_description"><para>a nul-terminated string</para><para>Passed as <code>haystack</code></para></td></tr><tr><td class="parameter_name"><para>haystack_len</para></td><td class="parameter_description"><para>the maximum length of <parameter>haystack</parameter></para><para>Passed as <code>haystack-len</code></para></td></tr><tr><td class="parameter_name"><para>needle</para></td><td class="parameter_description"><para>the nul-terminated string to search for</para><para>Passed as <code>needle</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strsignal</title><informalexample><programlisting>(define-values (%return) (strsignal signum))
</programlisting></informalexample><para>Returns a string describing the given signal, e.g. &quot;Segmentation fault&quot;.
You should use this function in preference to <function>strsignal()</function>, because it
returns a string in UTF-8 encoding, and since not all platforms support
the <function>strsignal()</function> function.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>signum</para></td><td class="parameter_description"><para>the signal number. See the <code>signal</code> documentation</para><para>Passed as <code>signum</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strstr-len</title><informalexample><programlisting>(define-values (%return) (strstr-len haystack haystack-len needle))
</programlisting></informalexample><para>Searches the string <parameter>haystack</parameter> for the first occurrence
of the string <parameter>needle</parameter>, limiting the length of the search
to <parameter>haystack_len</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>haystack</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>haystack</code></para></td></tr><tr><td class="parameter_name"><para>haystack_len</para></td><td class="parameter_description"><para>the maximum length of <parameter>haystack</parameter>. Note that -1 is
    a valid length, if <parameter>haystack</parameter> is nul-terminated, meaning it will
    search through the whole string.</para><para>Passed as <code>haystack-len</code></para></td></tr><tr><td class="parameter_name"><para>needle</para></td><td class="parameter_description"><para>the string to search for</para><para>Passed as <code>needle</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strtod</title><informalexample><programlisting>(define-values (%return endptr) (strtod nptr))
</programlisting></informalexample><para>Converts a string to a <type>gdouble</type> value.
It calls the standard <function>strtod()</function> function to handle the conversion, but
if the string is not completely converted it attempts the conversion
again with <function>g_ascii_strtod()</function>, and returns the best match.
</para>
<para>This function should seldom be used. The normal situation when reading
numbers not for human consumption is to use <function>g_ascii_strtod()</function>. 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>nptr</para></td><td class="parameter_description"><para>the string to convert to a numeric value.</para><para>Passed as <code>nptr</code></para></td></tr><tr><td class="parameter_name"><para>endptr</para></td><td class="parameter_description"><para>if non-<constant>NULL</constant>, it returns the
          character after the last character used in the conversion.</para><para>Passed as <code>endptr</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strv-contains?</title><informalexample><programlisting>(define-values (%return) (strv-contains? strv str))
</programlisting></informalexample><para>Checks if <parameter>strv</parameter> contains <parameter>str</parameter>. <parameter>strv</parameter> must not be <constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>strv</para></td><td class="parameter_description"><para>a <constant>NULL</constant>-terminated array of strings</para><para>Passed as <code>strv</code></para></td></tr><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a string</para><para>Passed as <code>str</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strv-equal?</title><informalexample><programlisting>(define-values (%return) (strv-equal? strv1 strv2))
</programlisting></informalexample><para>Checks if <parameter>strv1</parameter> and <parameter>strv2</parameter> contain exactly the same elements in exactly the
same order. Elements are compared using <function>g_str_equal()</function>. To match independently
of order, sort the arrays first (using <function>g_qsort_with_data()</function> or similar).
</para>
<para>Two empty arrays are considered equal. Neither <parameter>strv1</parameter> not <parameter>strv2</parameter> may be
<constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>strv1</para></td><td class="parameter_description"><para>a <constant>NULL</constant>-terminated array of strings</para><para>Passed as <code>strv1</code></para></td></tr><tr><td class="parameter_name"><para>strv2</para></td><td class="parameter_description"><para>another <constant>NULL</constant>-terminated array of strings</para><para>Passed as <code>strv2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>strv-get-type</title><informalexample><programlisting>(define-values (%return) (strv-get-type))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>strv-length</title><informalexample><programlisting>(define-values (%return) (strv-length str-array))
</programlisting></informalexample><para>Returns the length of the given <constant>NULL</constant>-terminated
string array <parameter>str_array</parameter>. <parameter>str_array</parameter> must not be <constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str_array</para></td><td class="parameter_description"><para>a <constant>NULL</constant>-terminated array of strings</para><para>Passed as <code>str-array</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-add-data-func</title><informalexample><programlisting>(define-values () (test-add-data-func testpath test-data test-func))
</programlisting></informalexample><para>Create a new test case, similar to <function>g_test_create_case()</function>. 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 <parameter>testpath</parameter>. The <parameter>test_data</parameter> argument
will be passed as first argument to <parameter>test_func</parameter>.
</para>
<para>If <parameter>testpath</parameter> includes the component &quot;subprocess&quot; anywhere in it,
the test will be skipped by default, and only run if explicitly
required via the <code>-p</code> command-line option or <function>g_test_trap_subprocess()</function>.
</para>
<para>No component of <parameter>testpath</parameter> may start with a dot (<code>.</code>) if the
<constant>G_TEST_OPTION_ISOLATE_DIRS</constant> option is being used; and it is recommended to
do so even if it isn’t.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>testpath</para></td><td class="parameter_description"><para>/-separated test case path name for the test.</para><para>Passed as <code>testpath</code></para></td></tr><tr><td class="parameter_name"><para>test_data</para></td><td class="parameter_description"><para>Test data argument for the test function.</para><para>Passed as <code>test-data</code></para></td></tr><tr><td class="parameter_name"><para>test_func</para></td><td class="parameter_description"><para>The test function to invoke for this test.</para><para>Passed as <code>test-func</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-add-data-func-full</title><informalexample><programlisting>(define-values
  ()
  (test-add-data-func-full testpath test-data test-func data-free-func))
</programlisting></informalexample><para>Create a new test case, as with <function>g_test_add_data_func()</function>, but freeing
<parameter>test_data</parameter> after the test run is complete.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>testpath</para></td><td class="parameter_description"><para>/-separated test case path name for the test.</para><para>Passed as <code>testpath</code></para></td></tr><tr><td class="parameter_name"><para>test_data</para></td><td class="parameter_description"><para>Test data argument for the test function.</para><para>Passed as <code>test-data</code></para></td></tr><tr><td class="parameter_name"><para>test_func</para></td><td class="parameter_description"><para>The test function to invoke for this test.</para><para>Passed as <code>test-func</code></para></td></tr><tr><td class="parameter_name"><para>data_free_func</para></td><td class="parameter_description"><para><type>GDestroyNotify</type> for <parameter>test_data</parameter>.</para><para>Passed as <code>data-free-func</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-add-func</title><informalexample><programlisting>(define-values () (test-add-func testpath test-func))
</programlisting></informalexample><para>Create a new test case, similar to <function>g_test_create_case()</function>. 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 <parameter>testpath</parameter>.
</para>
<para>If <parameter>testpath</parameter> includes the component &quot;subprocess&quot; anywhere in it,
the test will be skipped by default, and only run if explicitly
required via the <code>-p</code> command-line option or <function>g_test_trap_subprocess()</function>.
</para>
<para>No component of <parameter>testpath</parameter> may start with a dot (<code>.</code>) if the
<constant>G_TEST_OPTION_ISOLATE_DIRS</constant> option is being used; and it is recommended to
do so even if it isn’t.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>testpath</para></td><td class="parameter_description"><para>/-separated test case path name for the test.</para><para>Passed as <code>testpath</code></para></td></tr><tr><td class="parameter_name"><para>test_func</para></td><td class="parameter_description"><para>The test function to invoke for this test.</para><para>Passed as <code>test-func</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-assert-expected-messages-internal</title><informalexample><programlisting>(define-values
  ()
  (test-assert-expected-messages-internal domain file line func))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>domain</para></td><td class="parameter_description"><para></para><para>Passed as <code>domain</code></para></td></tr><tr><td class="parameter_name"><para>file</para></td><td class="parameter_description"><para></para><para>Passed as <code>file</code></para></td></tr><tr><td class="parameter_name"><para>line</para></td><td class="parameter_description"><para></para><para>Passed as <code>line</code></para></td></tr><tr><td class="parameter_name"><para>func</para></td><td class="parameter_description"><para></para><para>Passed as <code>func</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-bug</title><informalexample><programlisting>(define-values () (test-bug bug-uri-snippet))
</programlisting></informalexample><para>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 <function>g_test_bug_base()</function>
and <parameter>bug_uri_snippet</parameter>. If <function>g_test_bug_base()</function> has not been called, it is
assumed to be the empty string, so a full URI can be provided to
<function>g_test_bug()</function> instead.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>bug_uri_snippet</para></td><td class="parameter_description"><para>Bug specific bug tracker URI portion.</para><para>Passed as <code>bug-uri-snippet</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-bug-base</title><informalexample><programlisting>(define-values () (test-bug-base uri-pattern))
</programlisting></informalexample><para>Specify the base URI for bug reports.
</para>
<para>The base URI is used to construct bug report messages for
<function>g_test_message()</function> when <function>g_test_bug()</function> 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 <parameter>uri_pattern</parameter>, or by replacing the special string
'\%s' within <parameter>uri_pattern</parameter> if that is present.
</para>
<para>If <function>g_test_bug_base()</function> is not called, bug URIs are formed solely
from the value provided by <function>g_test_bug()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri_pattern</para></td><td class="parameter_description"><para>the base pattern for bug URIs</para><para>Passed as <code>uri-pattern</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-expect-message</title><informalexample><programlisting>(define-values () (test-expect-message log-domain log-level pattern))
</programlisting></informalexample><para>Indicates that a message with the given <parameter>log_domain</parameter> and <parameter>log_level</parameter>,
with text matching <parameter>pattern</parameter>, is expected to be logged. When this
message is logged, it will not be printed, and the test case will
not abort.
</para>
<para>This API may only be used with the old logging API (<function>g_log()</function> without
<constant>G_LOG_USE_STRUCTURED</constant> defined). It will not work with the structured logging
API. See [Testing for Messages][testing-for-messages].
</para>
<para>Use <function>g_test_assert_expected_messages()</function> to assert that all
previously-expected messages have been seen and suppressed.
</para>
<para>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 <function>g_test_expect_message()</function>.)
</para>
<para>For example:
</para>
<para><informalexample><programlisting>
  // 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,
                         &quot;assertion*acquired_context*failed&quot;);
  g_main_context_push_thread_default (bad_context);
  g_test_assert_expected_messages ();
</programlisting></informalexample></para>

<para>Note that you cannot use this to test <function>g_error()</function> messages, since
<function>g_error()</function> intentionally never returns even if the program doesn't
abort; use <function>g_test_trap_subprocess()</function> in this case.
</para>
<para>If messages at <constant>G_LOG_LEVEL_DEBUG</constant> are emitted, but not explicitly
expected via <function>g_test_expect_message()</function> then they will be ignored.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>log_domain</para></td><td class="parameter_description"><para>the log domain of the message</para><para>Passed as <code>log-domain</code></para></td></tr><tr><td class="parameter_name"><para>log_level</para></td><td class="parameter_description"><para>the log level of the message</para><para>Passed as <code>log-level</code></para></td></tr><tr><td class="parameter_name"><para>pattern</para></td><td class="parameter_description"><para>a glob-style [pattern][glib-Glob-style-pattern-matching]</para><para>Passed as <code>pattern</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-fail</title><informalexample><programlisting>(define-values () (test-fail))
</programlisting></informalexample><para>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.
</para>
<para>Do not use this function if the failure of a test could cause
other tests to malfunction.
</para>
<para>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.
</para>
<para>If not called from inside a test, this function does nothing.</para></refsect2><refsect2><title>test-failed?</title><informalexample><programlisting>(define-values (%return) (test-failed?))
</programlisting></informalexample><para>Returns whether a test has already failed. This will
be the case when <function>g_test_fail()</function>, <function>g_test_incomplete()</function>
or <function>g_test_skip()</function> have been called, but also if an
assertion has failed.
</para>
<para>This can be useful to return early from a test if
continuing after a failed assertion might be harmful.
</para>
<para>The return value of this function is only meaningful
if it is called from inside a test function.</para></refsect2><refsect2><title>test-get-dir</title><informalexample><programlisting>(define-values (%return) (test-get-dir file-type))
</programlisting></informalexample><para>Gets the pathname of the directory containing test files of the type
specified by <parameter>file_type</parameter>.
</para>
<para>This is approximately the same as calling g_test_build_filename(&quot;.&quot;),
but you don't need to free the return value.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>file_type</para></td><td class="parameter_description"><para>the type of file (built vs. distributed)</para><para>Passed as <code>file-type</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-get-path</title><informalexample><programlisting>(define-values (%return) (test-get-path))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>test-incomplete</title><informalexample><programlisting>(define-values () (test-incomplete msg))
</programlisting></informalexample><para>Indicates that a test failed because of some incomplete
functionality. This function can be called multiple times
from the same test.
</para>
<para>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.
</para>
<para>If not called from inside a test, this function does nothing.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>msg</para></td><td class="parameter_description"><para>explanation</para><para>Passed as <code>msg</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-log-type-name</title><informalexample><programlisting>(define-values (%return) (test-log-type-name log-type))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>log_type</para></td><td class="parameter_description"><para></para><para>Passed as <code>log-type</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-queue-destroy</title><informalexample><programlisting>(define-values () (test-queue-destroy destroy-func destroy-data))
</programlisting></informalexample><para>This function enqueus a callback <parameter>destroy_func</parameter> 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 <function>B()</function> to be called before
<function>A()</function> during teardown.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>destroy_func</para></td><td class="parameter_description"><para>Destroy callback for teardown phase.</para><para>Passed as <code>destroy-func</code></para></td></tr><tr><td class="parameter_name"><para>destroy_data</para></td><td class="parameter_description"><para>Destroy callback data.</para><para>Passed as <code>destroy-data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-queue-free</title><informalexample><programlisting>(define-values () (test-queue-free gfree-pointer))
</programlisting></informalexample><para>Enqueue a pointer to be released with <function>g_free()</function> during the next
teardown phase. This is equivalent to calling <function>g_test_queue_destroy()</function>
with a destroy callback of <function>g_free()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>gfree_pointer</para></td><td class="parameter_description"><para>the pointer to be stored.</para><para>Passed as <code>gfree-pointer</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-rand-double</title><informalexample><programlisting>(define-values (%return) (test-rand-double))
</programlisting></informalexample><para>Get a reproducible random floating point number,
see <function>g_test_rand_int()</function> for details on test case random numbers.</para></refsect2><refsect2><title>test-rand-double-range</title><informalexample><programlisting>(define-values (%return) (test-rand-double-range range-start range-end))
</programlisting></informalexample><para>Get a reproducible random floating pointer number out of a specified range,
see <function>g_test_rand_int()</function> for details on test case random numbers.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>range_start</para></td><td class="parameter_description"><para>the minimum value returned by this function</para><para>Passed as <code>range-start</code></para></td></tr><tr><td class="parameter_name"><para>range_end</para></td><td class="parameter_description"><para>the minimum value not returned by this function</para><para>Passed as <code>range-end</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-rand-int</title><informalexample><programlisting>(define-values (%return) (test-rand-int))
</programlisting></informalexample><para>Get a reproducible random integer number.
</para>
<para>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.
</para>
<para>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.</para></refsect2><refsect2><title>test-rand-int-range</title><informalexample><programlisting>(define-values (%return) (test-rand-int-range begin end))
</programlisting></informalexample><para>Get a reproducible random integer number out of a specified range,
see <function>g_test_rand_int()</function> for details on test case random numbers.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>begin</para></td><td class="parameter_description"><para>the minimum value returned by this function</para><para>Passed as <code>begin</code></para></td></tr><tr><td class="parameter_name"><para>end</para></td><td class="parameter_description"><para>the smallest value not to be returned by this function</para><para>Passed as <code>end</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-run</title><informalexample><programlisting>(define-values (%return) (test-run))
</programlisting></informalexample><para>Runs all tests under the toplevel suite which can be retrieved
with <function>g_test_get_root()</function>. Similar to <function>g_test_run_suite()</function>, the test
cases to be run are filtered according to test path arguments
(<code>-p testpath</code> and <code>-s testpath</code>) as parsed by <function>g_test_init()</function>.
<function>g_test_run_suite()</function> or <function>g_test_run()</function> may only be called once in a
program.
</para>
<para>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 <code>g_test_add_*</code>
functions which caused them to create multiple suites with the same
name, meaning that if you created tests &quot;/foo/simple&quot;,
&quot;/bar/simple&quot;, and &quot;/foo/using-bar&quot; in that order, they would get
run in that order (since <function>g_test_run()</function> would run the first &quot;/foo&quot;
suite, then the &quot;/bar&quot; suite, then the second &quot;/foo&quot; suite). As of
2.36, this bug is fixed, and adding the tests in that order would
result in a running order of &quot;/foo/simple&quot;, &quot;/foo/using-bar&quot;,
&quot;/bar/simple&quot;. 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, &quot;/simple/foo&quot;, &quot;/simple/bar&quot;,
&quot;/complex/foo-using-bar&quot;.
</para>
<para>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
<function>g_test_add()</function>, which lets you specify setup and teardown functions.
</para>
<para>If all tests are skipped or marked as incomplete (expected failures),
this function will return 0 if producing TAP output, or 77 (treated
as &quot;skip test&quot; by Automake) otherwise.</para></refsect2><refsect2><title>test-set-nonfatal-assertions</title><informalexample><programlisting>(define-values () (test-set-nonfatal-assertions))
</programlisting></informalexample><para>Changes the behaviour of the various <code>g_assert_*()</code> macros,
<function>g_test_assert_expected_messages()</function> and the various
<code>g_test_trap_assert_*()</code> macros to not abort to program, but instead
call <function>g_test_fail()</function> and continue. (This also changes the behavior of
<function>g_test_fail()</function> so that it will not cause the test program to abort
after completing the failed test.)
</para>
<para>Note that the <function>g_assert_not_reached()</function> and <function>g_assert()</function> macros are not
affected by this.
</para>
<para>This function can only be called after <function>g_test_init()</function>.</para></refsect2><refsect2><title>test-skip</title><informalexample><programlisting>(define-values () (test-skip msg))
</programlisting></informalexample><para>Indicates that a test was skipped.
</para>
<para>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.
</para>
<para>If not called from inside a test, this function does nothing.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>msg</para></td><td class="parameter_description"><para>explanation</para><para>Passed as <code>msg</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-subprocess?</title><informalexample><programlisting>(define-values (%return) (test-subprocess?))
</programlisting></informalexample><para>Returns <constant>TRUE</constant> (after <function>g_test_init()</function> has been called) if the test
program is running under <function>g_test_trap_subprocess()</function>.</para></refsect2><refsect2><title>test-summary</title><informalexample><programlisting>(define-values () (test-summary summary))
</programlisting></informalexample><para>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.
</para>
<para>This should be called at the top of a test function.
</para>
<para>For example:
<informalexample><programlisting>
static void
test_array_sort (void)
{
  g_test_summary (&quot;Test my_array_sort() sorts the array correctly and stably, &quot;
                  &quot;including testing zero length and one-element arrays.&quot;);

  …
}
</programlisting></informalexample></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>summary</para></td><td class="parameter_description"><para>One or two sentences summarising what the test checks, and how it
   checks it.</para><para>Passed as <code>summary</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-timer-elapsed</title><informalexample><programlisting>(define-values (%return) (test-timer-elapsed))
</programlisting></informalexample><para>Get the time since the last start of the timer with <function>g_test_timer_start()</function>.</para></refsect2><refsect2><title>test-timer-last</title><informalexample><programlisting>(define-values (%return) (test-timer-last))
</programlisting></informalexample><para>Report the last result of <function>g_test_timer_elapsed()</function>.</para></refsect2><refsect2><title>test-timer-start</title><informalexample><programlisting>(define-values () (test-timer-start))
</programlisting></informalexample><para>Start a timing test. Call <function>g_test_timer_elapsed()</function> when the task is supposed
to be done. Call this function again to restart the timer.</para></refsect2><refsect2><title>test-trap-assertions</title><informalexample><programlisting>(define-values
  ()
  (test-trap-assertions domain file line func assertion-flags pattern))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>domain</para></td><td class="parameter_description"><para></para><para>Passed as <code>domain</code></para></td></tr><tr><td class="parameter_name"><para>file</para></td><td class="parameter_description"><para></para><para>Passed as <code>file</code></para></td></tr><tr><td class="parameter_name"><para>line</para></td><td class="parameter_description"><para></para><para>Passed as <code>line</code></para></td></tr><tr><td class="parameter_name"><para>func</para></td><td class="parameter_description"><para></para><para>Passed as <code>func</code></para></td></tr><tr><td class="parameter_name"><para>assertion_flags</para></td><td class="parameter_description"><para></para><para>Passed as <code>assertion-flags</code></para></td></tr><tr><td class="parameter_name"><para>pattern</para></td><td class="parameter_description"><para></para><para>Passed as <code>pattern</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>test-trap-has-passed?</title><informalexample><programlisting>(define-values (%return) (test-trap-has-passed?))
</programlisting></informalexample><para>Check the result of the last <function>g_test_trap_subprocess()</function> call.</para></refsect2><refsect2><title>test-trap-reached-timeout?</title><informalexample><programlisting>(define-values (%return) (test-trap-reached-timeout?))
</programlisting></informalexample><para>Check the result of the last <function>g_test_trap_subprocess()</function> call.</para></refsect2><refsect2><title>test-trap-subprocess</title><informalexample><programlisting>(define-values () (test-trap-subprocess test-path usec-timeout test-flags))
</programlisting></informalexample><para>Respawns the test program to run only <parameter>test_path</parameter> in a subprocess.
This can be used for a test case that might not return, or that
might abort.
</para>
<para>If <parameter>test_path</parameter> is <constant>NULL</constant> then the same test is re-run in a subprocess.
You can use <function>g_test_subprocess()</function> to determine whether the test is in
a subprocess or not.
</para>
<para><parameter>test_path</parameter> can also be the name of the parent test, followed by
&quot;`/subprocess/<code>&quot; and then a name for the specific subtest (or just
ending with &quot;</code>/subprocess`&quot; if the test only has one child test);
tests with names of this form will automatically be skipped in the
parent process.
</para>
<para>If <parameter>usec_timeout</parameter> is non-0, the test subprocess is aborted and
considered failing if its run time exceeds it.
</para>
<para>The subprocess behavior can be configured with the
<type>GTestSubprocessFlags</type> flags.
</para>
<para>You can use methods such as <function>g_test_trap_assert_passed()</function>,
<function>g_test_trap_assert_failed()</function>, and <function>g_test_trap_assert_stderr()</function> to
check the results of the subprocess. (But note that
<function>g_test_trap_assert_stdout()</function> and <function>g_test_trap_assert_stderr()</function>
cannot be used if <parameter>test_flags</parameter> specifies that the child should
inherit the parent stdout/stderr.)
</para>
<para>If your <code>main ()</code> needs to behave differently in
the subprocess, you can call <function>g_test_subprocess()</function> (after calling
<function>g_test_init()</function>) to see whether you are in a subprocess.
</para>
<para>The following example tests that calling
<code>my_object_new(1000000)</code> will abort with an error
message.
</para>
<para><informalexample><programlisting>
  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 (&quot;*ERROR*too large*&quot;);
  }

  int
  main (int argc, char **argv)
  {
    g_test_init (&amp;argc, &amp;argv, NULL);

    g_test_add_func (&quot;/myobject/create_large_object&quot;,
                     test_create_large_object);
    return g_test_run ();
  }
</programlisting></informalexample></para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>test_path</para></td><td class="parameter_description"><para>Test to run in a subprocess</para><para>Passed as <code>test-path</code></para></td></tr><tr><td class="parameter_name"><para>usec_timeout</para></td><td class="parameter_description"><para>Timeout for the subprocess test in micro seconds.</para><para>Passed as <code>usec-timeout</code></para></td></tr><tr><td class="parameter_name"><para>test_flags</para></td><td class="parameter_description"><para>Flags to modify subprocess behaviour.</para><para>Passed as <code>test-flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>thread-error-quark</title><informalexample><programlisting>(define-values (%return) (thread-error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>thread-exit</title><informalexample><programlisting>(define-values () (thread-exit retval))
</programlisting></informalexample><para>Terminates the current thread.
</para>
<para>If another thread is waiting for us using <function>g_thread_join()</function> then the
waiting thread will be woken up and get <parameter>retval</parameter> as the return value
of <function>g_thread_join()</function>.
</para>
<para>Calling <function>g_thread_exit()</function> with a parameter <parameter>retval</parameter> is equivalent to
returning <parameter>retval</parameter> from the function <parameter>func</parameter>, as given to <function>g_thread_new()</function>.
</para>
<para>You must only call <function>g_thread_exit()</function> from a thread that you created
yourself with <function>g_thread_new()</function> or related APIs. You must not call
this function from a thread created with another threading library
or or from within a <type>GThreadPool</type>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>retval</para></td><td class="parameter_description"><para>the return value of this thread</para><para>Passed as <code>retval</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>thread-pool-get-max-idle-time</title><informalexample><programlisting>(define-values (%return) (thread-pool-get-max-idle-time))
</programlisting></informalexample><para>This function will return the maximum <parameter>interval</parameter> that a
thread will wait in the thread pool for new tasks before
being stopped.
</para>
<para>If this function returns 0, threads waiting in the thread
pool for new work are not stopped.</para></refsect2><refsect2><title>thread-pool-get-max-unused-threads</title><informalexample><programlisting>(define-values (%return) (thread-pool-get-max-unused-threads))
</programlisting></informalexample><para>Returns the maximal allowed number of unused threads.</para></refsect2><refsect2><title>thread-pool-get-num-unused-threads</title><informalexample><programlisting>(define-values (%return) (thread-pool-get-num-unused-threads))
</programlisting></informalexample><para>Returns the number of currently unused threads.</para></refsect2><refsect2><title>thread-pool-set-max-idle-time</title><informalexample><programlisting>(define-values () (thread-pool-set-max-idle-time interval))
</programlisting></informalexample><para>This function will set the maximum <parameter>interval</parameter> that a thread
waiting in the pool for new tasks can be idle for before
being stopped. This function is similar to calling
<function>g_thread_pool_stop_unused_threads()</function> on a regular timeout,
except this is done on a per thread basis.
</para>
<para>By setting <parameter>interval</parameter> to 0, idle threads will not be stopped.
</para>
<para>The default value is 15000 (15 seconds).</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>interval</para></td><td class="parameter_description"><para>the maximum <parameter>interval</parameter> (in milliseconds)
    a thread can be idle</para><para>Passed as <code>interval</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>thread-pool-set-max-unused-threads</title><informalexample><programlisting>(define-values () (thread-pool-set-max-unused-threads max-threads))
</programlisting></informalexample><para>Sets the maximal number of unused threads to <parameter>max_threads</parameter>.
If <parameter>max_threads</parameter> is -1, no limit is imposed on the number
of unused threads.
</para>
<para>The default value is 2.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>max_threads</para></td><td class="parameter_description"><para>maximal number of unused threads</para><para>Passed as <code>max-threads</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>thread-pool-stop-unused-threads</title><informalexample><programlisting>(define-values () (thread-pool-stop-unused-threads))
</programlisting></informalexample><para>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 <function>g_timeout_add()</function>.</para></refsect2><refsect2><title>thread-self</title><informalexample><programlisting>(define-values (%return) (thread-self))
</programlisting></informalexample><para>This function returns the <type>GThread</type> corresponding to the
current thread. Note that this function does not increase
the reference count of the returned struct.
</para>
<para>This function will return a <type>GThread</type> 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 <function>g_thread_join()</function>) on these threads.</para></refsect2><refsect2><title>thread-yield</title><informalexample><programlisting>(define-values () (thread-yield))
</programlisting></informalexample><para>Causes the calling thread to voluntarily relinquish the CPU, so
that other threads can run.
</para>
<para>This function is often used as a method to make busy wait less evil.</para></refsect2><refsect2><title>timeout-add</title><informalexample><programlisting>(define-values (%return) (timeout-add priority interval function data notify))
</programlisting></informalexample><para>Sets a function to be called at regular intervals, with the default
priority, <type>G_PRIORITY_DEFAULT</type>.  The function is called repeatedly
until it returns <constant>FALSE</constant>, 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 <parameter>interval</parameter>.
</para>
<para>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).
</para>
<para>See [memory management of sources][mainloop-memory-management] for details
on how to handle the return value and memory management of <parameter>data</parameter>.
</para>
<para>If you want to have a timer in the &quot;seconds&quot; range and do not care
about the exact time of the first call of the timer, use the
<function>g_timeout_add_seconds()</function> function; this function allows for more
optimizations and more efficient system power usage.
</para>
<para>This internally creates a main loop source using <function>g_timeout_source_new()</function>
and attaches it to the global <type>GMainContext</type> using <function>g_source_attach()</function>, 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.
</para>
<para>It is safe to call this function from any thread.
</para>
<para>The interval given is in terms of monotonic time, not wall clock
time.  See <function>g_get_monotonic_time()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>notify</para></td><td class="parameter_description"><para></para><para>Passed as <code>notify</code></para></td></tr><tr><td class="parameter_name"><para>priority</para></td><td class="parameter_description"><para></para><para>Passed as <code>priority</code></para></td></tr><tr><td class="parameter_name"><para>interval</para></td><td class="parameter_description"><para>the time between calls to the function, in milliseconds
            (1/1000ths of a second)</para><para>Passed as <code>interval</code></para></td></tr><tr><td class="parameter_name"><para>function</para></td><td class="parameter_description"><para>function to call</para><para>Passed as <code>function</code></para></td></tr><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>data to pass to <parameter>function</parameter></para><para>Passed as <code>data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>timeout-add-seconds</title><informalexample><programlisting>(define-values
  (%return)
  (timeout-add-seconds priority interval function data notify))
</programlisting></informalexample><para>Sets a function to be called at regular intervals with the default
priority, <type>G_PRIORITY_DEFAULT</type>. The function is called repeatedly until
it returns <constant>FALSE</constant>, at which point the timeout is automatically destroyed
and the function will not be called again.
</para>
<para>This internally creates a main loop source using
<function>g_timeout_source_new_seconds()</function> and attaches it to the main loop context
using <function>g_source_attach()</function>. You can do these steps manually if you need
greater control. Also see <function>g_timeout_add_seconds_full()</function>.
</para>
<para>It is safe to call this function from any thread.
</para>
<para>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 <function>g_timeout_add()</function> instead.
</para>
<para>See [memory management of sources][mainloop-memory-management] for details
on how to handle the return value and memory management of <parameter>data</parameter>.
</para>
<para>The interval given is in terms of monotonic time, not wall clock
time.  See <function>g_get_monotonic_time()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>notify</para></td><td class="parameter_description"><para></para><para>Passed as <code>notify</code></para></td></tr><tr><td class="parameter_name"><para>priority</para></td><td class="parameter_description"><para></para><para>Passed as <code>priority</code></para></td></tr><tr><td class="parameter_name"><para>interval</para></td><td class="parameter_description"><para>the time between calls to the function, in seconds</para><para>Passed as <code>interval</code></para></td></tr><tr><td class="parameter_name"><para>function</para></td><td class="parameter_description"><para>function to call</para><para>Passed as <code>function</code></para></td></tr><tr><td class="parameter_name"><para>data</para></td><td class="parameter_description"><para>data to pass to <parameter>function</parameter></para><para>Passed as <code>data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>timeout-source-new</title><informalexample><programlisting>(define-values (%return) (timeout-source-new interval))
</programlisting></informalexample><para>Creates a new timeout source.
</para>
<para>The source will not initially be associated with any <type>GMainContext</type>
and must be added to one with <function>g_source_attach()</function> before it will be
executed.
</para>
<para>The interval given is in terms of monotonic time, not wall clock
time.  See <function>g_get_monotonic_time()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>interval</para></td><td class="parameter_description"><para>the timeout interval in milliseconds.</para><para>Passed as <code>interval</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>timeout-source-new-seconds</title><informalexample><programlisting>(define-values (%return) (timeout-source-new-seconds interval))
</programlisting></informalexample><para>Creates a new timeout source.
</para>
<para>The source will not initially be associated with any <type>GMainContext</type>
and must be added to one with <function>g_source_attach()</function> before it will be
executed.
</para>
<para>The scheduling granularity/accuracy of this timeout source will be
in seconds.
</para>
<para>The interval given is in terms of monotonic time, not wall clock time.
See <function>g_get_monotonic_time()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>interval</para></td><td class="parameter_description"><para>the timeout interval in seconds</para><para>Passed as <code>interval</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>try-malloc</title><informalexample><programlisting>(define-values (%return) (try-malloc n-bytes))
</programlisting></informalexample><para>Attempts to allocate <parameter>n_bytes</parameter>, and returns <constant>NULL</constant> on failure.
Contrast with <function>g_malloc()</function>, which aborts the program on failure.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>n_bytes</para></td><td class="parameter_description"><para>number of bytes to allocate.</para><para>Passed as <code>n-bytes</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>try-malloc0</title><informalexample><programlisting>(define-values (%return) (try-malloc0 n-bytes))
</programlisting></informalexample><para>Attempts to allocate <parameter>n_bytes</parameter>, initialized to 0's, and returns <constant>NULL</constant> on
failure. Contrast with <function>g_malloc0()</function>, which aborts the program on failure.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>n_bytes</para></td><td class="parameter_description"><para>number of bytes to allocate</para><para>Passed as <code>n-bytes</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>try-malloc0-n</title><informalexample><programlisting>(define-values (%return) (try-malloc0-n n-blocks n-block-bytes))
</programlisting></informalexample><para>This function is similar to <function>g_try_malloc0()</function>, allocating (<parameter>n_blocks</parameter> * <parameter>n_block_bytes</parameter>) bytes,
but care is taken to detect possible overflow during multiplication.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>n_blocks</para></td><td class="parameter_description"><para>the number of blocks to allocate</para><para>Passed as <code>n-blocks</code></para></td></tr><tr><td class="parameter_name"><para>n_block_bytes</para></td><td class="parameter_description"><para>the size of each block in bytes</para><para>Passed as <code>n-block-bytes</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>try-malloc-n</title><informalexample><programlisting>(define-values (%return) (try-malloc-n n-blocks n-block-bytes))
</programlisting></informalexample><para>This function is similar to <function>g_try_malloc()</function>, allocating (<parameter>n_blocks</parameter> * <parameter>n_block_bytes</parameter>) bytes,
but care is taken to detect possible overflow during multiplication.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>n_blocks</para></td><td class="parameter_description"><para>the number of blocks to allocate</para><para>Passed as <code>n-blocks</code></para></td></tr><tr><td class="parameter_name"><para>n_block_bytes</para></td><td class="parameter_description"><para>the size of each block in bytes</para><para>Passed as <code>n-block-bytes</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>try-realloc</title><informalexample><programlisting>(define-values (%return) (try-realloc mem n-bytes))
</programlisting></informalexample><para>Attempts to realloc <parameter>mem</parameter> to a new size, <parameter>n_bytes</parameter>, and returns <constant>NULL</constant>
on failure. Contrast with <function>g_realloc()</function>, which aborts the program
on failure.
</para>
<para>If <parameter>mem</parameter> is <constant>NULL</constant>, behaves the same as <function>g_try_malloc()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>mem</para></td><td class="parameter_description"><para>previously-allocated memory, or <constant>NULL</constant>.</para><para>Passed as <code>mem</code></para></td></tr><tr><td class="parameter_name"><para>n_bytes</para></td><td class="parameter_description"><para>number of bytes to allocate.</para><para>Passed as <code>n-bytes</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>try-realloc-n</title><informalexample><programlisting>(define-values (%return) (try-realloc-n mem n-blocks n-block-bytes))
</programlisting></informalexample><para>This function is similar to <function>g_try_realloc()</function>, allocating (<parameter>n_blocks</parameter> * <parameter>n_block_bytes</parameter>) bytes,
but care is taken to detect possible overflow during multiplication.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>mem</para></td><td class="parameter_description"><para>previously-allocated memory, or <constant>NULL</constant>.</para><para>Passed as <code>mem</code></para></td></tr><tr><td class="parameter_name"><para>n_blocks</para></td><td class="parameter_description"><para>the number of blocks to allocate</para><para>Passed as <code>n-blocks</code></para></td></tr><tr><td class="parameter_name"><para>n_block_bytes</para></td><td class="parameter_description"><para>the size of each block in bytes</para><para>Passed as <code>n-block-bytes</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ucs4-to-utf16</title><informalexample><programlisting>(define-values
  (%return items-read items-written)
  (ucs4-to-utf16 str len items-read items-written))
</programlisting></informalexample><para>Convert a string from UCS-4 to UTF-16. A 0 character will be
added to the result after the converted text.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a UCS-4 encoded string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the maximum length (number of characters) of <parameter>str</parameter> to use.
    If <parameter>len</parameter> &lt; 0, then the string is nul-terminated.</para><para>Passed as <code>len</code></para></td></tr><tr><td class="parameter_name"><para>items_read</para></td><td class="parameter_description"><para>location to store number of
    bytes read, or <constant>NULL</constant>. If an error occurs then the index of the invalid
    input is stored here.</para><para>Passed as <code>items-read</code></para></td></tr><tr><td class="parameter_name"><para>items_written</para></td><td class="parameter_description"><para>location to store number
    of <type>gunichar2</type>  written, or <constant>NULL</constant>. The value stored here does not include
    the trailing 0.</para><para>Passed as <code>items-written</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>ucs4-to-utf8</title><informalexample><programlisting>(define-values
  (%return items-read items-written)
  (ucs4-to-utf8 str len items-read items-written))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a UCS-4 encoded string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the maximum length (number of characters) of <parameter>str</parameter> to use.
    If <parameter>len</parameter> &lt; 0, then the string is nul-terminated.</para><para>Passed as <code>len</code></para></td></tr><tr><td class="parameter_name"><para>items_read</para></td><td class="parameter_description"><para>location to store number of
    characters read, or <constant>NULL</constant>.</para><para>Passed as <code>items-read</code></para></td></tr><tr><td class="parameter_name"><para>items_written</para></td><td class="parameter_description"><para>location to store number
    of bytes written or <constant>NULL</constant>. The value here stored does not include the
    trailing 0 byte.</para><para>Passed as <code>items-written</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-break-type</title><informalexample><programlisting>(define-values (%return) (unichar-break-type c))
</programlisting></informalexample><para>Determines the break type of <parameter>c</parameter>. <parameter>c</parameter> should be a Unicode character
(to derive a character from UTF-8 encoded text, use
<function>g_utf8_get_char()</function>). The break type is used to find word and line
breaks (&quot;text boundaries&quot;), Pango implements the Unicode boundary
resolution algorithms and normally you would use a function such
as <function>pango_break()</function> instead of caring about break types yourself.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-combining-class</title><informalexample><programlisting>(define-values (%return) (unichar-combining-class uc))
</programlisting></informalexample><para>Determines the canonical combining class of a Unicode character.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uc</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>uc</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-compose</title><informalexample><programlisting>(define-values (%return ch) (unichar-compose a b))
</programlisting></informalexample><para>Performs a single composition step of the
Unicode canonical composition algorithm.
</para>
<para>This function includes algorithmic Hangul Jamo composition,
but it is not exactly the inverse of <function>g_unichar_decompose()</function>.
No composition can have either of <parameter>a</parameter> or <parameter>b</parameter> 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 &lt;<parameter>a</parameter>,<parameter>b</parameter>&gt;.  See the Unicode
Standard for the definition of Primary Composite.
</para>
<para>If <parameter>a</parameter> and <parameter>b</parameter> do not compose a new character, <parameter>ch</parameter> is set to zero.
</para>
<para>See
[UAX#15](http://unicode.org/reports/tr15/)
for details.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>a</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>a</code></para></td></tr><tr><td class="parameter_name"><para>b</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>b</code></para></td></tr><tr><td class="parameter_name"><para>ch</para></td><td class="parameter_description"><para>return location for the composed character</para><para>Passed as <code>ch</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-decompose</title><informalexample><programlisting>(define-values (%return a b) (unichar-decompose ch))
</programlisting></informalexample><para>Performs a single decomposition step of the
Unicode canonical decomposition algorithm.
</para>
<para>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 *<parameter>b</parameter> will
be set to zero.
</para>
<para>If <parameter>ch</parameter> is not decomposable, *<parameter>a</parameter> is set to <parameter>ch</parameter> and *<parameter>b</parameter>
is set to zero.
</para>
<para>Note that the way Unicode decomposition pairs are
defined, it is guaranteed that <parameter>b</parameter> would not decompose
further, but <parameter>a</parameter> may itself decompose.  To get the full
canonical decomposition for <parameter>ch</parameter>, one would need to
recursively call this function on <parameter>a</parameter>.  Or use
<function>g_unichar_fully_decompose()</function>.
</para>
<para>See
[UAX#15](http://unicode.org/reports/tr15/)
for details.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>ch</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>ch</code></para></td></tr><tr><td class="parameter_name"><para>a</para></td><td class="parameter_description"><para>return location for the first component of <parameter>ch</parameter></para><para>Passed as <code>a</code></para></td></tr><tr><td class="parameter_name"><para>b</para></td><td class="parameter_description"><para>return location for the second component of <parameter>ch</parameter></para><para>Passed as <code>b</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-digit-value</title><informalexample><programlisting>(define-values (%return) (unichar-digit-value c))
</programlisting></informalexample><para>Determines the numeric value of a character as a decimal
digit.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-fully-decompose</title><informalexample><programlisting>(define-values
  (%return result)
  (unichar-fully-decompose ch compat result result-len))
</programlisting></informalexample><para>Computes the canonical or compatibility decomposition of a
Unicode character.  For compatibility decomposition,
pass <constant>TRUE</constant> for <parameter>compat</parameter>; for canonical decomposition
pass <constant>FALSE</constant> for <parameter>compat</parameter>.
</para>
<para>The decomposed sequence is placed in <parameter>result</parameter>.  Only up to
<parameter>result_len</parameter> characters are written into <parameter>result</parameter>.  The length
of the full decomposition (irrespective of <parameter>result_len</parameter>) 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 <constant>G_UNICHAR_MAX_DECOMPOSITION_LENGTH</constant>.
</para>
<para>See
[UAX#15](http://unicode.org/reports/tr15/)
for details.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>ch</para></td><td class="parameter_description"><para>a Unicode character.</para><para>Passed as <code>ch</code></para></td></tr><tr><td class="parameter_name"><para>compat</para></td><td class="parameter_description"><para>whether perform canonical or compatibility decomposition</para><para>Passed as <code>compat</code></para></td></tr><tr><td class="parameter_name"><para>result</para></td><td class="parameter_description"><para>location to store decomposed result, or <constant>NULL</constant></para><para>Passed as <code>result</code></para></td></tr><tr><td class="parameter_name"><para>result_len</para></td><td class="parameter_description"><para>length of <parameter>result</parameter></para><para>Passed as <code>result-len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-get-mirror-char?</title><informalexample><programlisting>(define-values (%return) (unichar-get-mirror-char? ch mirrored-ch))
</programlisting></informalexample><para>In Unicode, some characters are &quot;mirrored&quot;. This means that their
images are mirrored horizontally in text that is laid out from right
to left. For instance, &quot;(&quot; would become its mirror image, &quot;)&quot;, in
right-to-left text.
</para>
<para>If <parameter>ch</parameter> has the Unicode mirrored property and there is another unicode
character that typically has a glyph that is the mirror image of <parameter>ch</parameter>'s
glyph and <parameter>mirrored_ch</parameter> is set, it puts that character in the address
pointed to by <parameter>mirrored_ch</parameter>.  Otherwise the original character is put.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>ch</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>ch</code></para></td></tr><tr><td class="parameter_name"><para>mirrored_ch</para></td><td class="parameter_description"><para>location to store the mirrored character</para><para>Passed as <code>mirrored-ch</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-get-script</title><informalexample><programlisting>(define-values (%return) (unichar-get-script ch))
</programlisting></informalexample><para>Looks up the <type>GUnicodeScript</type> for a particular character (as defined
by Unicode Standard Annex \#24). No check is made for <parameter>ch</parameter> being a
valid Unicode character; if you pass in invalid character, the
result is undefined.
</para>
<para>This function is equivalent to <function>pango_script_for_unichar()</function> and the
two are interchangeable.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>ch</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>ch</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-isalnum?</title><informalexample><programlisting>(define-values (%return) (unichar-isalnum? c))
</programlisting></informalexample><para>Determines whether a character is alphanumeric.
Given some UTF-8 text, obtain a character value
with <function>g_utf8_get_char()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-isalpha?</title><informalexample><programlisting>(define-values (%return) (unichar-isalpha? c))
</programlisting></informalexample><para>Determines whether a character is alphabetic (i.e. a letter).
Given some UTF-8 text, obtain a character value with
<function>g_utf8_get_char()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-iscntrl?</title><informalexample><programlisting>(define-values (%return) (unichar-iscntrl? c))
</programlisting></informalexample><para>Determines whether a character is a control character.
Given some UTF-8 text, obtain a character value with
<function>g_utf8_get_char()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-isdefined?</title><informalexample><programlisting>(define-values (%return) (unichar-isdefined? c))
</programlisting></informalexample><para>Determines if a given character is assigned in the Unicode
standard.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-isdigit?</title><informalexample><programlisting>(define-values (%return) (unichar-isdigit? c))
</programlisting></informalexample><para>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 <function>g_utf8_get_char()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-isgraph?</title><informalexample><programlisting>(define-values (%return) (unichar-isgraph? c))
</programlisting></informalexample><para>Determines whether a character is printable and not a space
(returns <constant>FALSE</constant> for control characters, format characters, and
spaces). <function>g_unichar_isprint()</function> is similar, but returns <constant>TRUE</constant> for
spaces. Given some UTF-8 text, obtain a character value with
<function>g_utf8_get_char()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-islower?</title><informalexample><programlisting>(define-values (%return) (unichar-islower? c))
</programlisting></informalexample><para>Determines whether a character is a lowercase letter.
Given some UTF-8 text, obtain a character value with
<function>g_utf8_get_char()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-ismark?</title><informalexample><programlisting>(define-values (%return) (unichar-ismark? c))
</programlisting></informalexample><para>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 <function>g_utf8_get_char()</function>.
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-isprint?</title><informalexample><programlisting>(define-values (%return) (unichar-isprint? c))
</programlisting></informalexample><para>Determines whether a character is printable.
Unlike <function>g_unichar_isgraph()</function>, returns <constant>TRUE</constant> for spaces.
Given some UTF-8 text, obtain a character value with
<function>g_utf8_get_char()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-ispunct?</title><informalexample><programlisting>(define-values (%return) (unichar-ispunct? c))
</programlisting></informalexample><para>Determines whether a character is punctuation or a symbol.
Given some UTF-8 text, obtain a character value with
<function>g_utf8_get_char()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-isspace?</title><informalexample><programlisting>(define-values (%return) (unichar-isspace? c))
</programlisting></informalexample><para>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 <function>g_utf8_get_char()</function>.
</para>
<para>(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.)</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-istitle?</title><informalexample><programlisting>(define-values (%return) (unichar-istitle? c))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-isupper?</title><informalexample><programlisting>(define-values (%return) (unichar-isupper? c))
</programlisting></informalexample><para>Determines if a character is uppercase.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-iswide?</title><informalexample><programlisting>(define-values (%return) (unichar-iswide? c))
</programlisting></informalexample><para>Determines if a character is typically rendered in a double-width
cell.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-iswide-cjk?</title><informalexample><programlisting>(define-values (%return) (unichar-iswide-cjk? c))
</programlisting></informalexample><para>Determines if a character is typically rendered in a double-width
cell under legacy East Asian locales.  If a character is wide according to
<function>g_unichar_iswide()</function>, then it is also reported wide with this function, but
the converse is not necessarily true. See the
[Unicode Standard Annex <type>11</type>](http://www.unicode.org/reports/tr11/)
for details.
</para>
<para>If a character passes the <function>g_unichar_iswide()</function> test then it will also pass
this test, but not the other way around.  Note that some characters may
pass both this test and <function>g_unichar_iszerowidth()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-isxdigit?</title><informalexample><programlisting>(define-values (%return) (unichar-isxdigit? c))
</programlisting></informalexample><para>Determines if a character is a hexadecimal digit.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character.</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-iszerowidth?</title><informalexample><programlisting>(define-values (%return) (unichar-iszerowidth? c))
</programlisting></informalexample><para>Determines if a given character typically takes zero width when rendered.
The return value is <constant>TRUE</constant> for all non-spacing and enclosing marks
(e.g., combining accents), format characters, zero-width
space, but not U+00AD SOFT HYPHEN.
</para>
<para>A typical use of this function is with one of <function>g_unichar_iswide()</function> or
<function>g_unichar_iswide_cjk()</function> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-to-utf8!</title><informalexample><programlisting>(define-values (%return outbuf) (unichar-to-utf8! c outbuf))
</programlisting></informalexample><para>Converts a single character to UTF-8.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character code</para><para>Passed as <code>c</code></para></td></tr><tr><td class="parameter_name"><para>outbuf</para></td><td class="parameter_description"><para>output buffer, must have at
      least 6 bytes of space. If <constant>NULL</constant>, the length will be computed and
      returned and nothing will be written to <parameter>outbuf</parameter>.</para><para>Passed as <code>outbuf</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-tolower</title><informalexample><programlisting>(define-values (%return) (unichar-tolower c))
</programlisting></informalexample><para>Converts a character to lower case.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character.</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-totitle</title><informalexample><programlisting>(define-values (%return) (unichar-totitle c))
</programlisting></informalexample><para>Converts a character to the titlecase.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-toupper</title><informalexample><programlisting>(define-values (%return) (unichar-toupper c))
</programlisting></informalexample><para>Converts a character to uppercase.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-type</title><informalexample><programlisting>(define-values (%return) (unichar-type c))
</programlisting></informalexample><para>Classifies a Unicode character by type.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-validate?</title><informalexample><programlisting>(define-values (%return) (unichar-validate? ch))
</programlisting></informalexample><para>Checks whether <parameter>ch</parameter> is a valid Unicode character. Some possible
integer values of <parameter>ch</parameter> will not be valid. 0 is considered a valid
character, though it's normally a string terminator.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>ch</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>ch</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unichar-xdigit-value</title><informalexample><programlisting>(define-values (%return) (unichar-xdigit-value c))
</programlisting></informalexample><para>Determines the numeric value of a character as a hexadecimal
digit.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unicode-canonical-ordering</title><informalexample><programlisting>(define-values () (unicode-canonical-ordering string len))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a UCS-4 encoded string.</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the maximum length of <parameter>string</parameter> to use.</para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unicode-script-from-iso15924</title><informalexample><programlisting>(define-values (%return) (unicode-script-from-iso15924 iso15924))
</programlisting></informalexample><para>Looks up the Unicode script for <parameter>iso15924</parameter>.  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 <parameter>guint32</parameter> 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).
</para>
<para>See
[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
for details.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>iso15924</para></td><td class="parameter_description"><para>a Unicode script</para><para>Passed as <code>iso15924</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unicode-script-to-iso15924</title><informalexample><programlisting>(define-values (%return) (unicode-script-to-iso15924 script))
</programlisting></informalexample><para>Looks up the ISO 15924 code for <parameter>script</parameter>.  ISO 15924 assigns four-letter
codes to scripts.  For example, the code for Arabic is 'Arab'.  The
four letter codes are encoded as a <parameter>guint32</parameter> 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).
</para>
<para>See
[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
for details.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>script</para></td><td class="parameter_description"><para>a Unicode script</para><para>Passed as <code>script</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unix-error-quark</title><informalexample><programlisting>(define-values (%return) (unix-error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>unix-fd-add-full</title><informalexample><programlisting>(define-values
  (%return)
  (unix-fd-add-full priority fd condition function user-data notify))
</programlisting></informalexample><para>Sets a function to be called when the IO condition, as specified by
<parameter>condition</parameter> becomes true for <parameter>fd</parameter>.
</para>
<para>This is the same as <function>g_unix_fd_add()</function>, except that it allows you to
specify a non-default priority and a provide a <type>GDestroyNotify</type> for
<parameter>user_data</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>priority</para></td><td class="parameter_description"><para>the priority of the source</para><para>Passed as <code>priority</code></para></td></tr><tr><td class="parameter_name"><para>fd</para></td><td class="parameter_description"><para>a file descriptor</para><para>Passed as <code>fd</code></para></td></tr><tr><td class="parameter_name"><para>condition</para></td><td class="parameter_description"><para>IO conditions to watch for on <parameter>fd</parameter></para><para>Passed as <code>condition</code></para></td></tr><tr><td class="parameter_name"><para>function</para></td><td class="parameter_description"><para>a <type>GUnixFDSourceFunc</type></para><para>Passed as <code>function</code></para></td></tr><tr><td class="parameter_name"><para>user_data</para></td><td class="parameter_description"><para>data to pass to <parameter>function</parameter></para><para>Passed as <code>user-data</code></para></td></tr><tr><td class="parameter_name"><para>notify</para></td><td class="parameter_description"><para>function to call when the idle is removed, or <constant>NULL</constant></para><para>Passed as <code>notify</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unix-fd-source-new</title><informalexample><programlisting>(define-values (%return) (unix-fd-source-new fd condition))
</programlisting></informalexample><para>Creates a <type>GSource</type> to watch for a particular IO condition on a file
descriptor.
</para>
<para>The source will never close the fd -- you must do it yourself.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>fd</para></td><td class="parameter_description"><para>a file descriptor</para><para>Passed as <code>fd</code></para></td></tr><tr><td class="parameter_name"><para>condition</para></td><td class="parameter_description"><para>IO conditions to watch for on <parameter>fd</parameter></para><para>Passed as <code>condition</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unix-get-passwd-entry</title><informalexample><programlisting>(define-values (%return) (unix-get-passwd-entry user-name))
</programlisting></informalexample><para>Get the <code>passwd</code> file entry for the given <parameter>user_name</parameter> using <code>getpwnam_r()</code>.
This can fail if the given <parameter>user_name</parameter> doesn’t exist.
</para>
<para>The returned <code>struct passwd</code> has been allocated using <function>g_malloc()</function> and should
be freed using <function>g_free()</function>. The strings referenced by the returned struct are
included in the same allocation, so are valid until the <code>struct passwd</code> is
freed.
</para>
<para>This function is safe to call from multiple threads concurrently.
</para>
<para>You will need to include <code>pwd.h</code> to get the definition of <code>struct passwd</code>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>user_name</para></td><td class="parameter_description"><para>the username to get the passwd file entry for</para><para>Passed as <code>user-name</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unix-open-pipe?</title><informalexample><programlisting>(define-values (%return) (unix-open-pipe? fds flags))
</programlisting></informalexample><para>Similar to the UNIX <function>pipe()</function> call, but on modern systems like Linux
uses the <function>pipe2()</function> system call, which atomically creates a pipe with
the configured flags. The only supported flag currently is
<constant>FD_CLOEXEC</constant>. If for example you want to configure <constant>O_NONBLOCK</constant>, that
must still be done separately with <function>fcntl()</function>.
</para>
<para>This function does not take <constant>O_CLOEXEC</constant>, it takes <constant>FD_CLOEXEC</constant> as if
for <function>fcntl()</function>; these are different on Linux/glibc.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>fds</para></td><td class="parameter_description"><para>Array of two integers</para><para>Passed as <code>fds</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>Bitfield of file descriptor flags, as for <function>fcntl()</function></para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unix-set-fd-nonblocking?</title><informalexample><programlisting>(define-values (%return) (unix-set-fd-nonblocking? fd nonblock))
</programlisting></informalexample><para>Control the non-blocking state of the given file descriptor,
according to <parameter>nonblock</parameter>. On most systems this uses <constant>O_NONBLOCK</constant>, but
on some older ones may use <constant>O_NDELAY</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>fd</para></td><td class="parameter_description"><para>A file descriptor</para><para>Passed as <code>fd</code></para></td></tr><tr><td class="parameter_name"><para>nonblock</para></td><td class="parameter_description"><para>If <constant>TRUE</constant>, set the descriptor to be non-blocking</para><para>Passed as <code>nonblock</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unix-signal-add</title><informalexample><programlisting>(define-values
  (%return)
  (unix-signal-add priority signum handler user-data notify))
</programlisting></informalexample><para>A convenience function for <function>g_unix_signal_source_new()</function>, which
attaches to the default <type>GMainContext</type>.  You can remove the watch
using <function>g_source_remove()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>notify</para></td><td class="parameter_description"><para></para><para>Passed as <code>notify</code></para></td></tr><tr><td class="parameter_name"><para>priority</para></td><td class="parameter_description"><para></para><para>Passed as <code>priority</code></para></td></tr><tr><td class="parameter_name"><para>signum</para></td><td class="parameter_description"><para>Signal number</para><para>Passed as <code>signum</code></para></td></tr><tr><td class="parameter_name"><para>handler</para></td><td class="parameter_description"><para>Callback</para><para>Passed as <code>handler</code></para></td></tr><tr><td class="parameter_name"><para>user_data</para></td><td class="parameter_description"><para>Data for <parameter>handler</parameter></para><para>Passed as <code>user-data</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unix-signal-source-new</title><informalexample><programlisting>(define-values (%return) (unix-signal-source-new signum))
</programlisting></informalexample><para>Create a <type>GSource</type> that will be dispatched upon delivery of the UNIX
signal <parameter>signum</parameter>.  In GLib versions before 2.36, only <code>SIGHUP</code>, <code>SIGINT</code>,
<code>SIGTERM</code> can be monitored.  In GLib 2.36, <code>SIGUSR1</code> and <code>SIGUSR2</code>
were added. In GLib 2.54, <code>SIGWINCH</code> was added.
</para>
<para>Note that unlike the UNIX default, all sources which have created a
watch will be dispatched, regardless of which underlying thread
invoked <function>g_unix_signal_source_new()</function>.
</para>
<para>For example, an effective use of this function is to handle <code>SIGTERM</code>
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 <function>malloc()</function> 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.
</para>
<para>The interaction of this source when combined with native UNIX
functions like <function>sigprocmask()</function> is not defined.
</para>
<para>The source will not initially be associated with any <type>GMainContext</type>
and must be added to one with <function>g_source_attach()</function> before it will be
executed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>signum</para></td><td class="parameter_description"><para>A signal number</para><para>Passed as <code>signum</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unlink</title><informalexample><programlisting>(define-values (%return) (unlink filename))
</programlisting></informalexample><para>A wrapper for the POSIX <function>unlink()</function> function. The <function>unlink()</function> 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.
</para>
<para>See your C library manual for more details about <function>unlink()</function>. Note
that on Windows, it is in general not possible to delete files that
are open to some process, or mapped into memory.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>filename</para></td><td class="parameter_description"><para>a pathname in the GLib file name encoding
    (UTF-8 on Windows)</para><para>Passed as <code>filename</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>unsetenv</title><informalexample><programlisting>(define-values () (unsetenv variable))
</programlisting></informalexample><para>Removes an environment variable from the environment.
</para>
<para>Note that on some systems, when variables are overwritten, the
memory used for the previous variables and its value isn't reclaimed.
</para>
<para>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 <function>g_unsetenv()</function> while another thread is calling <function>getenv()</function>. (And note
that many functions, such as <function>gettext()</function>, call <function>getenv()</function> 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).
</para>
<para>If you need to set up the environment for a child process, you can
use <function>g_get_environ()</function> to get an environment array, modify that with
<function>g_environ_setenv()</function> and <function>g_environ_unsetenv()</function>, and then pass that
array directly to <function>execvpe()</function>, <function>g_spawn_async()</function>, or the like.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>variable</para></td><td class="parameter_description"><para>the environment variable to remove, must
    not contain '='</para><para>Passed as <code>variable</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-build</title><informalexample><programlisting>(define-values
  (%return)
  (uri-build flags scheme userinfo host port path query fragment))
</programlisting></informalexample><para>Creates a new <type>GUri</type> from the given components according to <parameter>flags</parameter>.
</para>
<para>See also <function>g_uri_build_with_user()</function>, which allows specifying the
components of the &quot;userinfo&quot; separately.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags describing how to build the <type>GUri</type></para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>scheme</para></td><td class="parameter_description"><para>the URI scheme</para><para>Passed as <code>scheme</code></para></td></tr><tr><td class="parameter_name"><para>userinfo</para></td><td class="parameter_description"><para>the userinfo component, or <constant>NULL</constant></para><para>Passed as <code>userinfo</code></para></td></tr><tr><td class="parameter_name"><para>host</para></td><td class="parameter_description"><para>the host component, or <constant>NULL</constant></para><para>Passed as <code>host</code></para></td></tr><tr><td class="parameter_name"><para>port</para></td><td class="parameter_description"><para>the port, or <code>-1</code></para><para>Passed as <code>port</code></para></td></tr><tr><td class="parameter_name"><para>path</para></td><td class="parameter_description"><para>the path component</para><para>Passed as <code>path</code></para></td></tr><tr><td class="parameter_name"><para>query</para></td><td class="parameter_description"><para>the query component, or <constant>NULL</constant></para><para>Passed as <code>query</code></para></td></tr><tr><td class="parameter_name"><para>fragment</para></td><td class="parameter_description"><para>the fragment, or <constant>NULL</constant></para><para>Passed as <code>fragment</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-build-with-user</title><informalexample><programlisting>(define-values
  (%return)
  (uri-build-with-user
    flags
    scheme
    user
    password
    auth-params
    host
    port
    path
    query
    fragment))
</programlisting></informalexample><para>Creates a new <type>GUri</type> from the given components according to <parameter>flags</parameter>
(<constant>G_URI_FLAGS_HAS_PASSWORD</constant> is added unconditionally). The <parameter>flags</parameter> must be
coherent with the passed values, in particular use <code>%</code>-encoded values with
<constant>G_URI_FLAGS_ENCODED</constant>.
</para>
<para>In contrast to <function>g_uri_build()</function>, this allows specifying the components
of the ‘userinfo’ field separately. Note that <parameter>user</parameter> must be non-<constant>NULL</constant>
if either <parameter>password</parameter> or <parameter>auth_params</parameter> is non-<constant>NULL</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags describing how to build the <type>GUri</type></para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>scheme</para></td><td class="parameter_description"><para>the URI scheme</para><para>Passed as <code>scheme</code></para></td></tr><tr><td class="parameter_name"><para>user</para></td><td class="parameter_description"><para>the user component of the userinfo, or <constant>NULL</constant></para><para>Passed as <code>user</code></para></td></tr><tr><td class="parameter_name"><para>password</para></td><td class="parameter_description"><para>the password component of the userinfo, or <constant>NULL</constant></para><para>Passed as <code>password</code></para></td></tr><tr><td class="parameter_name"><para>auth_params</para></td><td class="parameter_description"><para>the auth params of the userinfo, or <constant>NULL</constant></para><para>Passed as <code>auth-params</code></para></td></tr><tr><td class="parameter_name"><para>host</para></td><td class="parameter_description"><para>the host component, or <constant>NULL</constant></para><para>Passed as <code>host</code></para></td></tr><tr><td class="parameter_name"><para>port</para></td><td class="parameter_description"><para>the port, or <code>-1</code></para><para>Passed as <code>port</code></para></td></tr><tr><td class="parameter_name"><para>path</para></td><td class="parameter_description"><para>the path component</para><para>Passed as <code>path</code></para></td></tr><tr><td class="parameter_name"><para>query</para></td><td class="parameter_description"><para>the query component, or <constant>NULL</constant></para><para>Passed as <code>query</code></para></td></tr><tr><td class="parameter_name"><para>fragment</para></td><td class="parameter_description"><para>the fragment, or <constant>NULL</constant></para><para>Passed as <code>fragment</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-error-quark</title><informalexample><programlisting>(define-values (%return) (uri-error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>uri-escape-bytes</title><informalexample><programlisting>(define-values (%return) (uri-escape-bytes unescaped reserved-chars-allowed))
</programlisting></informalexample><para>Escapes arbitrary data for use in a URI.
</para>
<para>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 <parameter>reserved_chars_allowed</parameter>
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.
</para>
<para>Though technically incorrect, this will also allow escaping nul
bytes as <code>%</code><code>00</code>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>unescaped</para></td><td class="parameter_description"><para>the unescaped input data.</para><para>Passed as <code>unescaped</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of <parameter>unescaped</parameter></para><para>Inferred from <code>unescaped</code></para></td></tr><tr><td class="parameter_name"><para>reserved_chars_allowed</para></td><td class="parameter_description"><para>a string of reserved
  characters that are allowed to be used, or <constant>NULL</constant>.</para><para>Passed as <code>reserved-chars-allowed</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-escape-string</title><informalexample><programlisting>(define-values
  (%return)
  (uri-escape-string unescaped reserved-chars-allowed allow-utf8))
</programlisting></informalexample><para>Escapes a string for use in a URI.
</para>
<para>Normally all characters that are not &quot;unreserved&quot; (i.e. ASCII
alphanumerical characters plus dash, dot, underscore and tilde) are
escaped. But if you specify characters in <parameter>reserved_chars_allowed</parameter>
they are not escaped. This is useful for the &quot;reserved&quot; characters
in the URI specification, since those are allowed unescaped in some
portions of a URI.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>unescaped</para></td><td class="parameter_description"><para>the unescaped input string.</para><para>Passed as <code>unescaped</code></para></td></tr><tr><td class="parameter_name"><para>reserved_chars_allowed</para></td><td class="parameter_description"><para>a string of reserved
  characters that are allowed to be used, or <constant>NULL</constant>.</para><para>Passed as <code>reserved-chars-allowed</code></para></td></tr><tr><td class="parameter_name"><para>allow_utf8</para></td><td class="parameter_description"><para><constant>TRUE</constant> if the result can include UTF-8 characters.</para><para>Passed as <code>allow-utf8</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-is-valid?</title><informalexample><programlisting>(define-values (%return) (uri-is-valid? uri-string flags))
</programlisting></informalexample><para>Parses <parameter>uri_string</parameter> according to <parameter>flags</parameter>, 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 <function>g_uri_parse_relative()</function>.
</para>
<para>If it’s not a valid URI, an error is returned explaining how it’s invalid.
</para>
<para>See <function>g_uri_split()</function>, and the definition of <type>GUriFlags</type>, for more
information on the effect of <parameter>flags</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri_string</para></td><td class="parameter_description"><para>a string containing an absolute URI</para><para>Passed as <code>uri-string</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags for parsing <parameter>uri_string</parameter></para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-join</title><informalexample><programlisting>(define-values
  (%return)
  (uri-join flags scheme userinfo host port path query fragment))
</programlisting></informalexample><para>Joins the given components together according to <parameter>flags</parameter> to create
an absolute URI string. <parameter>path</parameter> may not be <constant>NULL</constant> (though it may be the empty
string).
</para>
<para>When <parameter>host</parameter> is present, <parameter>path</parameter> must either be empty or begin with a slash (<code>/</code>)
character. When <parameter>host</parameter> is not present, <parameter>path</parameter> cannot begin with two slash
   characters (<code>//</code>). See
[RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3).
</para>
<para>See also <function>g_uri_join_with_user()</function>, which allows specifying the
components of the ‘userinfo’ separately.
</para>
<para><constant>G_URI_FLAGS_HAS_PASSWORD</constant> and <constant>G_URI_FLAGS_HAS_AUTH_PARAMS</constant> are ignored if set
in <parameter>flags</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags describing how to build the URI string</para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>scheme</para></td><td class="parameter_description"><para>the URI scheme, or <constant>NULL</constant></para><para>Passed as <code>scheme</code></para></td></tr><tr><td class="parameter_name"><para>userinfo</para></td><td class="parameter_description"><para>the userinfo component, or <constant>NULL</constant></para><para>Passed as <code>userinfo</code></para></td></tr><tr><td class="parameter_name"><para>host</para></td><td class="parameter_description"><para>the host component, or <constant>NULL</constant></para><para>Passed as <code>host</code></para></td></tr><tr><td class="parameter_name"><para>port</para></td><td class="parameter_description"><para>the port, or <code>-1</code></para><para>Passed as <code>port</code></para></td></tr><tr><td class="parameter_name"><para>path</para></td><td class="parameter_description"><para>the path component</para><para>Passed as <code>path</code></para></td></tr><tr><td class="parameter_name"><para>query</para></td><td class="parameter_description"><para>the query component, or <constant>NULL</constant></para><para>Passed as <code>query</code></para></td></tr><tr><td class="parameter_name"><para>fragment</para></td><td class="parameter_description"><para>the fragment, or <constant>NULL</constant></para><para>Passed as <code>fragment</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-join-with-user</title><informalexample><programlisting>(define-values
  (%return)
  (uri-join-with-user
    flags
    scheme
    user
    password
    auth-params
    host
    port
    path
    query
    fragment))
</programlisting></informalexample><para>Joins the given components together according to <parameter>flags</parameter> to create
an absolute URI string. <parameter>path</parameter> may not be <constant>NULL</constant> (though it may be the empty
string).
</para>
<para>In contrast to <function>g_uri_join()</function>, this allows specifying the components
of the ‘userinfo’ separately. It otherwise behaves the same.
</para>
<para><constant>G_URI_FLAGS_HAS_PASSWORD</constant> and <constant>G_URI_FLAGS_HAS_AUTH_PARAMS</constant> are ignored if set
in <parameter>flags</parameter>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags describing how to build the URI string</para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>scheme</para></td><td class="parameter_description"><para>the URI scheme, or <constant>NULL</constant></para><para>Passed as <code>scheme</code></para></td></tr><tr><td class="parameter_name"><para>user</para></td><td class="parameter_description"><para>the user component of the userinfo, or <constant>NULL</constant></para><para>Passed as <code>user</code></para></td></tr><tr><td class="parameter_name"><para>password</para></td><td class="parameter_description"><para>the password component of the userinfo, or
  <constant>NULL</constant></para><para>Passed as <code>password</code></para></td></tr><tr><td class="parameter_name"><para>auth_params</para></td><td class="parameter_description"><para>the auth params of the userinfo, or
  <constant>NULL</constant></para><para>Passed as <code>auth-params</code></para></td></tr><tr><td class="parameter_name"><para>host</para></td><td class="parameter_description"><para>the host component, or <constant>NULL</constant></para><para>Passed as <code>host</code></para></td></tr><tr><td class="parameter_name"><para>port</para></td><td class="parameter_description"><para>the port, or <code>-1</code></para><para>Passed as <code>port</code></para></td></tr><tr><td class="parameter_name"><para>path</para></td><td class="parameter_description"><para>the path component</para><para>Passed as <code>path</code></para></td></tr><tr><td class="parameter_name"><para>query</para></td><td class="parameter_description"><para>the query component, or <constant>NULL</constant></para><para>Passed as <code>query</code></para></td></tr><tr><td class="parameter_name"><para>fragment</para></td><td class="parameter_description"><para>the fragment, or <constant>NULL</constant></para><para>Passed as <code>fragment</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-list-extract-uris</title><informalexample><programlisting>(define-values (%return) (uri-list-extract-uris uri-list))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri_list</para></td><td class="parameter_description"><para>an URI list</para><para>Passed as <code>uri-list</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-parse</title><informalexample><programlisting>(define-values (%return) (uri-parse uri-string flags))
</programlisting></informalexample><para>Parses <parameter>uri_string</parameter> according to <parameter>flags</parameter>. If the result is not a
valid [absolute URI][relative-absolute-uris], it will be discarded, and an
error returned.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri_string</para></td><td class="parameter_description"><para>a string representing an absolute URI</para><para>Passed as <code>uri-string</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags describing how to parse <parameter>uri_string</parameter></para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-parse-params</title><informalexample><programlisting>(define-values (%return) (uri-parse-params params length separators flags))
</programlisting></informalexample><para>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
<type>GUriParamsIter</type>.
</para>
<para>The <parameter>params</parameter> string is assumed to still be <code>%</code>-encoded, but the returned
values will be fully decoded. (Thus it is possible that the returned values
may contain <code>=</code> or <parameter>separators</parameter>, if the value was encoded in the input.)
Invalid <code>%</code>-encoding is treated as with the <constant>G_URI_FLAGS_PARSE_RELAXED</constant>
rules for <function>g_uri_parse()</function>. (However, if <parameter>params</parameter> is the path or query string
from a <type>GUri</type> that was parsed without <constant>G_URI_FLAGS_PARSE_RELAXED</constant> and
<constant>G_URI_FLAGS_ENCODED</constant>, then you already know that it does not contain any
invalid encoding.)
</para>
<para><constant>G_URI_PARAMS_WWW_FORM</constant> is handled as documented for <function>g_uri_params_iter_init()</function>.
</para>
<para>If <constant>G_URI_PARAMS_CASE_INSENSITIVE</constant> is passed to <parameter>flags</parameter>, attributes will be
compared case-insensitively, so a params string <code>attr=123&amp;Attr=456</code> will only
return a single attribute–value pair, <code>Attr=456</code>. Case will be preserved in
the returned attributes.
</para>
<para>If <parameter>params</parameter> cannot be parsed (for example, it contains two <parameter>separators</parameter>
characters in a row), then <parameter>error</parameter> is set and <constant>NULL</constant> is returned.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>params</para></td><td class="parameter_description"><para>a <code>%</code>-encoded string containing <code>attribute=value</code>
  parameters</para><para>Passed as <code>params</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length of <parameter>params</parameter>, or <code>-1</code> if it is nul-terminated</para><para>Passed as <code>length</code></para></td></tr><tr><td class="parameter_name"><para>separators</para></td><td class="parameter_description"><para>the separator byte character set between parameters. (usually
  <code>&amp;</code>, but sometimes <code>;</code> or both <code>&amp;;</code>). 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.</para><para>Passed as <code>separators</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags to modify the way the parameters are handled.</para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-parse-scheme</title><informalexample><programlisting>(define-values (%return) (uri-parse-scheme uri))
</programlisting></informalexample><para>Gets the scheme portion of a URI string.
[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
as:
<informalexample><programlisting>
URI = scheme &quot;:&quot; hier-part [ &quot;?&quot; query ] [ &quot;#&quot; fragment ]
</programlisting></informalexample></para>
<para>Common schemes include <code>file</code>, <code>https</code>, <code>svn+ssh</code>, etc.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a valid URI.</para><para>Passed as <code>uri</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-peek-scheme</title><informalexample><programlisting>(define-values (%return) (uri-peek-scheme uri))
</programlisting></informalexample><para>Gets the scheme portion of a URI string.
[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
as:
<informalexample><programlisting>
URI = scheme &quot;:&quot; hier-part [ &quot;?&quot; query ] [ &quot;#&quot; fragment ]
</programlisting></informalexample></para>
<para>Common schemes include <code>file</code>, <code>https</code>, <code>svn+ssh</code>, etc.
</para>
<para>Unlike <function>g_uri_parse_scheme()</function>, the returned scheme is normalized to
all-lowercase and does not need to be freed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri</para></td><td class="parameter_description"><para>a valid URI.</para><para>Passed as <code>uri</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-resolve-relative</title><informalexample><programlisting>(define-values (%return) (uri-resolve-relative base-uri-string uri-ref flags))
</programlisting></informalexample><para>Parses <parameter>uri_ref</parameter> according to <parameter>flags</parameter> and, if it is a
[relative URI][relative-absolute-uris], resolves it relative to
<parameter>base_uri_string</parameter>. If the result is not a valid absolute URI, it will be
discarded, and an error returned.
</para>
<para>(If <parameter>base_uri_string</parameter> is <constant>NULL</constant>, this just returns <parameter>uri_ref</parameter>, or
<constant>NULL</constant> if <parameter>uri_ref</parameter> is invalid or not absolute.)</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>base_uri_string</para></td><td class="parameter_description"><para>a string representing a base URI</para><para>Passed as <code>base-uri-string</code></para></td></tr><tr><td class="parameter_name"><para>uri_ref</para></td><td class="parameter_description"><para>a string representing a relative or absolute URI</para><para>Passed as <code>uri-ref</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags describing how to parse <parameter>uri_ref</parameter></para><para>Passed as <code>flags</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-split</title><informalexample><programlisting>(define-values
  (%return scheme userinfo host port path query fragment)
  (uri-split uri-ref flags))
</programlisting></informalexample><para>Parses <parameter>uri_ref</parameter> (which can be an
[absolute or relative URI][relative-absolute-uris]) according to <parameter>flags</parameter>, and
returns the pieces. Any component that doesn't appear in <parameter>uri_ref</parameter> will be
returned as <constant>NULL</constant> (but note that all URIs always have a path component,
though it may be the empty string).
</para>
<para>If <parameter>flags</parameter> contains <constant>G_URI_FLAGS_ENCODED</constant>, then <code>%</code>-encoded characters in
<parameter>uri_ref</parameter> 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 <constant>G_URI_FLAGS_ENCODED</constant> if they are not.
</para>
<para>Note that the <constant>G_URI_FLAGS_HAS_PASSWORD</constant> and
<constant>G_URI_FLAGS_HAS_AUTH_PARAMS</constant> <parameter>flags</parameter> are ignored by <function>g_uri_split()</function>,
since it always returns only the full userinfo; use
<function>g_uri_split_with_user()</function> if you want it split up.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri_ref</para></td><td class="parameter_description"><para>a string containing a relative or absolute URI</para><para>Passed as <code>uri-ref</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags for parsing <parameter>uri_ref</parameter></para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>scheme</para></td><td class="parameter_description"><para>on return, contains
   the scheme (converted to lowercase), or <constant>NULL</constant></para><para>Passed as <code>scheme</code></para></td></tr><tr><td class="parameter_name"><para>userinfo</para></td><td class="parameter_description"><para>on return, contains
   the userinfo, or <constant>NULL</constant></para><para>Passed as <code>userinfo</code></para></td></tr><tr><td class="parameter_name"><para>host</para></td><td class="parameter_description"><para>on return, contains the
   host, or <constant>NULL</constant></para><para>Passed as <code>host</code></para></td></tr><tr><td class="parameter_name"><para>port</para></td><td class="parameter_description"><para>on return, contains the
   port, or <code>-1</code></para><para>Passed as <code>port</code></para></td></tr><tr><td class="parameter_name"><para>path</para></td><td class="parameter_description"><para>on return, contains the
   path</para><para>Passed as <code>path</code></para></td></tr><tr><td class="parameter_name"><para>query</para></td><td class="parameter_description"><para>on return, contains the
   query, or <constant>NULL</constant></para><para>Passed as <code>query</code></para></td></tr><tr><td class="parameter_name"><para>fragment</para></td><td class="parameter_description"><para>on return, contains
   the fragment, or <constant>NULL</constant></para><para>Passed as <code>fragment</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-split-network</title><informalexample><programlisting>(define-values
  (%return scheme host port)
  (uri-split-network uri-string flags))
</programlisting></informalexample><para>Parses <parameter>uri_string</parameter> (which must be an [absolute URI][relative-absolute-uris])
according to <parameter>flags</parameter>, and returns the pieces relevant to connecting to a host.
See the documentation for <function>g_uri_split()</function> for more details; this is
mostly a wrapper around that function with simpler arguments.
However, it will return an error if <parameter>uri_string</parameter> is a relative URI,
or does not contain a hostname component.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri_string</para></td><td class="parameter_description"><para>a string containing an absolute URI</para><para>Passed as <code>uri-string</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags for parsing <parameter>uri_string</parameter></para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>scheme</para></td><td class="parameter_description"><para>on return, contains
   the scheme (converted to lowercase), or <constant>NULL</constant></para><para>Passed as <code>scheme</code></para></td></tr><tr><td class="parameter_name"><para>host</para></td><td class="parameter_description"><para>on return, contains the
   host, or <constant>NULL</constant></para><para>Passed as <code>host</code></para></td></tr><tr><td class="parameter_name"><para>port</para></td><td class="parameter_description"><para>on return, contains the
   port, or <code>-1</code></para><para>Passed as <code>port</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-split-with-user</title><informalexample><programlisting>(define-values
  (%return scheme user password auth-params host port path query fragment)
  (uri-split-with-user uri-ref flags))
</programlisting></informalexample><para>Parses <parameter>uri_ref</parameter> (which can be an
[absolute or relative URI][relative-absolute-uris]) according to <parameter>flags</parameter>, and
returns the pieces. Any component that doesn't appear in <parameter>uri_ref</parameter> will be
returned as <constant>NULL</constant> (but note that all URIs always have a path component,
though it may be the empty string).
</para>
<para>See <function>g_uri_split()</function>, and the definition of <type>GUriFlags</type>, for more
information on the effect of <parameter>flags</parameter>. Note that <parameter>password</parameter> will only
be parsed out if <parameter>flags</parameter> contains <constant>G_URI_FLAGS_HAS_PASSWORD</constant>, and
<parameter>auth_params</parameter> will only be parsed out if <parameter>flags</parameter> contains
<constant>G_URI_FLAGS_HAS_AUTH_PARAMS</constant>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>uri_ref</para></td><td class="parameter_description"><para>a string containing a relative or absolute URI</para><para>Passed as <code>uri-ref</code></para></td></tr><tr><td class="parameter_name"><para>flags</para></td><td class="parameter_description"><para>flags for parsing <parameter>uri_ref</parameter></para><para>Passed as <code>flags</code></para></td></tr><tr><td class="parameter_name"><para>scheme</para></td><td class="parameter_description"><para>on return, contains
   the scheme (converted to lowercase), or <constant>NULL</constant></para><para>Passed as <code>scheme</code></para></td></tr><tr><td class="parameter_name"><para>user</para></td><td class="parameter_description"><para>on return, contains
   the user, or <constant>NULL</constant></para><para>Passed as <code>user</code></para></td></tr><tr><td class="parameter_name"><para>password</para></td><td class="parameter_description"><para>on return, contains
   the password, or <constant>NULL</constant></para><para>Passed as <code>password</code></para></td></tr><tr><td class="parameter_name"><para>auth_params</para></td><td class="parameter_description"><para>on return, contains
   the auth_params, or <constant>NULL</constant></para><para>Passed as <code>auth-params</code></para></td></tr><tr><td class="parameter_name"><para>host</para></td><td class="parameter_description"><para>on return, contains the
   host, or <constant>NULL</constant></para><para>Passed as <code>host</code></para></td></tr><tr><td class="parameter_name"><para>port</para></td><td class="parameter_description"><para>on return, contains the
   port, or <code>-1</code></para><para>Passed as <code>port</code></para></td></tr><tr><td class="parameter_name"><para>path</para></td><td class="parameter_description"><para>on return, contains the
   path</para><para>Passed as <code>path</code></para></td></tr><tr><td class="parameter_name"><para>query</para></td><td class="parameter_description"><para>on return, contains the
   query, or <constant>NULL</constant></para><para>Passed as <code>query</code></para></td></tr><tr><td class="parameter_name"><para>fragment</para></td><td class="parameter_description"><para>on return, contains
   the fragment, or <constant>NULL</constant></para><para>Passed as <code>fragment</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-unescape-bytes</title><informalexample><programlisting>(define-values
  (%return)
  (uri-unescape-bytes escaped-string length illegal-characters))
</programlisting></informalexample><para>Unescapes a segment of an escaped string as binary data.
</para>
<para>Note that in contrast to <function>g_uri_unescape_string()</function>, this does allow
nul bytes to appear in the output.
</para>
<para>If any of the characters in <parameter>illegal_characters</parameter> appears as an escaped
character in <parameter>escaped_string</parameter>, then that is an error and <constant>NULL</constant> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>escaped_string</para></td><td class="parameter_description"><para>A URI-escaped string</para><para>Passed as <code>escaped-string</code></para></td></tr><tr><td class="parameter_name"><para>length</para></td><td class="parameter_description"><para>the length (in bytes) of <parameter>escaped_string</parameter> to escape, or <code>-1</code> if it
  is nul-terminated.</para><para>Passed as <code>length</code></para></td></tr><tr><td class="parameter_name"><para>illegal_characters</para></td><td class="parameter_description"><para>a string of illegal characters
  not to be allowed, or <constant>NULL</constant>.</para><para>Passed as <code>illegal-characters</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-unescape-segment</title><informalexample><programlisting>(define-values
  (%return)
  (uri-unescape-segment escaped-string escaped-string-end illegal-characters))
</programlisting></informalexample><para>Unescapes a segment of an escaped string.
</para>
<para>If any of the characters in <parameter>illegal_characters</parameter> or the NUL
character appears as an escaped character in <parameter>escaped_string</parameter>, then
that is an error and <constant>NULL</constant> 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.
</para>
<para>Note: <code>NUL</code> byte is not accepted in the output, in contrast to
<function>g_uri_unescape_bytes()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>escaped_string</para></td><td class="parameter_description"><para>A string, may be <constant>NULL</constant></para><para>Passed as <code>escaped-string</code></para></td></tr><tr><td class="parameter_name"><para>escaped_string_end</para></td><td class="parameter_description"><para>Pointer to end of <parameter>escaped_string</parameter>,
  may be <constant>NULL</constant></para><para>Passed as <code>escaped-string-end</code></para></td></tr><tr><td class="parameter_name"><para>illegal_characters</para></td><td class="parameter_description"><para>An optional string of illegal
  characters not to be allowed, may be <constant>NULL</constant></para><para>Passed as <code>illegal-characters</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uri-unescape-string</title><informalexample><programlisting>(define-values
  (%return)
  (uri-unescape-string escaped-string illegal-characters))
</programlisting></informalexample><para>Unescapes a whole escaped string.
</para>
<para>If any of the characters in <parameter>illegal_characters</parameter> or the NUL
character appears as an escaped character in <parameter>escaped_string</parameter>, then
that is an error and <constant>NULL</constant> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>escaped_string</para></td><td class="parameter_description"><para>an escaped string to be unescaped.</para><para>Passed as <code>escaped-string</code></para></td></tr><tr><td class="parameter_name"><para>illegal_characters</para></td><td class="parameter_description"><para>a string of illegal characters
  not to be allowed, or <constant>NULL</constant>.</para><para>Passed as <code>illegal-characters</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>usleep</title><informalexample><programlisting>(define-values () (usleep microseconds))
</programlisting></informalexample><para>Pauses the current thread for the given number of microseconds.
</para>
<para>There are 1 million microseconds per second (represented by the
<type>G_USEC_PER_SEC</type> macro). <function>g_usleep()</function> may have limited precision,
depending on hardware and operating system; don't rely on the exact
length of the sleep.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>microseconds</para></td><td class="parameter_description"><para>number of microseconds to pause</para><para>Passed as <code>microseconds</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf16-to-ucs4</title><informalexample><programlisting>(define-values
  (%return items-read items-written)
  (utf16-to-ucs4 str len items-read items-written))
</programlisting></informalexample><para>Convert a string from UTF-16 to UCS-4. The result will be
nul-terminated.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a UTF-16 encoded string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the maximum length (number of <type>gunichar2</type>) of <parameter>str</parameter> to use.
    If <parameter>len</parameter> &lt; 0, then the string is nul-terminated.</para><para>Passed as <code>len</code></para></td></tr><tr><td class="parameter_name"><para>items_read</para></td><td class="parameter_description"><para>location to store number of
    words read, or <constant>NULL</constant>. If <constant>NULL</constant>, then <constant>G_CONVERT_ERROR_PARTIAL_INPUT</constant> will
    be returned in case <parameter>str</parameter> contains a trailing partial character. If
    an error occurs then the index of the invalid input is stored here.</para><para>Passed as <code>items-read</code></para></td></tr><tr><td class="parameter_name"><para>items_written</para></td><td class="parameter_description"><para>location to store number
    of characters written, or <constant>NULL</constant>. The value stored here does not include
    the trailing 0 character.</para><para>Passed as <code>items-written</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf16-to-utf8</title><informalexample><programlisting>(define-values
  (%return items-read items-written)
  (utf16-to-utf8 str len items-read items-written))
</programlisting></informalexample><para>Convert a string from UTF-16 to UTF-8. The result will be
terminated with a 0 byte.
</para>
<para>Note that the input is expected to be already in native endianness,
an initial byte-order-mark character is not handled specially.
<function>g_convert()</function> can be used to convert a byte buffer of UTF-16 data of
ambiguous endianness.
</para>
<para>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
unpaired surrogates or partial character sequences.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a UTF-16 encoded string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the maximum length (number of <type>gunichar2</type>) of <parameter>str</parameter> to use.
    If <parameter>len</parameter> &lt; 0, then the string is nul-terminated.</para><para>Passed as <code>len</code></para></td></tr><tr><td class="parameter_name"><para>items_read</para></td><td class="parameter_description"><para>location to store number of
    words read, or <constant>NULL</constant>. If <constant>NULL</constant>, then <constant>G_CONVERT_ERROR_PARTIAL_INPUT</constant> will
    be returned in case <parameter>str</parameter> contains a trailing partial character. If
    an error occurs then the index of the invalid input is stored here.</para><para>Passed as <code>items-read</code></para></td></tr><tr><td class="parameter_name"><para>items_written</para></td><td class="parameter_description"><para>location to store number
    of bytes written, or <constant>NULL</constant>. The value stored here does not include the
    trailing 0 byte.</para><para>Passed as <code>items-written</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-casefold</title><informalexample><programlisting>(define-values (%return) (utf8-casefold str len))
</programlisting></informalexample><para>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
<function>g_utf8_casefold()</function> on other strings.
</para>
<para>Note that calling <function>g_utf8_casefold()</function> followed by <function>g_utf8_collate()</function> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a UTF-8 encoded string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>length of <parameter>str</parameter>, in bytes, or -1 if <parameter>str</parameter> is nul-terminated.</para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-collate</title><informalexample><programlisting>(define-values (%return) (utf8-collate str1 str2))
</programlisting></informalexample><para>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 <function>g_utf8_collate_key()</function> and
compare the keys with <function>strcmp()</function> when sorting instead of sorting
the original strings.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str1</para></td><td class="parameter_description"><para>a UTF-8 encoded string</para><para>Passed as <code>str1</code></para></td></tr><tr><td class="parameter_name"><para>str2</para></td><td class="parameter_description"><para>a UTF-8 encoded string</para><para>Passed as <code>str2</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-collate-key</title><informalexample><programlisting>(define-values (%return) (utf8-collate-key str len))
</programlisting></informalexample><para>Converts a string into a collation key that can be compared
with other collation keys produced by the same function using
<function>strcmp()</function>.
</para>
<para>The results of comparing the collation keys of two strings
with <function>strcmp()</function> will always be the same as comparing the two
original keys with <function>g_utf8_collate()</function>.
</para>
<para>Note that this function depends on the [current locale][setlocale].</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a UTF-8 encoded string.</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>length of <parameter>str</parameter>, in bytes, or -1 if <parameter>str</parameter> is nul-terminated.</para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-collate-key-for-filename</title><informalexample><programlisting>(define-values (%return) (utf8-collate-key-for-filename str len))
</programlisting></informalexample><para>Converts a string into a collation key that can be compared
with other collation keys produced by the same function using <function>strcmp()</function>.
</para>
<para>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 &quot;event.c&quot; &quot;eventgenerator.c&quot;
&quot;event.h&quot; instead of &quot;event.c&quot; &quot;event.h&quot; &quot;eventgenerator.c&quot;. Also, we
would like to treat numbers intelligently so that &quot;file1&quot; &quot;file10&quot; &quot;file5&quot;
is sorted as &quot;file1&quot; &quot;file5&quot; &quot;file10&quot;.
</para>
<para>Note that this function depends on the [current locale][setlocale].</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a UTF-8 encoded string.</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>length of <parameter>str</parameter>, in bytes, or -1 if <parameter>str</parameter> is nul-terminated.</para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-find-next-char</title><informalexample><programlisting>(define-values (%return) (utf8-find-next-char p end))
</programlisting></informalexample><para>Finds the start of the next UTF-8 character in the string after <parameter>p</parameter>.
</para>
<para><parameter>p</parameter> 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.
</para>
<para>If <parameter>end</parameter> is <constant>NULL</constant>, the return value will never be <constant>NULL</constant>: if the end of the
string is reached, a pointer to the terminating nul byte is returned. If
<parameter>end</parameter> is non-<constant>NULL</constant>, the return value will be <constant>NULL</constant> if the end of the string
is reached.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>p</para></td><td class="parameter_description"><para>a pointer to a position within a UTF-8 encoded string</para><para>Passed as <code>p</code></para></td></tr><tr><td class="parameter_name"><para>end</para></td><td class="parameter_description"><para>a pointer to the byte following the end of the string,
    or <constant>NULL</constant> to indicate that the string is nul-terminated</para><para>Passed as <code>end</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-find-prev-char</title><informalexample><programlisting>(define-values (%return) (utf8-find-prev-char str p))
</programlisting></informalexample><para>Given a position <parameter>p</parameter> with a UTF-8 encoded string <parameter>str</parameter>, find the start
of the previous UTF-8 character starting before <parameter>p</parameter>. Returns <constant>NULL</constant> if no
UTF-8 characters are present in <parameter>str</parameter> before <parameter>p</parameter>.
</para>
<para><parameter>p</parameter> 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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>pointer to the beginning of a UTF-8 encoded string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>p</para></td><td class="parameter_description"><para>pointer to some position within <parameter>str</parameter></para><para>Passed as <code>p</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-get-char</title><informalexample><programlisting>(define-values (%return) (utf8-get-char p))
</programlisting></informalexample><para>Converts a sequence of bytes encoded as UTF-8 to a Unicode character.
</para>
<para>If <parameter>p</parameter> 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 <function>g_utf8_get_char_validated()</function>
instead.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>p</para></td><td class="parameter_description"><para>a pointer to Unicode character encoded as UTF-8</para><para>Passed as <code>p</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-get-char-validated</title><informalexample><programlisting>(define-values (%return) (utf8-get-char-validated p max-len))
</programlisting></informalexample><para>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.
</para>
<para>Note that <function>g_utf8_get_char_validated()</function> returns (gunichar)-2 if
<parameter>max_len</parameter> is positive and any of the bytes in the first UTF-8 character
sequence are nul.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>p</para></td><td class="parameter_description"><para>a pointer to Unicode character encoded as UTF-8</para><para>Passed as <code>p</code></para></td></tr><tr><td class="parameter_name"><para>max_len</para></td><td class="parameter_description"><para>the maximum number of bytes to read, or -1 if <parameter>p</parameter> is nul-terminated</para><para>Passed as <code>max-len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-make-valid</title><informalexample><programlisting>(define-values (%return) (utf8-make-valid str len))
</programlisting></informalexample><para>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).
</para>
<para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>string to coerce into UTF-8</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the maximum length of <parameter>str</parameter> to use, in bytes. If <parameter>len</parameter> &lt; 0,
    then the string is nul-terminated.</para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-normalize</title><informalexample><programlisting>(define-values (%return) (utf8-normalize str len mode))
</programlisting></informalexample><para>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 <constant>NULL</constant> is
returned. You should generally call <function>g_utf8_normalize()</function>
before comparing two Unicode strings.
</para>
<para>The normalization mode <constant>G_NORMALIZE_DEFAULT</constant> only
standardizes differences that do not affect the
text content, such as the above-mentioned accent
representation. <constant>G_NORMALIZE_ALL</constant> also standardizes
the &quot;compatibility&quot; 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.
</para>
<para><constant>G_NORMALIZE_DEFAULT_COMPOSE</constant> and <constant>G_NORMALIZE_ALL_COMPOSE</constant>
are like <constant>G_NORMALIZE_DEFAULT</constant> and <constant>G_NORMALIZE_ALL</constant>,
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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a UTF-8 encoded string.</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>length of <parameter>str</parameter>, in bytes, or -1 if <parameter>str</parameter> is nul-terminated.</para><para>Passed as <code>len</code></para></td></tr><tr><td class="parameter_name"><para>mode</para></td><td class="parameter_description"><para>the type of normalization to perform.</para><para>Passed as <code>mode</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-offset-to-pointer</title><informalexample><programlisting>(define-values (%return) (utf8-offset-to-pointer str offset))
</programlisting></informalexample><para>Converts from an integer character offset to a pointer to a position
within the string.
</para>
<para>Since 2.10, this function allows to pass a negative <parameter>offset</parameter> to
step backwards. It is usually worth stepping backwards from the end
instead of forwards if <parameter>offset</parameter> is in the last fourth of the string,
since moving forward is about 3 times faster than moving backward.
</para>
<para>Note that this function doesn't abort when reaching the end of <parameter>str</parameter>.
Therefore you should be sure that <parameter>offset</parameter> is within string boundaries
before calling that function. Call <function>g_utf8_strlen()</function> when unsure.
This limitation exists as this function is called frequently during
text rendering and therefore has to be as fast as possible.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a UTF-8 encoded string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>offset</para></td><td class="parameter_description"><para>a character offset within <parameter>str</parameter></para><para>Passed as <code>offset</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-pointer-to-offset</title><informalexample><programlisting>(define-values (%return) (utf8-pointer-to-offset str pos))
</programlisting></informalexample><para>Converts from a pointer to position within a string to an integer
character offset.
</para>
<para>Since 2.10, this function allows <parameter>pos</parameter> to be before <parameter>str</parameter>, and returns
a negative offset in this case.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a UTF-8 encoded string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>pos</para></td><td class="parameter_description"><para>a pointer to a position within <parameter>str</parameter></para><para>Passed as <code>pos</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-prev-char</title><informalexample><programlisting>(define-values (%return) (utf8-prev-char p))
</programlisting></informalexample><para>Finds the previous UTF-8 character in the string before <parameter>p</parameter>.
</para>
<para><parameter>p</parameter> 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 <parameter>p</parameter> might be the first
character of the string, you must use <function>g_utf8_find_prev_char()</function> instead.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>p</para></td><td class="parameter_description"><para>a pointer to a position within a UTF-8 encoded string</para><para>Passed as <code>p</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-strchr</title><informalexample><programlisting>(define-values (%return) (utf8-strchr p len c))
</programlisting></informalexample><para>Finds the leftmost occurrence of the given Unicode character
in a UTF-8 encoded string, while limiting the search to <parameter>len</parameter> bytes.
If <parameter>len</parameter> is -1, allow unbounded search.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>p</para></td><td class="parameter_description"><para>a nul-terminated UTF-8 encoded string</para><para>Passed as <code>p</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the maximum length of <parameter>p</parameter></para><para>Passed as <code>len</code></para></td></tr><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-strdown</title><informalexample><programlisting>(define-values (%return) (utf8-strdown str len))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a UTF-8 encoded string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>length of <parameter>str</parameter>, in bytes, or -1 if <parameter>str</parameter> is nul-terminated.</para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-strlen</title><informalexample><programlisting>(define-values (%return) (utf8-strlen p max))
</programlisting></informalexample><para>Computes the length of the string in characters, not including
the terminating nul character. If the <parameter>max</parameter>'th byte falls in the
middle of a character, the last (partial) character is not counted.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>p</para></td><td class="parameter_description"><para>pointer to the start of a UTF-8 encoded string</para><para>Passed as <code>p</code></para></td></tr><tr><td class="parameter_name"><para>max</para></td><td class="parameter_description"><para>the maximum number of bytes to examine. If <parameter>max</parameter>
      is less than 0, then the string is assumed to be
      nul-terminated. If <parameter>max</parameter> is 0, <parameter>p</parameter> will not be examined and
      may be <constant>NULL</constant>. If <parameter>max</parameter> is greater than 0, up to <parameter>max</parameter>
      bytes are examined</para><para>Passed as <code>max</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-strncpy</title><informalexample><programlisting>(define-values (%return) (utf8-strncpy dest src n))
</programlisting></informalexample><para>Like the standard C <function>strncpy()</function> function, but copies a given number
of characters instead of a given number of bytes. The <parameter>src</parameter> string
must be valid UTF-8 encoded text. (Use <function>g_utf8_validate()</function> on all
text before trying to use UTF-8 utility functions with it.)
</para>
<para>Note you must ensure <parameter>dest</parameter> is at least 4 * <parameter>n</parameter> to fit the
largest possible UTF-8 characters</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>dest</para></td><td class="parameter_description"><para>buffer to fill with characters from <parameter>src</parameter></para><para>Passed as <code>dest</code></para></td></tr><tr><td class="parameter_name"><para>src</para></td><td class="parameter_description"><para>UTF-8 encoded string</para><para>Passed as <code>src</code></para></td></tr><tr><td class="parameter_name"><para>n</para></td><td class="parameter_description"><para>character count</para><para>Passed as <code>n</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-strrchr</title><informalexample><programlisting>(define-values (%return) (utf8-strrchr p len c))
</programlisting></informalexample><para>Find the rightmost occurrence of the given Unicode character
in a UTF-8 encoded string, while limiting the search to <parameter>len</parameter> bytes.
If <parameter>len</parameter> is -1, allow unbounded search.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>p</para></td><td class="parameter_description"><para>a nul-terminated UTF-8 encoded string</para><para>Passed as <code>p</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the maximum length of <parameter>p</parameter></para><para>Passed as <code>len</code></para></td></tr><tr><td class="parameter_name"><para>c</para></td><td class="parameter_description"><para>a Unicode character</para><para>Passed as <code>c</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-strreverse</title><informalexample><programlisting>(define-values (%return) (utf8-strreverse str len))
</programlisting></informalexample><para>Reverses a UTF-8 string. <parameter>str</parameter> must be valid UTF-8 encoded text.
(Use <function>g_utf8_validate()</function> on all text before trying to use UTF-8
utility functions with it.)
</para>
<para>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.
</para>
<para>Note that unlike <function>g_strreverse()</function>, this function returns
newly-allocated memory, which should be freed with <function>g_free()</function> when
no longer needed.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a UTF-8 encoded string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the maximum length of <parameter>str</parameter> to use, in bytes. If <parameter>len</parameter> &lt; 0,
    then the string is nul-terminated.</para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-strup</title><informalexample><programlisting>(define-values (%return) (utf8-strup str len))
</programlisting></informalexample><para>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.)</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a UTF-8 encoded string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>length of <parameter>str</parameter>, in bytes, or -1 if <parameter>str</parameter> is nul-terminated.</para><para>Passed as <code>len</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-substring</title><informalexample><programlisting>(define-values (%return) (utf8-substring str start-pos end-pos))
</programlisting></informalexample><para>Copies a substring out of a UTF-8 encoded string.
The substring will contain <parameter>end_pos</parameter> - <parameter>start_pos</parameter> characters.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a UTF-8 encoded string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>start_pos</para></td><td class="parameter_description"><para>a character offset within <parameter>str</parameter></para><para>Passed as <code>start-pos</code></para></td></tr><tr><td class="parameter_name"><para>end_pos</para></td><td class="parameter_description"><para>another character offset within <parameter>str</parameter></para><para>Passed as <code>end-pos</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-to-ucs4</title><informalexample><programlisting>(define-values
  (%return items-read items-written)
  (utf8-to-ucs4 str len items-read items-written))
</programlisting></informalexample><para>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.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a UTF-8 encoded string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the maximum length of <parameter>str</parameter> to use, in bytes. If <parameter>len</parameter> &lt; 0,
    then the string is nul-terminated.</para><para>Passed as <code>len</code></para></td></tr><tr><td class="parameter_name"><para>items_read</para></td><td class="parameter_description"><para>location to store number of
   bytes read, or <constant>NULL</constant>.
    If <constant>NULL</constant>, then <constant>G_CONVERT_ERROR_PARTIAL_INPUT</constant> will be
    returned in case <parameter>str</parameter> contains a trailing partial
    character. If an error occurs then the index of the
    invalid input is stored here.</para><para>Passed as <code>items-read</code></para></td></tr><tr><td class="parameter_name"><para>items_written</para></td><td class="parameter_description"><para>location to store number
    of characters written or <constant>NULL</constant>. The value here stored does not include
    the trailing 0 character.</para><para>Passed as <code>items-written</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-to-ucs4-fast</title><informalexample><programlisting>(define-values
  (%return items-written)
  (utf8-to-ucs4-fast str len items-written))
</programlisting></informalexample><para>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 <function>g_utf8_to_ucs4()</function>
but does no error checking on the input. A trailing 0 character
will be added to the string after the converted text.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a UTF-8 encoded string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the maximum length of <parameter>str</parameter> to use, in bytes. If <parameter>len</parameter> &lt; 0,
    then the string is nul-terminated.</para><para>Passed as <code>len</code></para></td></tr><tr><td class="parameter_name"><para>items_written</para></td><td class="parameter_description"><para>location to store the
    number of characters in the result, or <constant>NULL</constant>.</para><para>Passed as <code>items-written</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-to-utf16</title><informalexample><programlisting>(define-values
  (%return items-read items-written)
  (utf8-to-utf16 str len items-read items-written))
</programlisting></informalexample><para>Convert a string from UTF-8 to UTF-16. A 0 character will be
added to the result after the converted text.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a UTF-8 encoded string</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>len</para></td><td class="parameter_description"><para>the maximum length (number of bytes) of <parameter>str</parameter> to use.
    If <parameter>len</parameter> &lt; 0, then the string is nul-terminated.</para><para>Passed as <code>len</code></para></td></tr><tr><td class="parameter_name"><para>items_read</para></td><td class="parameter_description"><para>location to store number of
    bytes read, or <constant>NULL</constant>. If <constant>NULL</constant>, then <constant>G_CONVERT_ERROR_PARTIAL_INPUT</constant> will
    be returned in case <parameter>str</parameter> contains a trailing partial character. If
    an error occurs then the index of the invalid input is stored here.</para><para>Passed as <code>items-read</code></para></td></tr><tr><td class="parameter_name"><para>items_written</para></td><td class="parameter_description"><para>location to store number
    of <type>gunichar2</type> written, or <constant>NULL</constant>. The value stored here does not include
    the trailing 0.</para><para>Passed as <code>items-written</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-validate</title><informalexample><programlisting>(define-values (%return end) (utf8-validate str))
</programlisting></informalexample><para>Validates UTF-8 encoded text. <parameter>str</parameter> is the text to validate;
if <parameter>str</parameter> is nul-terminated, then <parameter>max_len</parameter> can be -1, otherwise
<parameter>max_len</parameter> should be the number of bytes to validate.
If <parameter>end</parameter> is non-<constant>NULL</constant>, 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).
</para>
<para>Note that <function>g_utf8_validate()</function> returns <constant>FALSE</constant> if <parameter>max_len</parameter> is
positive and any of the <parameter>max_len</parameter> bytes are nul.
</para>
<para>Returns <constant>TRUE</constant> if all of <parameter>str</parameter> 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 <function>g_utf8_validate()</function> before
doing anything else with it.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a pointer to character data</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>max_len</para></td><td class="parameter_description"><para>max bytes to validate, or -1 to go until NUL</para><para>Inferred from <code>str</code></para></td></tr><tr><td class="parameter_name"><para>end</para></td><td class="parameter_description"><para>return location for end of valid data</para><para>Passed as <code>end</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>utf8-validate-len</title><informalexample><programlisting>(define-values (%return end) (utf8-validate-len str))
</programlisting></informalexample><para>Validates UTF-8 encoded text.
</para>
<para>As with <function>g_utf8_validate()</function>, but <parameter>max_len</parameter> must be set, and hence this function
will always return <constant>FALSE</constant> if any of the bytes of <parameter>str</parameter> are nul.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a pointer to character data</para><para>Passed as <code>str</code></para></td></tr><tr><td class="parameter_name"><para>max_len</para></td><td class="parameter_description"><para>max bytes to validate</para><para>Inferred from <code>str</code></para></td></tr><tr><td class="parameter_name"><para>end</para></td><td class="parameter_description"><para>return location for end of valid data</para><para>Passed as <code>end</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uuid-string-is-valid?</title><informalexample><programlisting>(define-values (%return) (uuid-string-is-valid? str))
</programlisting></informalexample><para>Parses the string <parameter>str</parameter> and verify if it is a UUID.
</para>
<para>The function accepts the following syntax:
</para>
<para>- simple forms (e.g. <code>f81d4fae-7dec-11d0-a765-00a0c91e6bf6</code>)
</para>
<para>Note that hyphens are required within the UUID string itself,
as per the aforementioned RFC.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>str</para></td><td class="parameter_description"><para>a string representing a UUID</para><para>Passed as <code>str</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>uuid-string-random</title><informalexample><programlisting>(define-values (%return) (uuid-string-random))
</programlisting></informalexample><para>Generates a random UUID (RFC 4122 version 4) as a string. It has the same
randomness guarantees as <type>GRand</type>, so must not be used for cryptographic
purposes such as key generation, nonces, salts or one-time pads.</para></refsect2><refsect2><title>variant-get-gtype</title><informalexample><programlisting>(define-values (%return) (variant-get-gtype))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>variant-is-object-path?</title><informalexample><programlisting>(define-values (%return) (variant-is-object-path? string))
</programlisting></informalexample><para>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 <function>g_variant_new_object_path()</function>.
</para>
<para>A valid object path starts with <code>/</code> followed by zero or more
sequences of characters separated by <code>/</code> characters.  Each sequence
must contain only the characters <code>[A-Z][a-z][0-9]_</code>.  No sequence
(including the one following the final <code>/</code> character) may be empty.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a normal C nul-terminated string</para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-is-signature?</title><informalexample><programlisting>(define-values (%return) (variant-is-signature? string))
</programlisting></informalexample><para>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 <function>g_variant_new_signature()</function>.
</para>
<para>D-Bus type signatures consist of zero or more definite <type>GVariantType</type>
strings in sequence.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a normal C nul-terminated string</para><para>Passed as <code>string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-parse</title><informalexample><programlisting>(define-values (%return) (variant-parse type text limit endptr))
</programlisting></informalexample><para>Parses a <type>GVariant</type> from a text representation.
</para>
<para>A single <type>GVariant</type> is parsed from the content of <parameter>text</parameter>.
</para>
<para>The format is described [here][gvariant-text].
</para>
<para>The memory at <parameter>limit</parameter> will never be accessed and the parser behaves as
if the character at <parameter>limit</parameter> is the nul terminator.  This has the
effect of bounding <parameter>text</parameter>.
</para>
<para>If <parameter>endptr</parameter> is non-<constant>NULL</constant> then <parameter>text</parameter> is permitted to contain data
following the value that this function parses and <parameter>endptr</parameter> will be
updated to point to the first character past the end of the text
parsed by this function.  If <parameter>endptr</parameter> is <constant>NULL</constant> and there is extra data
then an error is returned.
</para>
<para>If <parameter>type</parameter> is non-<constant>NULL</constant> 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).
</para>
<para>In the event that the parsing is successful, the resulting <type>GVariant</type>
is returned. It is never floating, and must be freed with
<function>g_variant_unref()</function>.
</para>
<para>In case of any error, <constant>NULL</constant> will be returned.  If <parameter>error</parameter> is non-<constant>NULL</constant>
then it will be set to reflect the error that occurred.
</para>
<para>Officially, the language understood by the parser is &quot;any string
produced by <function>g_variant_print()</function>&quot;.
</para>
<para>There may be implementation specific restrictions on deeply nested values,
which would result in a <constant>G_VARIANT_PARSE_ERROR_RECURSION</constant> error. <type>GVariant</type> is
guaranteed to handle nesting up to at least 64 levels.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type</para></td><td class="parameter_description"><para>a <type>GVariantType</type>, or <constant>NULL</constant></para><para>Passed as <code>type</code></para></td></tr><tr><td class="parameter_name"><para>text</para></td><td class="parameter_description"><para>a string containing a GVariant in text form</para><para>Passed as <code>text</code></para></td></tr><tr><td class="parameter_name"><para>limit</para></td><td class="parameter_description"><para>a pointer to the end of <parameter>text</parameter>, or <constant>NULL</constant></para><para>Passed as <code>limit</code></para></td></tr><tr><td class="parameter_name"><para>endptr</para></td><td class="parameter_description"><para>a location to store the end pointer, or <constant>NULL</constant></para><para>Passed as <code>endptr</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-parse-error-print-context</title><informalexample><programlisting>(define-values (%return) (variant-parse-error-print-context error source-str))
</programlisting></informalexample><para>Pretty-prints a message showing the context of a <type>GVariant</type> parse
error within the string for which parsing was attempted.
</para>
<para>The resulting string is suitable for output to the console or other
monospace media where newlines are treated in the usual way.
</para>
<para>The message will typically look something like one of the following:
</para>
<para><informalexample><programlisting>
unterminated string constant:
  (1, 2, 3, 'abc
            ^^^^
</programlisting></informalexample></para>

<para>or
</para>
<para><informalexample><programlisting>
unable to find a common type:
  [1, 2, 3, 'str']
   ^        ^^^^^
</programlisting></informalexample></para>

<para>The format of the message may change in a future version.
</para>
<para><parameter>error</parameter> must have come from a failed attempt to <function>g_variant_parse()</function> and
<parameter>source_str</parameter> must be exactly the same string that caused the error.
If <parameter>source_str</parameter> was not nul-terminated when you passed it to
<function>g_variant_parse()</function> then you must add nul termination before using this
function.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>error</para></td><td class="parameter_description"><para>a <type>GError</type> from the <type>GVariantParseError</type> domain</para><para>Passed as <code>error</code></para></td></tr><tr><td class="parameter_name"><para>source_str</para></td><td class="parameter_description"><para>the string that was given to the parser</para><para>Passed as <code>source-str</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-parse-error-quark</title><informalexample><programlisting>(define-values (%return) (variant-parse-error-quark))
</programlisting></informalexample><para>Undocumented</para></refsect2><refsect2><title>variant-type-checked-</title><informalexample><programlisting>(define-values (%return) (variant-type-checked- arg0))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>arg0</para></td><td class="parameter_description"><para></para><para>Passed as <code>arg0</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-type-string-get-depth-</title><informalexample><programlisting>(define-values (%return) (variant-type-string-get-depth- type-string))
</programlisting></informalexample><para>Undocumented</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type_string</para></td><td class="parameter_description"><para></para><para>Passed as <code>type-string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-type-string-is-valid?</title><informalexample><programlisting>(define-values (%return) (variant-type-string-is-valid? type-string))
</programlisting></informalexample><para>Checks if <parameter>type_string</parameter> is a valid GVariant type string.  This call is
equivalent to calling <function>g_variant_type_string_scan()</function> and confirming
that the following character is a nul terminator.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>type_string</para></td><td class="parameter_description"><para>a pointer to any string</para><para>Passed as <code>type-string</code></para></td></tr></informaltable></refsect3></refsect2><refsect2><title>variant-type-string-scan</title><informalexample><programlisting>(define-values (%return endptr) (variant-type-string-scan string limit))
</programlisting></informalexample><para>Scan for a single complete and valid GVariant type string in <parameter>string</parameter>.
The memory pointed to by <parameter>limit</parameter> (or bytes beyond it) is never
accessed.
</para>
<para>If a valid type string is found, <parameter>endptr</parameter> is updated to point to the
first character past the end of the string that was found and <constant>TRUE</constant>
is returned.
</para>
<para>If there is no valid type string starting at <parameter>string</parameter>, or if the type
string does not end before <parameter>limit</parameter> then <constant>FALSE</constant> is returned.
</para>
<para>For the simple case of checking if a string is a valid type string,
see <function>g_variant_type_string_is_valid()</function>.</para><refsect3><title>Parameters</title><informaltable><tr><td class="parameter_name"><para>string</para></td><td class="parameter_description"><para>a pointer to any string</para><para>Passed as <code>string</code></para></td></tr><tr><td class="parameter_name"><para>limit</para></td><td class="parameter_description"><para>the end of <parameter>string</parameter>, or <constant>NULL</constant></para><para>Passed as <code>limit</code></para></td></tr><tr><td class="parameter_name"><para>endptr</para></td><td class="parameter_description"><para>location to store the end pointer, or <constant>NULL</constant></para><para>Passed as <code>endptr</code></para></td></tr></informaltable></refsect3></refsect2></refsect1></refentry></chapter></book>