More gracefully handle type mismatch errors when doing playlist things (just ignore...

[ardour.git] / libs / glibmm2 / glib / src / glib_docs.xml

<root>
<function name="g_str_hash">
<description>
Converts a string to a hash value.
It can be passed to g_hash_table_new() as the @hash_func 
parameter, when using strings as keys in a #GHashTable.


</description>
<parameters>
<parameter name="v">
<parameter_description> a string key
</parameter_description>
</parameter>
</parameters>
<return> a hash value corresponding to the key
</return>
</function>

<function name="g_strcasecmp">
<description>
A case-insensitive string comparison, corresponding to the standard
strcasecmp() function on platforms which support it.


</description>
<parameters>
<parameter name="s1">
<parameter_description> a string.
</parameter_description>
</parameter>
<parameter name="s2">
<parameter_description> a string to compare with @s1.
</parameter_description>
</parameter>
</parameters>
<return> 0 if the strings match, a negative value if @s1 &amp;lt; @s2, 
or a positive value if @s1 &amp;gt; @s2.

Deprecated:2.2: See g_strncasecmp() for a discussion of why this function 
is deprecated and how to replace it.
</return>
</function>

<function name="g_source_destroy">
<description>
Removes a source from its #GMainContext, if any, and mark it as
destroyed.  The source cannot be subsequently added to another
context.

</description>
<parameters>
<parameter name="source">
<parameter_description> a #GSource
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_unichar_isdigit">
<description>
Determines whether a character is numeric (i.e. a digit).  This
covers ASCII 0-9 and also digits in other languages/scripts.  Given
some UTF-8 text, obtain a character value with g_utf8_get_char().


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @c is a digit
</return>
</function>

<function name="g_shell_unquote">
<description>
Unquotes a string as the shell (/bin/sh) would. Only handles
quotes; if a string contains file globs, arithmetic operators,
variables, backticks, redirections, or other special-to-the-shell
features, the result will be different from the result a real shell
would produce (the variables, backticks, etc. will be passed
through literally instead of being expanded). This function is
guaranteed to succeed if applied to the result of
g_shell_quote(). If it fails, it returns %NULL and sets the
error. The @quoted_string need not actually contain quoted or
escaped text; g_shell_unquote() simply goes through the string and
unquotes/unescapes anything that the shell would. Both single and
double quotes are handled, as are escapes including escaped
newlines. The return value must be freed with g_free(). Possible
errors are in the #G_SHELL_ERROR domain.

Shell quoting rules are a bit strange. Single quotes preserve the
literal string exactly. escape sequences are not allowed; not even
\&apos; - if you want a &apos; in the quoted text, you have to do something
like &apos;foo&apos;\&apos;&apos;bar&apos;.  Double quotes allow $, `, &quot;, \, and newline to
be escaped with backslash. Otherwise double quotes preserve things
literally.


</description>
<parameters>
<parameter name="quoted_string">
<parameter_description> shell-quoted string
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> error return location or NULL
</parameter_description>
</parameter>
</parameters>
<return> an unquoted string
</return>
</function>

<function name="g_build_pathv">
<description>
Behaves exactly like g_build_path(), but takes the path elements 
as a string array, instead of varargs. This function is mainly
meant for language bindings.


</description>
<parameters>
<parameter name="separator">
<parameter_description> a string used to separator the elements of the path.
</parameter_description>
</parameter>
<parameter name="args">
<parameter_description> %NULL-terminated array of strings containing the path elements.
</parameter_description>
</parameter>
</parameters>
<return> a newly-allocated string that must be freed with g_free().

Since: 2.8
</return>
</function>

<function name="g_propagate_error">
<description>
If @dest is %NULL, free @src; otherwise,
moves @src into *@dest. *@dest must be %NULL.

</description>
<parameters>
<parameter name="dest">
<parameter_description> error return location
</parameter_description>
</parameter>
<parameter name="src">
<parameter_description> error to move into the return location
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_thread_pool_get_num_threads">
<description>
Return value: the number of threads currently running

</description>
<parameters>
<parameter name="pool">
<parameter_description> a #GThreadPool
</parameter_description>
</parameter>
</parameters>
<return> the number of threads currently running
</return>
</function>

<function name="g_bookmark_file_get_applications">
<description>
Retrieves the names of the applications that have registered the
bookmark for @uri.

In the event the URI cannot be found, %NULL is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> return location of the length of the returned list, or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated %NULL-terminated array of strings.
Use g_strfreev() to free it.

Since: 2.12
</return>
</function>

<function name="g_io_channel_close">
<description>
Close an IO channel. Any pending data to be written will be
flushed, ignoring errors. The channel will not be freed until the
last reference is dropped using g_io_channel_unref(). 

Deprecated:2.2: Use g_io_channel_shutdown() instead.

</description>
<parameters>
<parameter name="channel">
<parameter_description> A #GIOChannel
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_string_equal">
<description>
Compares two strings for equality, returning %TRUE if they are equal. 
For use with #GHashTable.


</description>
<parameters>
<parameter name="v">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="v2">
<parameter_description> another #GString
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if they strings are the same length and contain the 
same bytes
</return>
</function>

<function name="g_bookmark_file_get_is_private">
<description>
Gets whether the private flag of the bookmark for @uri is set.

In the event the URI cannot be found, %FALSE is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.  In the
event that the private flag cannot be found, %FALSE is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the private flag is set, %FALSE otherwise.

Since: 2.12
</return>
</function>

<function name="g_main_current_source">
<description>
Return value: The currently firing source or %NULL.

</description>
<parameters>
</parameters>
<return> The currently firing source or %NULL.

Since: 2.12
</return>
</function>

<function name="g_intern_string">
<description>
Returns: a canonical representation for the string

</description>
<parameters>
<parameter name="string">
<parameter_description> a string
</parameter_description>
</parameter>
</parameters>
<return> a canonical representation for the string

Since: 2.10
</return>
</function>

<function name="g_key_file_set_double_list">
<description>
Associates a list of double values with @key under
@group_name.  If @key cannot be found then it is created.
If @group_name is %NULL the start group is used.

Since: 2.12

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="list">
<parameter_description> an array of double values
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> number of double values in @list
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_sequence_iter_get_position">
<description>
Return value: the position of @iter

</description>
<parameters>
<parameter name="iter">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
</parameters>
<return> the position of @iter

Since: 2.14
</return>
</function>

<function name="g_source_new">
<description>
Creates a new #GSource structure. The size is specified to
allow creating structures derived from #GSource that contain
additional data. The size passed in must be at least
&amp;lt;literal&amp;gt;sizeof (GSource)&amp;lt;/literal&amp;gt;.

The source will not initially be associated with any #GMainContext
and must be added to one with g_source_attach() before it will be
executed.


</description>
<parameters>
<parameter name="source_funcs">
<parameter_description> structure containing functions that implement
the sources behavior.
</parameter_description>
</parameter>
<parameter name="struct_size">
<parameter_description> size of the #GSource structure to create.
</parameter_description>
</parameter>
</parameters>
<return> the newly-created #GSource.
</return>
</function>

<function name="g_io_channel_set_encoding">
<description>
Sets the encoding for the input/output of the channel. The internal
encoding is always UTF-8. The default encoding for the
external file is UTF-8.

The encoding %NULL is safe to use with binary data.

The encoding can only be set if one of the following conditions
is true:

1. The channel was just created, and has not been written to
or read from yet.

2. The channel is write-only.

3. The channel is a file, and the file pointer was just
repositioned by a call to g_io_channel_seek_position().
(This flushes all the internal buffers.)

4. The current encoding is %NULL or UTF-8.

5. One of the (new API) read functions has just returned %G_IO_STATUS_EOF
(or, in the case of g_io_channel_read_to_end (), %G_IO_STATUS_NORMAL).

6. One of the functions g_io_channel_read_chars () or g_io_channel_read_unichar ()
has returned %G_IO_STATUS_AGAIN or %G_IO_STATUS_ERROR. This may be
useful in the case of %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
Returning one of these statuses from g_io_channel_read_line (),
g_io_channel_read_line_string (), or g_io_channel_read_to_end ()
does &amp;lt;emphasis&amp;gt;not&amp;lt;/emphasis&amp;gt; guarantee that the encoding can be changed.

Channels which do not meet one of the above conditions cannot call
g_io_channel_seek_position () with an offset of %G_SEEK_CUR,
and, if they are &quot;seekable&quot;, cannot
call g_io_channel_write_chars () after calling one
of the API &quot;read&quot; functions.


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
<parameter name="encoding">
<parameter_description> the encoding type
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store an error of type #GConvertError.
</parameter_description>
</parameter>
</parameters>
<return> %G_IO_STATUS_NORMAL if the encoding was successfully set.
</return>
</function>

<function name="g_markup_parse_context_free">
<description>
Frees a #GMarkupParseContext. Can&apos;t be called from inside
one of the #GMarkupParser functions.


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMarkupParseContext
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_string_chunk_new">
<description>
Creates a new #GStringChunk. 


</description>
<parameters>
<parameter name="size">
<parameter_description> the default size of the blocks of memory which are 
allocated to store the strings. If a particular string 
is larger than this default size, a larger block of 
memory will be allocated for it.
</parameter_description>
</parameter>
</parameters>
<return> a new #GStringChunk
</return>
</function>

<function name="g_utf8_normalize">
<description>
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. You
should generally call g_utf8_normalize() before
comparing two Unicode strings.

The normalization mode %G_NORMALIZE_DEFAULT only
standardizes differences that do not affect the
text content, such as the above-mentioned accent
representation. %G_NORMALIZE_ALL also standardizes
the &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.
For example, g_utf8_collate() normalizes
with %G_NORMALIZE_ALL as its first step.

%G_NORMALIZE_DEFAULT_COMPOSE and %G_NORMALIZE_ALL_COMPOSE
are like %G_NORMALIZE_DEFAULT and %G_NORMALIZE_ALL,
but returned a result with composed forms rather
than a maximally decomposed form. This is often
useful if you intend to convert the string to
a legacy encoding or pass it to a system with
less capable Unicode handling.


</description>
<parameters>
<parameter name="str">
<parameter_description> a UTF-8 encoded string.
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> length of @str, in bytes, or -1 if @str is nul-terminated.
</parameter_description>
</parameter>
<parameter name="mode">
<parameter_description> the type of normalization to perform.
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string, that is the 
normalized form of @str.
</return>
</function>

<function name="g_match_info_next">
<description>
Scans for the next match using the same parameters of the previous
call to g_regex_match_full() or g_regex_match() that returned
@match_info.

The match is done on the string passed to the match function, so you
cannot free it before calling this function.


</description>
<parameters>
<parameter name="match_info">
<parameter_description> a #GMatchInfo structure
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store the error occuring, or %NULL to ignore errors
</parameter_description>
</parameter>
</parameters>
<return> %TRUE is the string matched, %FALSE otherwise

Since: 2.14
</return>
</function>

<function name="g_qsort_with_data">
<description>
This is just like the standard C qsort() function, but
the comparison routine accepts a user data argument.


</description>
<parameters>
<parameter name="pbase">
<parameter_description> start of array to sort
</parameter_description>
</parameter>
<parameter name="total_elems">
<parameter_description> elements in the array
</parameter_description>
</parameter>
<parameter name="size">
<parameter_description> size of each element
</parameter_description>
</parameter>
<parameter name="compare_func">
<parameter_description> function to compare elements
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> data to pass to @compare_func
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_dir_read_name">
<description>
Retrieves the name of the next entry in the directory.  The &apos;.&apos; and
&apos;..&apos; entries are omitted. On Windows, the returned name is in
UTF-8. On Unix, it is in the on-disk encoding.


</description>
<parameters>
<parameter name="dir">
<parameter_description> a #GDir* created by g_dir_open()
</parameter_description>
</parameter>
</parameters>
<return> The entry&apos;s name or %NULL if there are no 
more entries. The return value is owned by GLib and
must not be modified or freed.
</return>
</function>

<function name="g_main_context_wakeup">
<description>
If @context is currently waiting in a poll(), interrupt
the poll(), and continue the iteration process.

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_get_application_name">
<description>
Gets a human-readable name for the application, as set by
g_set_application_name(). This name should be localized if
possible, and is intended for display to the user.  Contrast with
g_get_prgname(), which gets a non-localized name. If
g_set_application_name() has not been called, returns the result of
g_get_prgname() (which may be %NULL if g_set_prgname() has also not
been called).


</description>
<parameters>
</parameters>
<return> human-readable application name. may return %NULL

Since: 2.2
</return>
</function>

<function name="g_get_tmp_dir">
<description>
Gets the directory to use for temporary files. This is found from 
inspecting the environment variables &amp;lt;envar&amp;gt;TMPDIR&amp;lt;/envar&amp;gt;, 
&amp;lt;envar&amp;gt;TMP&amp;lt;/envar&amp;gt;, and &amp;lt;envar&amp;gt;TEMP&amp;lt;/envar&amp;gt; in that order. If none 
of those are defined &quot;/tmp&quot; is returned on UNIX and &quot;C:\&quot; on Windows. 
The encoding of the returned string is system-defined. On Windows, 
it is always UTF-8. The return value is never %NULL.


</description>
<parameters>
</parameters>
<return> the directory to use for temporary files.
</return>
</function>

<function name="g_snprintf">
<description>
A safer form of the standard sprintf() function. The output is guaranteed
to not exceed @n characters (including the terminating nul character), so 
it is easy to ensure that a buffer overflow cannot occur.

See also g_strdup_printf().

In versions of GLib prior to 1.2.3, this function may return -1 if the 
output was truncated, and the truncated string may not be nul-terminated. 
In versions prior to 1.3.12, this function returns the length of the output 
string.

The return value of g_snprintf() conforms to the snprintf()
function as standardized in ISO C99. Note that this is different from 
traditional snprintf(), which returns the length of the output string.

The format string may contain positional parameters, as specified in 
the Single Unix Specification.


</description>
<parameters>
<parameter name="string">
<parameter_description> the buffer to hold the output.
</parameter_description>
</parameter>
<parameter name="n">
<parameter_description> the maximum number of characters to produce (including the 
terminating nul character).
</parameter_description>
</parameter>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice 
&amp;lt;link linkend=&quot;string-precision&quot;&amp;gt;string precision pitfalls&amp;lt;/link&amp;gt;.
</parameter_description>
</parameter>
<parameter name="Varargs">
<parameter_description> the arguments to insert in the output.
</parameter_description>
</parameter>
</parameters>
<return> the number of characters which would be produced if the buffer 
was large enough.
</return>
</function>

<function name="g_match_info_fetch">
<description>
Retrieves the text matching the @match_num&amp;lt;!-- --&amp;gt;&apos;th capturing 
parentheses. 0 is the full text of the match, 1 is the first paren 
set, 2 the second, and so on.

If @match_num is a valid sub pattern but it didn&apos;t match anything 
(e.g. sub pattern 1, matching &quot;b&quot; against &quot;(a)?b&quot;) then an empty 
string is returned.

If the match was obtained using the DFA algorithm, that is using
g_regex_match_all() or g_regex_match_all_full(), the retrieved
string is not that of a set of parentheses but that of a matched
substring. Substrings are matched in reverse order of length, so 
0 is the longest match.

The string is fetched from the string passed to the match function,
so you cannot call this function after freeing the string.


</description>
<parameters>
<parameter name="match_info">
<parameter_description> #GMatchInfo structure
</parameter_description>
</parameter>
<parameter name="match_num">
<parameter_description> number of the sub expression
</parameter_description>
</parameter>
</parameters>
<return> The matched substring, or %NULL if an error occurred.
You have to free the string yourself

Since: 2.14
</return>
</function>

<function name="g_main_context_ref">
<description>
Increases the reference count on a #GMainContext object by one.


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext
</parameter_description>
</parameter>
</parameters>
<return> the @context that was passed in (since 2.6)
</return>
</function>

<function name="g_set_application_name">
<description>
Sets a human-readable name for the application. This name should be
localized if possible, and is intended for display to the user.
Contrast with g_set_prgname(), which sets a non-localized name.
g_set_prgname() will be called automatically by gtk_init(),
but g_set_application_name() will not.

Note that for thread safety reasons, this function can only
be called once.

The application name will be used in contexts such as error messages,
or when displaying an application&apos;s name in the task list.


</description>
<parameters>
<parameter name="application_name">
<parameter_description> localized name of the application
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_main_context_acquire">
<description>
Tries to become the owner of the specified context.
If some other context is the owner of the context,
Return value: %TRUE if the operation succeeded, and

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the operation succeeded, and
this thread is now the owner of @context.
</return>
</function>

<function name="g_match_info_get_string">
<description>
Returns: the string searched with @match_info

</description>
<parameters>
<parameter name="match_info">
<parameter_description> a #GMatchInfo
</parameter_description>
</parameter>
</parameters>
<return> the string searched with @match_info

Since: 2.14
</return>
</function>

<function name="g_file_set_contents">
<description>
Writes all of @contents to a file named @filename, with good error checking.
If a file called @filename already exists it will be overwritten.

This write is atomic in the sense that it is first written to a temporary
file which is then renamed to the final name. Notes:
&amp;lt;itemizedlist&amp;gt;
&amp;lt;listitem&amp;gt;
On Unix, if @filename already exists hard links to @filename will break.
Also since the file is recreated, existing permissions, access control
lists, metadata etc. may be lost. If @filename is a symbolic link,
the link itself will be replaced, not the linked file.
&amp;lt;/listitem&amp;gt;
&amp;lt;listitem&amp;gt;
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.
&amp;lt;/listitem&amp;gt;
&amp;lt;listitem&amp;gt;
On Windows there is no way to remove a file that is open to some
process, or mapped into memory. Thus, this function will fail if
@filename already exists and is open.
&amp;lt;/listitem&amp;gt;
&amp;lt;/itemizedlist&amp;gt;

If the call was sucessful, it returns %TRUE. If the call was not successful,
it returns %FALSE and sets @error. The error domain is #G_FILE_ERROR.
Possible error codes are those in the #GFileError enumeration.


</description>
<parameters>
<parameter name="filename">
<parameter_description> name of a file to write @contents to, in the GLib file name
encoding
</parameter_description>
</parameter>
<parameter name="contents">
<parameter_description> string to write to the file
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> length of @contents, or -1 if @contents is a nul-terminated string
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE on success, %FALSE if an error occurred

Since: 2.8
</return>
</function>

<function name="g_idle_add_full">
<description>
Adds a function to be called whenever there are no higher priority
events pending.  If the function returns %FALSE it is automatically
removed from the list of event sources and will not be called again.


</description>
<parameters>
<parameter name="priority">
<parameter_description> the priority of the idle source. Typically this will be in the
range btweeen #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.
</parameter_description>
</parameter>
<parameter name="function">
<parameter_description> function to call
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description>     data to pass to @function
</parameter_description>
</parameter>
<parameter name="notify">
<parameter_description>   function to call when the idle is removed, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> the ID (greater than 0) of the event source.
</return>
</function>

<function name="g_dir_rewind">
<description>
Resets the given directory. The next call to g_dir_read_name()
will return the first entry again.

</description>
<parameters>
<parameter name="dir">
<parameter_description> a #GDir* created by g_dir_open()
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_hash_table_get_keys">
<description>
Retrieves every key inside @hash_table. The returned data is valid
until @hash_table is modified.


</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a #GHashTable
</parameter_description>
</parameter>
</parameters>
<return> a #GList containing all the keys inside the hash
table. The content of the list is owned by the hash table and
should not be modified or freed. Use g_list_free() when done
using the list.

Since: 2.14
</return>
</function>

<function name="g_get_system_config_dirs">
<description>
Return value: a %NULL-terminated array of strings owned by GLib that must 

</description>
<parameters>
</parameters>
<return> a %NULL-terminated array of strings owned by GLib that must 
not be modified or freed.
Since: 2.6
</return>
</function>

<function name="g_queue_pop_nth">
<description>
Removes the @n&apos;th element of @queue.


</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="n">
<parameter_description> the position of the element.
</parameter_description>
</parameter>
</parameters>
<return> the element&apos;s data, or %NULL if @n is off the end of @queue.

Since: 2.4
</return>
</function>

<function name="g_key_file_has_key">
<description>
Looks whether the key file has the key @key in the group
@group_name. 


</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key name
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @key is a part of @group_name, %FALSE
otherwise.

Since: 2.6
</return>
</function>

<function name="g_io_channel_read_chars">
<description>
Replacement for g_io_channel_read() with the new API.


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
<parameter name="buf">
<parameter_description> a buffer to read data into
</parameter_description>
</parameter>
<parameter name="count">
<parameter_description> the size of the buffer. Note that the buffer may
not be complelely filled even if there is data
in the buffer if the remaining data is not a
complete character.
</parameter_description>
</parameter>
<parameter name="bytes_read">
<parameter_description> The number of bytes read. This may be zero even on
success if count &amp;lt; 6 and the channel&apos;s encoding is non-%NULL.
This indicates that the next UTF-8 character is too wide for
the buffer.
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> A location to return an error of type #GConvertError
or #GIOChannelError.
</parameter_description>
</parameter>
</parameters>
<return> the status of the operation.
</return>
</function>

<function name="g_key_file_set_boolean_list">
<description>
Associates a list of boolean values with @key under
@group_name.  If @key cannot be found then it is created.
If @group_name is %NULL, the start_group is used.

Since: 2.6

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="list">
<parameter_description> an array of boolean values
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> length of @list
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_rand_double">
<description>
Return value: A random number.

</description>
<parameters>
<parameter name="rand_">
<parameter_description> a #GRand.
</parameter_description>
</parameter>
</parameters>
<return> A random number.
</return>
</function>

<function name="g_markup_parse_context_parse">
<description>
Feed some data to the #GMarkupParseContext. The data need not
be valid UTF-8; an error will be signaled if it&apos;s invalid.
The data need not be an entire document; you can feed a document
into the parser incrementally, via multiple calls to this function.
Typically, as you receive data from a network connection or file,
you feed each received chunk of data into this function, aborting
the process if an error occurs. Once an error is reported, no further
data may be fed to the #GMarkupParseContext; all errors are fatal.


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMarkupParseContext
</parameter_description>
</parameter>
<parameter name="text">
<parameter_description> chunk of text to parse
</parameter_description>
</parameter>
<parameter name="text_len">
<parameter_description> length of @text in bytes
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError
</parameter_description>
</parameter>
</parameters>
<return> %FALSE if an error occurred, %TRUE on success
</return>
</function>

<function name="g_node_copy_deep">
<description>
Recursively copies a #GNode and its data.


</description>
<parameters>
<parameter name="node">
<parameter_description> a #GNode
</parameter_description>
</parameter>
<parameter name="copy_func">
<parameter_description> the function which is called to copy the data inside each node,
or %NULL to use the original data.
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> data to pass to @copy_func
</parameter_description>
</parameter>
</parameters>
<return> a new #GNode containing copies of the data in @node.

Since: 2.4
</return>
</function>

<function name="g_main_context_iteration">
<description>
Runs a single iteration for the given main loop. This involves
checking to see if any event sources are ready to be processed,
then if no events sources are ready and @may_block is %TRUE, waiting
for a source to become ready, then dispatching the highest priority
events sources that are ready. Note that even when @may_block is %TRUE,
it is still possible for g_main_context_iteration() to return
%FALSE, since the the wait may be interrupted for other
reasons than an event source becoming ready.


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext (if %NULL, the default context will be used) 
</parameter_description>
</parameter>
<parameter name="may_block">
<parameter_description> whether the call may block.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if events were dispatched.
</return>
</function>

<function name="g_file_read_link">
<description>
Reads the contents of the symbolic link @filename like the POSIX
readlink() function.  The returned string is in the encoding used
for filenames. Use g_filename_to_utf8() to convert it to UTF-8.


</description>
<parameters>
<parameter name="filename">
<parameter_description> the symbolic link
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError
</parameter_description>
</parameter>
</parameters>
<return> A newly allocated string with the contents of the symbolic link, 
or %NULL if an error occurred.

Since: 2.4
</return>
</function>

<function name="g_unichar_totitle">
<description>
Converts a character to the titlecase.


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> the result of converting @c to titlecase.
If @c is not an uppercase or lowercase character,
@c is returned unchanged.
</return>
</function>

<function name="g_sequence_new">
<description>
Creates a new GSequence. The @data_destroy function, if non-%NULL will
be called on all items when the sequence is destroyed and on items that
are removed from the sequence.


</description>
<parameters>
<parameter name="data_destroy">
<parameter_description> a #GDestroyNotify function, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a new #GSequence

Since: 2.14
</return>
</function>

<function name="g_main_loop_unref">
<description>
Decreases the reference count on a #GMainLoop object by one. If
the result is zero, free the loop and free all associated memory.

</description>
<parameters>
<parameter name="loop">
<parameter_description> a #GMainLoop
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_key_file_get_integer_list">
<description>
Return value: the values associated with the key as a list of

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> the number of integers returned
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError
</parameter_description>
</parameter>
</parameters>
<return> the values associated with the key as a list of
integers, or %NULL if the key was not found or could not be parsed.

Since: 2.6
</return>
</function>

<function name="g_file_error_from_errno">
<description>
Gets a #GFileError constant based on the passed-in @errno.
For example, if you pass in %EEXIST this function returns
#G_FILE_ERROR_EXIST. Unlike @errno values, you can portably
assume that all #GFileError values will exist.

Normally a #GFileError value goes into a #GError returned
from a function that manipulates files. So you would use
g_file_error_from_errno() when constructing a #GError.


</description>
<parameters>
<parameter name="err_no">
<parameter_description> an &quot;errno&quot; value
</parameter_description>
</parameter>
</parameters>
<return> #GFileError corresponding to the given @errno
</return>
</function>

<function name="g_main_context_find_source_by_funcs_user_data">
<description>
Finds a source with the given source functions and user data.  If
multiple sources exist with the same source function and user data,
the first one found will be returned.


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext (if %NULL, the default context will be used).
</parameter_description>
</parameter>
<parameter name="funcs">
<parameter_description> the @source_funcs passed to g_source_new().
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> the user data from the callback.
</parameter_description>
</parameter>
</parameters>
<return> the source, if one was found, otherwise %NULL
</return>
</function>

<function name="g_bookmark_file_load_from_data_dirs">
<description>
This function looks for a desktop bookmark file named @file in the
paths returned from g_get_user_data_dir() and g_get_system_data_dirs(), 
loads the file into @bookmark and returns the file&apos;s full path in 
@full_path.  If the file could not be loaded then an %error is
set to either a #GFileError or #GBookmarkFileError.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="file">
<parameter_description> a relative path to a filename to open and parse
</parameter_description>
</parameter>
<parameter name="full_path">
<parameter_description> return location for a string containing the full path
of the file, or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if a key file could be loaded, %FALSE othewise

Since: 2.12
</return>
</function>

<function name="g_base64_decode_step">
<description>
Incrementally decode a sequence of binary data from its Base-64 stringified
representation. By calling this function multiple times you can convert 
data in chunks to avoid having to have the full encoded data in memory.

The output buffer must be large enough to fit all the data that will
be written to it. Since base64 encodes 3 bytes in 4 chars you need
at least: @len * 3 / 4 bytes.


</description>
<parameters>
<parameter name="in">
<parameter_description> binary input data
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> max length of @in data to decode
</parameter_description>
</parameter>
<parameter name="out">
<parameter_description> output buffer
</parameter_description>
</parameter>
<parameter name="state">
<parameter_description> Saved state between steps, initialize to 0
</parameter_description>
</parameter>
<parameter name="save">
<parameter_description> Saved state between steps, initialize to 0
</parameter_description>
</parameter>
</parameters>
<return> The number of bytes of output that was written

Since: 2.12
</return>
</function>

<function name="g_convert">
<description>
Converts a string from one character set to another.

Note that you should use g_iconv() for streaming 
conversions&amp;lt;footnoteref linkend=&quot;streaming-state&quot;/&amp;gt;.


</description>
<parameters>
<parameter name="str">
<parameter_description>           the string to convert
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description>           the length of the string, or -1 if the string is 
nul-terminated&amp;lt;footnote id=&quot;nul-unsafe&quot;&amp;gt;
                     &amp;lt;para&amp;gt;
                       Note that some encodings may allow nul bytes to 
                       occur inside strings. In that case, using -1 for 
                       the @len parameter is unsafe.
                     &amp;lt;/para&amp;gt;
                   &amp;lt;/footnote&amp;gt;. 
</parameter_description>
</parameter>
<parameter name="to_codeset">
<parameter_description>    name of character set into which to convert @str
</parameter_description>
</parameter>
<parameter name="from_codeset">
<parameter_description>  character set of @str.
</parameter_description>
</parameter>
<parameter name="bytes_read">
<parameter_description>    location to store the number of bytes in the
input string that were successfully converted, or %NULL.
Even if the conversion was successful, this may be 
less than @len if there were partial characters
at the end of the input. If the error
#G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
stored will the byte offset after the last valid
input sequence.
</parameter_description>
</parameter>
<parameter name="bytes_written">
<parameter_description> the number of bytes stored in the output buffer (not 
including the terminating nul).
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description>         location to store the error occuring, or %NULL to ignore
errors. Any of the errors in #GConvertError may occur.
</parameter_description>
</parameter>
</parameters>
<return> If the conversion was successful, a newly allocated
nul-terminated string, which must be freed with
g_free(). Otherwise %NULL and @error will be set.
</return>
</function>

<function name="g_sequence_range_get_midpoint">
<description>
Finds an iterator somewhere in the range (@begin, @end). This
iterator will be close to the middle of the range, but is not
guaranteed to be &amp;lt;emphasis&amp;gt;exactly&amp;lt;/emphasis&amp;gt; in the middle.

The @begin and @end iterators must both point to the same sequence and
@begin must come before or be equal to @end in the sequence.


</description>
<parameters>
<parameter name="begin">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
<parameter name="end">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
</parameters>
<return> A #GSequenceIter pointing somewhere in the
(@begin, @end) range.

Since: 2.14
</return>
</function>

<function name="g_main_context_add_poll">
<description>
Adds a file descriptor to the set of file descriptors polled for
this context. This will very seldomly be used directly. Instead
a typical event source will use g_source_add_poll() instead.

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext (or %NULL for the default context)
</parameter_description>
</parameter>
<parameter name="fd">
<parameter_description> a #GPollFD structure holding information about a file
descriptor to watch.
</parameter_description>
</parameter>
<parameter name="priority">
<parameter_description> the priority for this file descriptor which should be
the same as the priority used for g_source_attach() to ensure that the
file descriptor is polled whenever the results may be needed.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_option_group_set_translation_domain">
<description>
A convenience function to use gettext() for translating
user-visible strings. 

Since: 2.6

</description>
<parameters>
<parameter name="group">
<parameter_description> a #GOptionGroup
</parameter_description>
</parameter>
<parameter name="domain">
<parameter_description> the domain to use
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_option_context_get_main_group">
<description>
Return value: the main group of @context, or %NULL if @context doesn&apos;t

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GOptionContext
</parameter_description>
</parameter>
</parameters>
<return> the main group of @context, or %NULL if @context doesn&apos;t
have a main group. Note that group belongs to @context and should
not be modified or freed.

Since: 2.6
</return>
</function>

<function name="g_unicode_canonical_ordering">
<description>
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. 

</description>
<parameters>
<parameter name="string">
<parameter_description> a UCS-4 encoded string.
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the maximum length of @string to use.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_ascii_strdown">
<description>
Converts all upper case ASCII letters to lower case ASCII letters.


</description>
<parameters>
<parameter name="str">
<parameter_description> a string.
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> length of @str in bytes, or -1 if @str is nul-terminated.
</parameter_description>
</parameter>
</parameters>
<return> a newly-allocated string, with all the upper case
characters in @str converted to lower case, with
semantics that exactly match g_ascii_tolower(). (Note
that this is unlike the old g_strdown(), which modified
the string in place.)
</return>
</function>

<function name="g_bookmark_file_get_groups">
<description>
Retrieves the list of group names of the bookmark for @uri.

In the event the URI cannot be found, %NULL is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.

The returned array is %NULL terminated, so @length may optionally
be %NULL.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> return location for the length of the returned string, or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated %NULL-terminated array of group names.
Use g_strfreev() to free it.

Since: 2.12
</return>
</function>

<function name="g_freopen">
<description>
A wrapper for the POSIX freopen() function. The freopen() function
opens a file and associates it with an existing stream.

See the C library manual for more details about freopen().


</description>
<parameters>
<parameter name="filename">
<parameter_description> a pathname in the GLib file name encoding (UTF-8 on Windows)
</parameter_description>
</parameter>
<parameter name="mode">
<parameter_description> a string describing the mode in which the file should be 
opened
</parameter_description>
</parameter>
<parameter name="stream">
<parameter_description> an existing stream which will be reused, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> A &amp;lt;type&amp;gt;FILE&amp;lt;/type&amp;gt; pointer if the file was successfully
opened, or %NULL if an error occurred.

Since: 2.6
</return>
</function>

<function name="g_queue_foreach">
<description>
Calls @func for each element in the queue passing @user_data to the
function.

Since: 2.4

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> the function to call for each element&apos;s data
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data to pass to @func
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_queue_remove">
<description>
Removes the first element in @queue that contains @data. 

Since: 2.4

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> data to remove.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_str_equal">
<description>
Compares two strings for byte-by-byte equality and returns %TRUE 
if they are equal. It can be passed to g_hash_table_new() as the 
@key_equal_func parameter, when using strings as keys in a #GHashTable.


</description>
<parameters>
<parameter name="v1">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="v2">
<parameter_description> a key to compare with @v1
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the two keys match
</return>
</function>

<function name="g_key_file_get_start_group">
<description>
Return value: The start group of the key file.

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
</parameters>
<return> The start group of the key file.

Since: 2.6
</return>
</function>

<function name="g_tree_lookup">
<description>
Gets the value corresponding to the given key. Since a #GTree is 
automatically balanced as key/value pairs are added, key lookup is very 
fast.


</description>
<parameters>
<parameter name="tree">
<parameter_description> a #GTree.
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> the key to look up.
</parameter_description>
</parameter>
</parameters>
<return> the value corresponding to the key, or %NULL if the key was
not found.
</return>
</function>

<function name="g_hash_table_destroy">
<description>
Destroys all keys and values in the #GHashTable and decrements its
reference count by 1. If keys and/or values are dynamically allocated,
you should either free them first or create the #GHashTable with destroy
notifiers using g_hash_table_new_full(). In the latter case the destroy
functions you supplied will be called on all keys and values during the
destruction phase.

</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a #GHashTable.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_key_file_get_double">
<description>
Return value: the value associated with the key as a double, or

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError
</parameter_description>
</parameter>
</parameters>
<return> the value associated with the key as a double, or
0.0 if the key was not found or could not be parsed.

Since: 2.12
</return>
</function>

<function name="g_bookmark_file_has_item">
<description>
Looks whether the desktop bookmark has an item with its URI set to @uri.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @uri is inside @bookmark, %FALSE otherwise

Since: 2.12
</return>
</function>

<function name="g_thread_pool_get_max_idle_time">
<description>
This function will return the maximum @interval that a thread will
wait in the thread pool for new tasks before being stopped.

If this function returns 0, threads waiting in the thread pool for
new work are not stopped.


</description>
<parameters>
</parameters>
<return> the maximum @interval to wait for new tasks in the
thread pool before stopping the thread (1/1000ths of a second).

Since: 2.10
</return>
</function>

<function name="g_async_queue_ref">
<description>
Increases the reference count of the asynchronous @queue by 1. You
do not need to hold the lock to call this function.


</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue.
</parameter_description>
</parameter>
</parameters>
<return> the @queue that was passed in (since 2.6)
</return>
</function>

<function name="g_string_erase">
<description>
Removes @len bytes from a #GString, starting at position @pos.
The rest of the #GString is shifted down to fill the gap.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="pos">
<parameter_description> the position of the content to remove
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the number of bytes to remove, or -1 to remove all
following bytes
</parameter_description>
</parameter>
</parameters>
<return> @string
</return>
</function>

<function name="g_get_user_data_dir">
<description>
Return value: a string owned by GLib that must not be modified 

</description>
<parameters>
</parameters>
<return> a string owned by GLib that must not be modified 
or freed.
Since: 2.6
</return>
</function>

<function name="g_ascii_strncasecmp">
<description>
Compare @s1 and @s2, ignoring the case of ASCII characters and any
characters after the first @n in each string.

Unlike the BSD strcasecmp() function, this only recognizes standard
ASCII letters and ignores the locale, treating all non-ASCII
characters as if they are not letters.

The same warning as in g_ascii_strcasecmp() applies: Use this
function only on strings known to be in encodings where bytes
corresponding to ASCII letters always represent themselves.


</description>
<parameters>
<parameter name="s1">
<parameter_description> string to compare with @s2.
</parameter_description>
</parameter>
<parameter name="s2">
<parameter_description> string to compare with @s1.
</parameter_description>
</parameter>
<parameter name="n">
<parameter_description>  number of characters to compare.
</parameter_description>
</parameter>
</parameters>
<return> 0 if the strings match, a negative value if @s1 &amp;lt; @s2, 
or a positive value if @s1 &amp;gt; @s2.
</return>
</function>

<function name="g_source_unref">
<description>
Decreases the reference count of a source by one. If the
resulting reference count is zero the source and associated
memory will be destroyed. 

</description>
<parameters>
<parameter name="source">
<parameter_description> a #GSource
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_hash_table_ref">
<description>
Atomically increments the reference count of @hash_table by one.
This function is MT-safe and may be called from any thread.


</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a valid #GHashTable.
</parameter_description>
</parameter>
</parameters>
<return> the passed in #GHashTable.

Since: 2.10
</return>
</function>

<function name="g_main_loop_run">
<description>
Runs a main loop until g_main_loop_quit() is called on the loop.
If this is called for the thread of the loop&apos;s #GMainContext,
it will process events from the loop, otherwise it will
simply wait.

</description>
<parameters>
<parameter name="loop">
<parameter_description> a #GMainLoop
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_queue_push_head_link">
<description>
Adds a new element at the head of the queue.

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue.
</parameter_description>
</parameter>
<parameter name="link_">
<parameter_description> a single #GList element, &amp;lt;emphasis&amp;gt;not&amp;lt;/emphasis&amp;gt; a list with
more than one element.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_unichar_iswide">
<description>
Determines if a character is typically rendered in a double-width
cell.


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the character is wide
</return>
</function>

<function name="g_strdown">
<description>
Converts a string to lower case.  


</description>
<parameters>
<parameter name="string">
<parameter_description> the string to convert.
</parameter_description>
</parameter>
</parameters>
<return> the string 

Deprecated:2.2: This function is totally broken for the reasons discussed 
in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown() 
instead.
</return>
</function>

<function name="g_queue_find_custom">
<description>
Finds an element in a #GQueue, using a supplied function to find the
desired element. It iterates over the queue, calling the given function
which should return 0 when the desired element is found. The function
takes two gconstpointer arguments, the #GQueue element&apos;s data as the
first argument and the given user data as the second argument.


</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> user data passed to @func
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> a #GCompareFunc to call for each element. It should return 0
when the desired element is found
</parameter_description>
</parameter>
</parameters>
<return> The found link, or %NULL if it wasn&apos;t found

Since: 2.4
</return>
</function>

<function name="g_regex_get_capture_count">
<description>
Returns: the number of capturing subpatterns

</description>
<parameters>
<parameter name="regex">
<parameter_description> a #GRegex
</parameter_description>
</parameter>
</parameters>
<return> the number of capturing subpatterns

Since: 2.14
</return>
</function>

<function name="g_option_group_set_error_hook">
<description>
Associates a function with @group which will be called 
from g_option_context_parse() when an error occurs.

Note that the user data to be passed to @pre_parse_func and
@post_parse_func can be specified when constructing the group
with g_option_group_new().

Since: 2.6

</description>
<parameters>
<parameter name="group">
<parameter_description> a #GOptionGroup
</parameter_description>
</parameter>
<parameter name="error_func">
<parameter_description> a function to call when an error occurs
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_unichar_validate">
<description>
Checks whether @ch is a valid Unicode character. Some possible
integer values of @ch will not be valid. 0 is considered a valid
character, though it&apos;s normally a string terminator.


</description>
<parameters>
<parameter name="ch">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @ch is a valid Unicode character
</return>
</function>

<function name="g_thread_pool_free">
<description>
Frees all resources allocated for @pool.

If @immediate is %TRUE, no new task is processed for
@pool. Otherwise @pool is not freed before the last task is
processed. Note however, that no thread of this pool is
interrupted, while processing a task. Instead at least all still
running threads can finish their tasks before the @pool is freed.

If @wait_ is %TRUE, the functions does not return before all tasks
to be processed (dependent on @immediate, whether all or only the
currently running) are ready. Otherwise the function returns immediately.

After calling this function @pool must not be used anymore. 

</description>
<parameters>
<parameter name="pool">
<parameter_description> a #GThreadPool
</parameter_description>
</parameter>
<parameter name="immediate">
<parameter_description> should @pool shut down immediately?
</parameter_description>
</parameter>
<parameter name="wait_">
<parameter_description> should the function wait for all tasks to be finished?
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_bookmark_file_get_modified">
<description>
Gets the time when the bookmark for @uri was last modified.

In the event the URI cannot be found, -1 is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a timestamp

Since: 2.12
</return>
</function>

<function name="g_utf8_prev_char">
<description>
Finds the previous UTF-8 character in the string before @p.

@p does not have to be at the beginning of a UTF-8 character. No check
is made to see if the character found is actually valid other than
it starts with an appropriate byte. If @p might be the first
character of the string, you must use g_utf8_find_prev_char() instead.


</description>
<parameters>
<parameter name="p">
<parameter_description> a pointer to a position within a UTF-8 encoded string
</parameter_description>
</parameter>
</parameters>
<return> a pointer to the found character.
</return>
</function>

<function name="g_fprintf">
<description>
An implementation of the standard fprintf() function which supports 
positional parameters, as specified in the Single Unix Specification.


</description>
<parameters>
<parameter name="file">
<parameter_description> the stream to write to.
</parameter_description>
</parameter>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice 
&amp;lt;link linkend=&quot;string-precision&quot;&amp;gt;string precision pitfalls&amp;lt;/link&amp;gt;.
</parameter_description>
</parameter>
<parameter name="Varargs">
<parameter_description> the arguments to insert in the output.
</parameter_description>
</parameter>
</parameters>
<return> the number of characters printed.

Since: 2.2
</return>
</function>

<function name="find_conversion">
<description>
Find the next conversion in a printf-style format string.
Partially based on code from printf-parser.c,
Copyright (C) 1999-2000, 2002-2003 Free Software Foundation, Inc.


</description>
<parameters>
<parameter name="format">
<parameter_description> a printf-style format string
</parameter_description>
</parameter>
<parameter name="after">
<parameter_description> location to store a pointer to the character after
the returned conversion. On a %NULL return, returns the
pointer to the trailing NUL in the string
</parameter_description>
</parameter>
</parameters>
<return> pointer to the next conversion in @format,
or %NULL, if none.
</return>
</function>

<function name="g_filename_from_utf8">
<description>
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 
&amp;lt;link linkend=&quot;setlocale&quot;&amp;gt;current locale&amp;lt;/link&amp;gt;.


</description>
<parameters>
<parameter name="utf8string">
<parameter_description>    a UTF-8 encoded string.
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description>           the length of the string, or -1 if the string is
nul-terminated.
</parameter_description>
</parameter>
<parameter name="bytes_read">
<parameter_description>    location to store the number of bytes in the
input string that were successfully converted, or %NULL.
Even if the conversion was successful, this may be 
less than @len if there were partial characters
at the end of the input. If the error
#G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
stored will the byte offset after the last valid
input sequence.
</parameter_description>
</parameter>
<parameter name="bytes_written">
<parameter_description> the number of bytes stored in the output buffer (not 
including the terminating nul).
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description>         location to store the error occuring, or %NULL to ignore
errors. Any of the errors in #GConvertError may occur.
</parameter_description>
</parameter>
</parameters>
<return> The converted string, or %NULL on an error.
</return>
</function>

<function name="g_get_host_name">
<description>
Return a name for the machine. 

The returned name is not necessarily a fully-qualified domain name,
or even present in DNS or some other name service at all. It need
not even be unique on your local network or site, but usually it
is. Callers should not rely on the return value having any specific
properties like uniqueness for security purposes. Even if the name
of the machine is changed while an application is running, the
return value from this function does not change. The returned
string is owned by GLib and should not be modified or freed. If no
name can be determined, a default fixed string &quot;localhost&quot; is
returned.


</description>
<parameters>
</parameters>
<return> the host name of the machine.

Since: 2.8
</return>
</function>

<function name="g_spawn_command_line_async">
<description>
A simple version of g_spawn_async() that parses a command line with
g_shell_parse_argv() and passes it to g_spawn_async(). Runs a
command line in the background. Unlike g_spawn_async(), the
%G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note
that %G_SPAWN_SEARCH_PATH can have security implications, so
consider using g_spawn_async() directly if appropriate. Possible
errors are those from g_shell_parse_argv() and g_spawn_async().

The same concerns on Windows apply as for g_spawn_command_line_sync().


</description>
<parameters>
<parameter name="command_line">
<parameter_description> a command line
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for errors
</parameter_description>
</parameter>
</parameters>
<return> %TRUE on success, %FALSE if error is set.
</return>
</function>

<function name="g_hash_table_lookup">
<description>
Looks up a key in a #GHashTable. Note that this function cannot
distinguish between a key that is not present and one which is present
and has the value %NULL. If you need this distinction, use
g_hash_table_lookup_extended().


</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a #GHashTable.
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> the key to look up.
</parameter_description>
</parameter>
</parameters>
<return> the associated value, or %NULL if the key is not found.
</return>
</function>

<function name="g_random_double_range">
<description>
Return value: A random number.

</description>
<parameters>
<parameter name="begin">
<parameter_description> lower closed bound of the interval.
</parameter_description>
</parameter>
<parameter name="end">
<parameter_description> upper open bound of the interval.
</parameter_description>
</parameter>
</parameters>
<return> A random number.
</return>
</function>

<function name="g_time_val_add">
<description>
Adds the given number of microseconds to @time_. @microseconds can
also be negative to decrease the value of @time_.

</description>
<parameters>
<parameter name="time_">
<parameter_description> a #GTimeVal
</parameter_description>
</parameter>
<parameter name="microseconds">
<parameter_description> number of microseconds to add to @time
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_key_file_set_double">
<description>
Associates a new double value with @key under @group_name.
If @key cannot be found then it is created. If @group_name
is %NULL, the start group is used.

Since: 2.12

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="value">
<parameter_description> an double value
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_base64_encode">
<description>
Encode a sequence of binary data into its Base-64 stringified
representation.


</description>
<parameters>
<parameter name="data">
<parameter_description> the binary data to encode
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the length of @data
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated, zero-terminated Base-64 encoded
string representing @data.

Since: 2.12
</return>
</function>

<function name="g_mkdir_with_parents">
<description>
Create a directory if it doesn&apos;t already exist. Create intermediate
parent directories as needed, too.


</description>
<parameters>
<parameter name="pathname">
<parameter_description> a pathname in the GLib file name encoding
</parameter_description>
</parameter>
<parameter name="mode">
<parameter_description> permissions to use for newly created directories
</parameter_description>
</parameter>
</parameters>
<return> 0 if the directory already exists, or was successfully
created. Returns -1 if an error occurred, with errno set.

Since: 2.8
</return>
</function>

<function name="g_option_context_new">
<description>
Creates a new option context. 

The @parameter_string can serve multiple purposes. It can be used
to add descriptions for &quot;rest&quot; arguments, which are not parsed by
the #GOptionContext, typically something like &quot;FILES&quot; or
&quot;FILE1 FILE2...&quot;. If you are using #G_OPTION_REMAINING for
collecting &quot;rest&quot; arguments, GLib handles this automatically by
using the @arg_description of the corresponding #GOptionEntry in
the usage summary.

Another usage is to give a short summary of the program
functionality, like &quot; - frob the strings&quot;, which will be displayed
in the same line as the usage. For a longer description of the
program functionality that should be displayed as a paragraph
below the usage line, use g_option_context_set_summary().

Note that the @parameter_string is translated (see
g_option_context_set_translate_func()). 


</description>
<parameters>
<parameter name="parameter_string">
<parameter_description> a string which is displayed in
the first line of &amp;lt;option&amp;gt;--help&amp;lt;/option&amp;gt; output, after the
usage summary 
&amp;lt;literal&amp;gt;&amp;lt;replaceable&amp;gt;programname&amp;lt;/replaceable&amp;gt; [OPTION...]&amp;lt;/literal&amp;gt;
</parameter_description>
</parameter>
</parameters>
<return> a newly created #GOptionContext, which must be
freed with g_option_context_free() after use.

Since: 2.6
</return>
</function>

<function name="g_io_channel_write_unichar">
<description>
This function cannot be called on a channel with %NULL encoding.


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
<parameter name="thechar">
<parameter_description> a character
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> A location to return an error of type #GConvertError
or #GIOChannelError
</parameter_description>
</parameter>
</parameters>
<return> a #GIOStatus
</return>
</function>

<function name="g_child_watch_add">
<description>
Sets a function to be called when the child indicated by @pid 
exits, at a default priority, #G_PRIORITY_DEFAULT.

If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() 
you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to 
the spawn function for the child watching to work.

Note that on platforms where #GPid must be explicitly closed
(see g_spawn_close_pid()) @pid must not be closed while the
source is still active. Typically, you will want to call
g_spawn_close_pid() in the callback function for the source.

GLib supports only a single callback per process id.


</description>
<parameters>
<parameter name="pid">
<parameter_description>      process id of a child process to watch
</parameter_description>
</parameter>
<parameter name="function">
<parameter_description> function to call
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description>     data to pass to @function
</parameter_description>
</parameter>
</parameters>
<return> the ID (greater than 0) of the event source.

Since: 2.4
</return>
</function>

<function name="g_async_queue_length_unlocked">
<description>
Return value: the length of the @queue.

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue.
</parameter_description>
</parameter>
</parameters>
<return> the length of the @queue.
</return>
</function>

<function name="g_string_chunk_insert">
<description>
Adds a copy of @string to the #GStringChunk.
It returns a pointer to the new copy of the string 
in the #GStringChunk. The characters in the string 
can be changed, if necessary, though you should not 
change anything after the end of the string.

Unlike g_string_chunk_insert_const(), this function 
does not check for duplicates. Also strings added 
with g_string_chunk_insert() will not be searched 
by g_string_chunk_insert_const() when looking for 
duplicates.


</description>
<parameters>
<parameter name="chunk">
<parameter_description> a #GStringChunk
</parameter_description>
</parameter>
<parameter name="string">
<parameter_description> the string to add
</parameter_description>
</parameter>
</parameters>
<return> a pointer to the copy of @string within 
the #GStringChunk
</return>
</function>

<function name="g_find_program_in_path">
<description>
Locates the first executable named @program in the user&apos;s path, in the
same way that execvp() would locate it. Returns an allocated string
with the absolute path name, or %NULL if the program is not found in
the path. If @program is already an absolute path, returns a copy of
@program if @program exists and is executable, and %NULL otherwise.

On Windows, if @program does not have a file type suffix, tries
with the suffixes .exe, .cmd, .bat and .com, and the suffixes in
the &amp;lt;envar&amp;gt;PATHEXT&amp;lt;/envar&amp;gt; environment variable. 

On Windows, it looks for the file in the same way as CreateProcess() 
would. This means first in the directory where the executing
program was loaded from, then in the current directory, then in the
Windows 32-bit system directory, then in the Windows directory, and
finally in the directories in the &amp;lt;envar&amp;gt;PATH&amp;lt;/envar&amp;gt; environment 
variable. If the program is found, the return value contains the 
full name including the type suffix.


</description>
<parameters>
<parameter name="program">
<parameter_description> a program name in the GLib file name encoding
</parameter_description>
</parameter>
</parameters>
<return> absolute path, or %NULL
</return>
</function>

<function name="g_error_free">
<description>
Frees a #GError and associated resources.


</description>
<parameters>
<parameter name="error">
<parameter_description> a #GError
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_idle_add">
<description>
Adds a function to be called whenever there are no higher priority
events pending to the default main loop. The function is given the
default idle priority, #G_PRIORITY_DEFAULT_IDLE.  If the function
Return value: the ID (greater than 0) of the event source.

</description>
<parameters>
<parameter name="function">
<parameter_description> function to call 
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> data to pass to @function.
</parameter_description>
</parameter>
</parameters>
<return> the ID (greater than 0) of the event source.
</return>
</function>

<function name="g_string_append_printf">
<description>
Appends a formatted string onto the end of a #GString.
This function is is similar to g_string_printf() except 
that the text is appended to the #GString.

</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="format">
<parameter_description> the string format. See the printf() documentation
</parameter_description>
</parameter>
<parameter name="Varargs">
<parameter_description> the parameters to insert into the format string
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_random_double">
<description>
Return value: A random number.

</description>
<parameters>
</parameters>
<return> A random number.
</return>
</function>

<function name="g_markup_printf_escaped">
<description>
Formats arguments according to @format, escaping
all string and character arguments in the fashion
of g_markup_escape_text(). This is useful when you
want to insert literal strings into XML-style markup
output, without having to worry that the strings
might themselves contain markup.

&amp;lt;informalexample&amp;gt;&amp;lt;programlisting&amp;gt;
const char *store = &quot;Fortnum &amp;amp; Mason&quot;;
const char *item = &quot;Tea&quot;;
char *output;
&amp;nbsp;
output = g_markup_printf_escaped (&quot;&amp;lt;purchase&amp;gt;&quot;
&quot;&amp;lt;store&amp;gt;&amp;percnt;s&amp;lt;/store&amp;gt;&quot;
&quot;&amp;lt;item&amp;gt;&amp;percnt;s&amp;lt;/item&amp;gt;&quot;
&quot;&amp;lt;/purchase&amp;gt;&quot;,
store, item);
&amp;lt;/programlisting&amp;gt;&amp;lt;/informalexample&amp;gt;


</description>
<parameters>
<parameter name="format">
<parameter_description> printf() style format string
</parameter_description>
</parameter>
<parameter name="Varargs">
<parameter_description> the arguments to insert in the format string
</parameter_description>
</parameter>
</parameters>
<return> newly allocated result from formatting
operation. Free with g_free().

Since: 2.4
</return>
</function>

<function name="g_utf8_find_prev_char">
<description>
Given a position @p with a UTF-8 encoded string @str, find the start
of the previous UTF-8 character starting before @p. Returns %NULL if no
UTF-8 characters are present in @str before @p.

@p does not have to be at the beginning of a UTF-8 character. No check
is made to see if the character found is actually valid other than
it starts with an appropriate byte.


</description>
<parameters>
<parameter name="str">
<parameter_description> pointer to the beginning of a UTF-8 encoded string
</parameter_description>
</parameter>
<parameter name="p">
<parameter_description> pointer to some position within @str
</parameter_description>
</parameter>
</parameters>
<return> a pointer to the found character or %NULL.
</return>
</function>

<function name="g_sequence_search_iter">
<description>
Like g_sequence_search(), but uses
a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as
the compare function.


</description>
<parameters>
<parameter name="seq">
<parameter_description> a #GSequence
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> data for the new item
</parameter_description>
</parameter>
<parameter name="iter_cmp">
<parameter_description> the #GSequenceIterCompare function used to compare iterators
in the sequence. It is called with two iterators pointing into @seq.
It should return 0 if the iterators are equal, a negative value if the
first iterator comes before the second, and a positive value if the
second iterator comes before the first.
</parameter_description>
</parameter>
<parameter name="cmp_data">
<parameter_description> user data passed to @iter_cmp
</parameter_description>
</parameter>
</parameters>
<return> a #GSequenceIter pointing to the position in @seq
where @data would have been inserted according to @iter_cmp and @cmp_data.

Since: 2.14
</return>
</function>

<function name="g_sequence_move">
<description>
Moves the item pointed to by @src to the position indicated by @dest.
After calling this function @dest will point to the position immediately
after @src. It is allowed for @src and @dest to point into different
sequences.

Since: 2.14

</description>
<parameters>
<parameter name="src">
<parameter_description> a #GSequenceIter pointing to the item to move
</parameter_description>
</parameter>
<parameter name="dest">
<parameter_description> a #GSequenceIter pointing to the position to which
the item is moved.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_string_vprintf">
<description>
Writes a formatted string into a #GString. 
This function is similar to g_string_printf() except that 
the arguments to the format string are passed as a va_list.

Since: 2.14

</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="format">
<parameter_description> the string format. See the printf() documentation
</parameter_description>
</parameter>
<parameter name="args">
<parameter_description> the parameters to insert into the format string
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_main_context_unref">
<description>
Decreases the reference count on a #GMainContext object by one. If
the result is zero, free the context and free all associated memory.

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_listenv">
<description>
Gets the names of all variables set in the environment.


</description>
<parameters>
</parameters>
<return> a %NULL-terminated list of strings which must be freed
with g_strfreev().

Programs that want to be portable to Windows should typically use
this function and g_getenv() instead of using the environ array
from the C library directly. On Windows, the strings in the environ
array are in system codepage encoding, while in most of the typical
use cases for environment variables in GLib-using programs you want
the UTF-8 encoding that this function and g_getenv() provide.

Since: 2.8
</return>
</function>

<function name="g_timeout_add_seconds">
<description>
Sets a function to be called at regular intervals with the default
priority, #G_PRIORITY_DEFAULT. The function is called repeatedly until
it returns %FALSE, at which point the timeout is automatically destroyed
and the function will not be called again.

See g_timeout_add_seconds_full() for the differences between
g_timeout_add() and g_timeout_add_seconds().


</description>
<parameters>
<parameter name="interval">
<parameter_description> the time between calls to the function, in seconds
</parameter_description>
</parameter>
<parameter name="function">
<parameter_description> function to call
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> data to pass to @function
</parameter_description>
</parameter>
</parameters>
<return> the ID (greater than 0) of the event source.

Since: 2.14
</return>
</function>

<function name="g_bookmark_file_set_added">
<description>
Sets the time the bookmark for @uri was added into @bookmark.

If no bookmark for @uri is found then it is created.

Since: 2.12

</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="added">
<parameter_description> a timestamp or -1 to use the current time
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_sequence_set">
<description>
Changes the data for the item pointed to by @iter to be @data. If
the sequence has a data destroy function associated with it, that
function is called on the existing data that @iter pointed to.

Since: 2.14

</description>
<parameters>
<parameter name="iter">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> new data for the item
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_main_context_is_owner">
<description>
Determines whether this thread holds the (recursive)
ownership of this #GMaincontext. This is useful to
know before waiting on another thread that may be
blocking to get ownership of @context.


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if current thread is owner of @context.

Since: 2.10
</return>
</function>

<function name="g_random_int">
<description>
Return a random #guint32 equally distributed over the range
[0..2^32-1].


</description>
<parameters>
</parameters>
<return> A random number.
</return>
</function>

<function name="g_get_current_time">
<description>
Equivalent to the UNIX gettimeofday() function, but portable.

</description>
<parameters>
<parameter name="result">
<parameter_description> #GTimeVal structure in which to store current time.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_unichar_break_type">
<description>
Determines the break type of @c. @c should be a Unicode character
(to derive a character from UTF-8 encoded text, use
g_utf8_get_char()). The break type is used to find word and line
breaks (&quot;text boundaries&quot;), Pango implements the Unicode boundary
resolution algorithms and normally you would use a function such
as pango_break() instead of caring about break types yourself.


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> the break type of @c
</return>
</function>

<function name="g_hash_table_steal">
<description>
Removes a key and its associated value from a #GHashTable without
calling the key and value destroy functions.


</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a #GHashTable.
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> the key to remove.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the key was found and removed from the #GHashTable.
</return>
</function>

<function name="g_sequence_get_length">
<description>
Return value: the length of @seq

</description>
<parameters>
<parameter name="seq">
<parameter_description> a #GSequence
</parameter_description>
</parameter>
</parameters>
<return> the length of @seq

Since: 2.14
</return>
</function>

<function name="g_source_set_callback_indirect">
<description>
Sets the callback function storing the data as a refcounted callback
&quot;object&quot;. This is used internally. Note that calling 
g_source_set_callback_indirect() assumes
an initial reference count on @callback_data, and thus
@callback_funcs-&amp;gt;unref will eventually be called once more
than @callback_funcs-&amp;gt;ref.

</description>
<parameters>
<parameter name="source">
<parameter_description> the source
</parameter_description>
</parameter>
<parameter name="callback_data">
<parameter_description> pointer to callback data &quot;object&quot;
</parameter_description>
</parameter>
<parameter name="callback_funcs">
<parameter_description> functions for reference counting @callback_data
and getting the callback and data
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_date_set_time">
<description>
Sets the value of a date from a #GTime value. 

@Deprecated:2.10: Use g_date_set_time_t() instead.

</description>
<parameters>
<parameter name="date">
<parameter_description> a #GDate.
</parameter_description>
</parameter>
<parameter name="time_">
<parameter_description> #GTime value to set.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_string_new_len">
<description>
Creates a new #GString with @len bytes of the @init buffer.  
Because a length is provided, @init need not be nul-terminated,
and can contain embedded nul bytes.

Since this function does not stop at nul bytes, it is the caller&apos;s
responsibility to ensure that @init has at least @len addressable 
bytes.


</description>
<parameters>
<parameter name="init">
<parameter_description> initial contents of the string
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> length of @init to use
</parameter_description>
</parameter>
</parameters>
<return> a new #GString
</return>
</function>

<function name="g_queue_push_tail">
<description>
Adds a new element at the tail of the queue.

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue.
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> the data for the new element.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_access">
<description>
A wrapper for the POSIX access() function. This function is used to
test a pathname for one or several of read, write or execute
permissions, or just existence. On Windows, the underlying access()
function in the C library only checks the READONLY attribute, and
does not look at the ACL at all. Software that needs to handle file
permissions on Windows more exactly should use the Win32 API.

See the C library manual for more details about access().


</description>
<parameters>
<parameter name="filename">
<parameter_description> a pathname in the GLib file name encoding (UTF-8 on Windows)
</parameter_description>
</parameter>
<parameter name="mode">
<parameter_description> as in access()
</parameter_description>
</parameter>
</parameters>
<return> zero if the pathname refers to an existing file system
object that has all the tested permissions, or -1 otherwise or on
error.

Since: 2.8
</return>
</function>

<function name="g_match_info_free">
<description>
Frees all the memory associated with the #GMatchInfo structure.

Since: 2.14

</description>
<parameters>
<parameter name="match_info">
<parameter_description> a #GMatchInfo
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_key_file_has_group">
<description>
Looks whether the key file has the group @group_name.


</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @group_name is a part of @key_file, %FALSE
otherwise.
Since: 2.6
</return>
</function>

<function name="g_strndup">
<description>
Duplicates the first @n bytes of a string, returning a newly-allocated
buffer @n + 1 bytes long which will always be nul-terminated.
If @str is less than @n bytes long the buffer is padded with nuls.
If @str is %NULL it returns %NULL.
The returned value should be freed when no longer needed.

&amp;lt;note&amp;gt;&amp;lt;para&amp;gt;
To copy a number of characters from a UTF-8 encoded string, use
g_utf8_strncpy() instead.
&amp;lt;/para&amp;gt;&amp;lt;/note&amp;gt;


</description>
<parameters>
<parameter name="str">
<parameter_description> the string to duplicate
</parameter_description>
</parameter>
<parameter name="n">
<parameter_description> the maximum number of bytes to copy from @str
</parameter_description>
</parameter>
</parameters>
<return> a newly-allocated buffer containing the first @n bytes 
of @str, nul-terminated 
</return>
</function>

<function name="g_queue_pop_head">
<description>
Removes the first element of the queue.


</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue.
</parameter_description>
</parameter>
</parameters>
<return> the data of the first element in the queue, or %NULL if the queue
is empty.
</return>
</function>

<function name="g_queue_peek_head">
<description>
Returns: the data of the first element in the queue, or %NULL if the queue

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue.
</parameter_description>
</parameter>
</parameters>
<return> the data of the first element in the queue, or %NULL if the queue
is empty.
</return>
</function>

<function name="g_option_group_set_parse_hooks">
<description>
Associates two functions with @group which will be called 
from g_option_context_parse() before the first option is parsed
and after the last option has been parsed, respectively.

Note that the user data to be passed to @pre_parse_func and
@post_parse_func can be specified when constructing the group
with g_option_group_new().

Since: 2.6

</description>
<parameters>
<parameter name="group">
<parameter_description> a #GOptionGroup
</parameter_description>
</parameter>
<parameter name="pre_parse_func">
<parameter_description> a function to call before parsing, or %NULL
</parameter_description>
</parameter>
<parameter name="post_parse_func">
<parameter_description> a function to call after parsing, or %NULL
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_regex_replace">
<description>
Replaces all occurances of the pattern in @regex with the
replacement text. Backreferences of the form &apos;\number&apos; or 
&apos;\g&amp;lt;number&amp;gt;&apos; in the replacement text are interpolated by the 
number-th captured subexpression of the match, &apos;\g&amp;lt;name&amp;gt;&apos; refers 
to the captured subexpression with the given name. &apos;\0&apos; refers to the 
complete match, but &apos;\0&apos; followed by a number is the octal representation 
of a character. To include a literal &apos;\&apos; in the replacement, write &apos;\\&apos;.
There are also escapes that changes the case of the following text:

&amp;lt;variablelist&amp;gt;
&amp;lt;varlistentry&amp;gt;&amp;lt;term&amp;gt;\l&amp;lt;/term&amp;gt;
&amp;lt;listitem&amp;gt;
&amp;lt;para&amp;gt;Convert to lower case the next character&amp;lt;/para&amp;gt;
&amp;lt;/listitem&amp;gt;
&amp;lt;/varlistentry&amp;gt;
&amp;lt;varlistentry&amp;gt;&amp;lt;term&amp;gt;\u&amp;lt;/term&amp;gt;
&amp;lt;listitem&amp;gt;
&amp;lt;para&amp;gt;Convert to upper case the next character&amp;lt;/para&amp;gt;
&amp;lt;/listitem&amp;gt;
&amp;lt;/varlistentry&amp;gt;
&amp;lt;varlistentry&amp;gt;&amp;lt;term&amp;gt;\L&amp;lt;/term&amp;gt;
&amp;lt;listitem&amp;gt;
&amp;lt;para&amp;gt;Convert to lower case till \E&amp;lt;/para&amp;gt;
&amp;lt;/listitem&amp;gt;
&amp;lt;/varlistentry&amp;gt;
&amp;lt;varlistentry&amp;gt;&amp;lt;term&amp;gt;\U&amp;lt;/term&amp;gt;
&amp;lt;listitem&amp;gt;
&amp;lt;para&amp;gt;Convert to upper case till \E&amp;lt;/para&amp;gt;
&amp;lt;/listitem&amp;gt;
&amp;lt;/varlistentry&amp;gt;
&amp;lt;varlistentry&amp;gt;&amp;lt;term&amp;gt;\E&amp;lt;/term&amp;gt;
&amp;lt;listitem&amp;gt;
&amp;lt;para&amp;gt;End case modification&amp;lt;/para&amp;gt;
&amp;lt;/listitem&amp;gt;
&amp;lt;/varlistentry&amp;gt;
&amp;lt;/variablelist&amp;gt;

If you do not need to use backreferences use g_regex_replace_literal().

The @replacement string must be UTF-8 encoded even if #G_REGEX_RAW was
passed to g_regex_new(). If you want to use not UTF-8 encoded stings
you can use g_regex_replace_literal().

Setting @start_position differs from just passing over a shortened 
string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern that 
begins with any kind of lookbehind assertion, such as &quot;\b&quot;.


</description>
<parameters>
<parameter name="regex">
<parameter_description> a #GRegex structure
</parameter_description>
</parameter>
<parameter name="string">
<parameter_description> the string to perform matches against
</parameter_description>
</parameter>
<parameter name="string_len">
<parameter_description> the length of @string, or -1 if @string is nul-terminated
</parameter_description>
</parameter>
<parameter name="start_position">
<parameter_description> starting index of the string to match
</parameter_description>
</parameter>
<parameter name="replacement">
<parameter_description> text to replace each match with
</parameter_description>
</parameter>
<parameter name="match_options">
<parameter_description> options for the match
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store the error occuring, or %NULL to ignore errors
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string containing the replacements

Since: 2.14
</return>
</function>

<function name="g_io_channel_set_flags">
<description>
Sets the (writeable) flags in @channel to (@flags &amp; %G_IO_CHANNEL_SET_MASK).


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel.
</parameter_description>
</parameter>
<parameter name="flags">
<parameter_description> the flags to set on the IO channel.
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> A location to return an error of type #GIOChannelError.
</parameter_description>
</parameter>
</parameters>
<return> the status of the operation. 
</return>
</function>

<function name="g_bookmark_file_add_application">
<description>
Adds the application with @name and @exec to the list of
applications that have registered a bookmark for @uri into
@bookmark.

Every bookmark inside a #GBookmarkFile must have at least an
application registered.  Each application must provide a name, a
command line useful for launching the bookmark, the number of times
the bookmark has been registered by the application and the last
time the application registered this bookmark.

If @name is %NULL, the name of the application will be the
same returned by g_get_application(); if @exec is %NULL, the
command line will be a composition of the program name as
returned by g_get_prgname() and the &quot;%u&quot; modifier, which will be
expanded to the bookmark&apos;s URI.

This function will automatically take care of updating the
registrations count and timestamping in case an application
with the same @name had already registered a bookmark for
@uri inside @bookmark.

If no bookmark for @uri is found, one is created.

Since: 2.12

</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="name">
<parameter_description> the name of the application registering the bookmark
or %NULL
</parameter_description>
</parameter>
<parameter name="exec">
<parameter_description> command line to be used to launch the bookmark or %NULL
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_unichar_get_script">
<description>
Looks up the #GUnicodeScript for a particular character (as defined 
by Unicode Standard Annex #24). No check is made for @ch being a
valid Unicode character; if you pass in invalid character, the
result is undefined.


</description>
<parameters>
<parameter name="ch">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> the #GUnicodeScript for the character.

Since: 2.14
</return>
</function>

<function name="g_tree_destroy">
<description>
Destroys the #GTree. If keys and/or values are dynamically allocated, you 
should either free them first or create the #GTree using g_tree_new_full().
In the latter case the destroy functions you supplied will be called on 
all keys and values before destroying the #GTree.

</description>
<parameters>
<parameter name="tree">
<parameter_description> a #GTree.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_dir_close">
<description>
Closes the directory and deallocates all related resources.

</description>
<parameters>
<parameter name="dir">
<parameter_description> a #GDir* created by g_dir_open()
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_string_append_len">
<description>
Appends @len bytes of @val to @string. Because @len is 
provided, @val may contain embedded nuls and need not 
be nul-terminated.

Since this function does not stop at nul bytes, it is 
the caller&apos;s responsibility to ensure that @val has at 
least @len addressable bytes.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="val">
<parameter_description> bytes to append
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> number of bytes of @val to use
</parameter_description>
</parameter>
</parameters>
<return> @string
</return>
</function>

<function name="g_option_context_get_help">
<description>
Returns: A newly allocated string containing the help text

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GOptionContext
</parameter_description>
</parameter>
<parameter name="main_help">
<parameter_description> if %TRUE, only include the main group 
</parameter_description>
</parameter>
<parameter name="group">
<parameter_description> the #GOptionGroup to create help for, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> A newly allocated string containing the help text

Since: 2.14
</return>
</function>

<function name="g_queue_push_nth">
<description>
Inserts a new element into @queue at the given position

Since: 2.4

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> the data for the new element
</parameter_description>
</parameter>
<parameter name="n">
<parameter_description> the position to insert the new element. If @n is negative or
larger than the number of elements in the @queue, the element is
added to the end of the queue.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_queue_insert_after">
<description>
Inserts @data into @queue after @sibling

@sibling must be part of @queue

Since: 2.4

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="sibling">
<parameter_description> a #GList link that &amp;lt;emphasis&amp;gt;must&amp;lt;/emphasis&amp;gt; be part of @queue
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> the data to insert
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_unichar_isalnum">
<description>
Determines whether a character is alphanumeric.
Given some UTF-8 text, obtain a character value
with g_utf8_get_char().


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @c is an alphanumeric character
</return>
</function>

<function name="g_base64_encode_step">
<description>
Incrementally encode a sequence of binary data into it&apos;s Base-64 stringified
representation. By calling this function multiple times you can convert 
data in chunks to avoid having to have the full encoded data in memory.

When all of the data has been converted you must call 
g_base64_encode_close() to flush the saved state.

The output buffer must be large enough to fit all the data that will
be written to it. Due to the way base64 encodes you will need
at least: @len * 4 / 3 + 6 bytes. If you enable line-breaking you will
need at least: @len * 4 / 3 + @len * 4 / (3 * 72) + 7 bytes.

@break_lines is typically used when putting base64-encoded data in emails.
It breaks the lines at 72 columns instead of putting all of the text on 
the same line. This avoids problems with long lines in the email system.


</description>
<parameters>
<parameter name="in">
<parameter_description> the binary data to encode
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the length of @in
</parameter_description>
</parameter>
<parameter name="break_lines">
<parameter_description> whether to break long lines
</parameter_description>
</parameter>
<parameter name="out">
<parameter_description> pointer to destination buffer
</parameter_description>
</parameter>
<parameter name="state">
<parameter_description> Saved state between steps, initialize to 0
</parameter_description>
</parameter>
<parameter name="save">
<parameter_description> Saved state between steps, initialize to 0
</parameter_description>
</parameter>
</parameters>
<return> The number of bytes of output that was written

Since: 2.12
</return>
</function>

<function name="g_main_context_new">
<description>
Creates a new #GMainContext strcuture


</description>
<parameters>
</parameters>
<return> the new #GMainContext
</return>
</function>

<function name="g_vsnprintf">
<description>
A safer form of the standard vsprintf() function. The output is guaranteed
to not exceed @n characters (including the terminating nul character), so 
it is easy to ensure that a buffer overflow cannot occur.

See also g_strdup_vprintf().

In versions of GLib prior to 1.2.3, this function may return -1 if the 
output was truncated, and the truncated string may not be nul-terminated.
In versions prior to 1.3.12, this function returns the length of the output 
string.

The return value of g_vsnprintf() conforms to the vsnprintf() function 
as standardized in ISO C99. Note that this is different from traditional 
vsnprintf(), which returns the length of the output string.

The format string may contain positional parameters, as specified in 
the Single Unix Specification.


</description>
<parameters>
<parameter name="string">
<parameter_description> the buffer to hold the output.
</parameter_description>
</parameter>
<parameter name="n">
<parameter_description> the maximum number of characters to produce (including the 
terminating nul character).
</parameter_description>
</parameter>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice 
&amp;lt;link linkend=&quot;string-precision&quot;&amp;gt;string precision pitfalls&amp;lt;/link&amp;gt;.
</parameter_description>
</parameter>
<parameter name="args">
<parameter_description> the list of arguments to insert in the output.
</parameter_description>
</parameter>
</parameters>
<return> the number of characters which would be produced if the buffer 
was large enough.
</return>
</function>

<function name="g_time_val_from_iso8601">
<description>
Converts a string containing an ISO 8601 encoded date and time
to a #GTimeVal and puts it into @time_.


</description>
<parameters>
<parameter name="iso_date">
<parameter_description> a ISO 8601 encoded date string
</parameter_description>
</parameter>
<parameter name="time_">
<parameter_description> a #GTimeVal
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the conversion was successful.

Since: 2.12
</return>
</function>

<function name="g_ascii_strup">
<description>
Converts all lower case ASCII letters to upper case ASCII letters.


</description>
<parameters>
<parameter name="str">
<parameter_description> a string.
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> length of @str in bytes, or -1 if @str is nul-terminated.
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string, with all the lower case
characters in @str converted to upper case, with
semantics that exactly match g_ascii_toupper(). (Note
that this is unlike the old g_strup(), which modified
the string in place.)
</return>
</function>

<function name="g_async_queue_push">
<description>
Pushes the @data into the @queue. @data must not be %NULL.

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue.
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> @data to push into the @queue.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_strtod">
<description>
Converts a string to a #gdouble value.
It calls the standard strtod() function to handle the conversion, but
if the string is not completely converted it attempts the conversion
again with g_ascii_strtod(), and returns the best match.

This function should seldomly be used. The normal situation when reading
numbers not for human consumption is to use g_ascii_strtod(). Only when
you know that you must expect both locale formatted and C formatted numbers
should you use this. Make sure that you don&apos;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.


</description>
<parameters>
<parameter name="nptr">
<parameter_description>    the string to convert to a numeric value.
</parameter_description>
</parameter>
<parameter name="endptr">
<parameter_description>  if non-%NULL, it returns the character after
the last character used in the conversion.
</parameter_description>
</parameter>
</parameters>
<return> the #gdouble value.
</return>
</function>

<function name="g_get_system_data_dirs">
<description>
Return value: a %NULL-terminated array of strings owned by GLib that must 

</description>
<parameters>
</parameters>
<return> a %NULL-terminated array of strings owned by GLib that must 
not be modified or freed.
Since: 2.6
</return>
</function>

<function name="g_sequence_iter_compare">
<description>
Return value: A negative number if @a comes before @b, 0 if they are

</description>
<parameters>
<parameter name="a">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
<parameter name="b">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
</parameters>
<return> A negative number if @a comes before @b, 0 if they are
equal, and a positive number if @a comes after @b.

Since: 2.14
</return>
</function>

<function name="g_string_prepend">
<description>
Adds a string on to the start of a #GString, 
expanding it if necessary.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="val">
<parameter_description> the string to prepend on the start of @string
</parameter_description>
</parameter>
</parameters>
<return> @string
</return>
</function>

<function name="iconv_cache_expire_unused">
<description>
Expires as many unused cache buckets as it needs to in order to get
the total number of buckets &amp;lt; ICONV_CACHE_SIZE.

</description>
<parameters>
</parameters>
<return></return>
</function>

<function name="g_string_append_unichar">
<description>
Converts a Unicode character into UTF-8, and appends it
to the string.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="wc">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> @string
</return>
</function>

<function name="g_option_context_get_ignore_unknown_options">
<description>
Returns: %TRUE if unknown options are ignored.

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GOptionContext
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if unknown options are ignored.

Since: 2.6
</return>
</function>

<function name="g_regex_split_full">
<description>
Breaks the string on the pattern, and returns an array of the tokens.
If the pattern contains capturing parentheses, then the text for each
of the substrings will also be returned. If the pattern does not match
anywhere in the string, then the whole string is returned as the first
token.

As a special case, the result of splitting the empty string &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 a empty vector is
typically more useful than consistent handling of empty elements. If
you do need to represent empty elements, you&apos;ll need to check for the
empty string before calling this function.

A pattern that can match empty strings splits @string into separate
characters wherever it matches the empty string between characters.
For example splitting &quot;ab c&quot; using as a separator &quot;\s*&quot;, you will get
&quot;a&quot;, &quot;b&quot; and &quot;c&quot;.

Setting @start_position differs from just passing over a shortened 
string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern 
that begins with any kind of lookbehind assertion, such as &quot;\b&quot;.


</description>
<parameters>
<parameter name="regex">
<parameter_description> a #GRegex structure
</parameter_description>
</parameter>
<parameter name="string">
<parameter_description> the string to split with the pattern
</parameter_description>
</parameter>
<parameter name="string_len">
<parameter_description> the length of @string, or -1 if @string is nul-terminated
</parameter_description>
</parameter>
<parameter name="start_position">
<parameter_description> starting index of the string to match
</parameter_description>
</parameter>
<parameter name="match_options">
<parameter_description> match time option flags
</parameter_description>
</parameter>
<parameter name="max_tokens">
<parameter_description> the maximum number of tokens to split @string into. 
If this is less than 1, the string is split completely
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError
</parameter_description>
</parameter>
</parameters>
<return> a %NULL-terminated gchar ** array. Free it using g_strfreev()

Since: 2.14
</return>
</function>

<function name="g_utf8_offset_to_pointer">
<description>
Converts from an integer character offset to a pointer to a position
within the string.

Since 2.10, this function allows to pass a negative @offset to
step backwards. It is usually worth stepping backwards from the end
instead of forwards if @offset is in the last fourth of the string, 
since moving forward is about 3 times faster than moving backward.


</description>
<parameters>
<parameter name="str">
<parameter_description> a UTF-8 encoded string
</parameter_description>
</parameter>
<parameter name="offset">
<parameter_description> a character offset within @str
</parameter_description>
</parameter>
</parameters>
<return> the resulting pointer
</return>
</function>

<function name="g_io_channel_get_encoding">
<description>
Gets the encoding for the input/output of the channel. The internal
encoding is always UTF-8. The encoding %NULL makes the
channel safe for binary data.


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
</parameters>
<return> A string containing the encoding, this string is
owned by GLib and must not be freed.
</return>
</function>

<function name="g_key_file_get_locale_string">
<description>
Return value: a newly allocated string or %NULL if the specified 

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="locale">
<parameter_description> a locale or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string or %NULL if the specified 
key cannot be found.

Since: 2.6
</return>
</function>

<function name="g_sequence_insert_before">
<description>
Inserts a new item just before the item pointed to by @iter.


</description>
<parameters>
<parameter name="iter">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> the data for the new item
</parameter_description>
</parameter>
</parameters>
<return> an iterator pointing to the new item

Since: 2.14
</return>
</function>

<function name="g_bookmark_file_load_from_file">
<description>
Loads a desktop bookmark file into an empty #GBookmarkFile structure.
If the file could not be loaded then @error is set to either a #GFileError
or #GBookmarkFileError.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> an empty #GBookmarkFile struct
</parameter_description>
</parameter>
<parameter name="filename">
<parameter_description> the path of a filename to load, in the GLib file name encoding
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if a desktop bookmark file could be loaded

Since: 2.12
</return>
</function>

<function name="g_chmod">
<description>
A wrapper for the POSIX chmod() function. The chmod() function is
used to set the permissions of a file system object. Note that on
Windows the file protection mechanism is not at all POSIX-like, and
the underlying chmod() function in the C library just sets or
clears the READONLY attribute. It does not touch any ACL. Software
that needs to manage file permissions on Windows exactly should
use the Win32 API.

See the C library manual for more details about chmod().


</description>
<parameters>
<parameter name="filename">
<parameter_description> a pathname in the GLib file name encoding (UTF-8 on Windows)
</parameter_description>
</parameter>
<parameter name="mode">
<parameter_description> as in chmod()
</parameter_description>
</parameter>
</parameters>
<return> zero if the operation succeeded, -1 on error.

Since: 2.8
</return>
</function>

<function name="g_match_info_fetch_named">
<description>
Retrieves the text matching the capturing parentheses named @name.

If @name is a valid sub pattern name but it didn&apos;t match anything 
(e.g. sub pattern &quot;X&quot;, matching &quot;b&quot; against &quot;(?P&amp;lt;X&amp;gt;a)?b&quot;) 
then an empty string is returned.

The string is fetched from the string passed to the match function,
so you cannot call this function after freeing the string.


</description>
<parameters>
<parameter name="match_info">
<parameter_description> #GMatchInfo structure
</parameter_description>
</parameter>
<parameter name="name">
<parameter_description> name of the subexpression
</parameter_description>
</parameter>
</parameters>
<return> The matched substring, or %NULL if an error occurred.
You have to free the string yourself

Since: 2.14
</return>
</function>

<function name="g_unichar_isxdigit">
<description>
Determines if a character is a hexidecimal digit.


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the character is a hexadecimal digit
</return>
</function>

<function name="g_markup_parse_context_new">
<description>
Creates a new parse context. A parse context is used to parse
marked-up documents. You can feed any number of documents into
a context, as long as no errors occur; once an error occurs,
the parse context can&apos;t continue to parse text (you have to free it
and create a new parse context).


</description>
<parameters>
<parameter name="parser">
<parameter_description> a #GMarkupParser
</parameter_description>
</parameter>
<parameter name="flags">
<parameter_description> one or more #GMarkupParseFlags
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data to pass to #GMarkupParser functions
</parameter_description>
</parameter>
<parameter name="user_data_dnotify">
<parameter_description> user data destroy notifier called when the parse context is freed
</parameter_description>
</parameter>
</parameters>
<return> a new #GMarkupParseContext
</return>
</function>

<function name="g_key_file_set_boolean">
<description>
Associates a new boolean value with @key under @group_name.
If @key cannot be found then it is created. 

Since: 2.6

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="value">
<parameter_description> %TRUE or %FALSE
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_string_chunk_clear">
<description>
Frees all strings contained within the #GStringChunk.
After calling g_string_chunk_clear() it is not safe to
access any of the strings which were contained within it.

Since: 2.14

</description>
<parameters>
<parameter name="chunk">
<parameter_description> a #GStringChunk
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_bookmark_file_add_group">
<description>
Adds @group to the list of groups to which the bookmark for @uri
belongs to.

If no bookmark for @uri is found then it is created.

Since: 2.12

</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="group">
<parameter_description> the group name to be added
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_bookmark_file_remove_item">
<description>
Removes the bookmark for @uri from the bookmark file @bookmark.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the bookmark was removed successfully.

Since: 2.12
</return>
</function>

<function name="g_completion_complete_utf8">
<description>
Attempts to complete the string @prefix using the #GCompletion target items.
In contrast to g_completion_complete(), this function returns the largest common
prefix that is a valid UTF-8 string, omitting a possible common partial 
character.

You should use this function instead of g_completion_complete() if your 
items are UTF-8 strings.


</description>
<parameters>
<parameter name="cmp">
<parameter_description> the #GCompletion
</parameter_description>
</parameter>
<parameter name="prefix">
<parameter_description> the prefix string, typically used by the user, which is compared
with each of the items
</parameter_description>
</parameter>
<parameter name="new_prefix">
<parameter_description> if non-%NULL, returns the longest prefix which is common to all
items that matched @prefix, or %NULL if no items matched @prefix.
This string should be freed when no longer needed.
</parameter_description>
</parameter>
</parameters>
<return> the list of items whose strings begin with @prefix. This should
not be changed.

Since: 2.4
</return>
</function>

<function name="g_sequence_prepend">
<description>
Adds a new item to the front of @seq


</description>
<parameters>
<parameter name="seq">
<parameter_description> a #GSequence
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> the data for the new item
</parameter_description>
</parameter>
</parameters>
<return> an iterator pointing to the new item

Since: 2.14
</return>
</function>

<function name="g_utf8_to_utf16">
<description>
Convert a string from UTF-8 to UTF-16. A 0 character will be
added to the result after the converted text.


</description>
<parameters>
<parameter name="str">
<parameter_description> a UTF-8 encoded string
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the maximum length (number of characters) of @str to use. 
If @len &amp;lt; 0, then the string is nul-terminated.
</parameter_description>
</parameter>
<parameter name="items_read">
<parameter_description> location to store number of bytes read, or %NULL.
If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
returned in case @str contains a trailing partial
character. If an error occurs then the index of the
invalid input is stored here.
</parameter_description>
</parameter>
<parameter name="items_written">
<parameter_description> location to store number of &amp;lt;type&amp;gt;gunichar2&amp;lt;/type&amp;gt; written, 
or %NULL.
The value stored here does not include the trailing 0.
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store the error occuring, or %NULL to ignore
errors. Any of the errors in #GConvertError other than
%G_CONVERT_ERROR_NO_CONVERSION may occur.
</parameter_description>
</parameter>
</parameters>
<return> a pointer to a newly allocated UTF-16 string.
This value must be freed with g_free(). If an
error occurs, %NULL will be returned and
@error set.
</return>
</function>

<function name="g_queue_push_nth_link">
<description>
Inserts @link into @queue at the given position.

Since: 2.4

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="n">
<parameter_description> the position to insert the link. If this is negative or larger than
the number of elements in @queue, the link is added to the end of
@queue.
</parameter_description>
</parameter>
<parameter name="link_">
<parameter_description> the link to add to @queue
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_thread_foreach">
<description>
Call @thread_func on all existing #GThread structures. Note that
threads may decide to exit while @thread_func is running, so
without intimate knowledge about the lifetime of foreign threads,
@thread_func shouldn&apos;t access the GThread* pointer passed in as
first argument. However, @thread_func will not be called for threads
which are known to have exited already.

Due to thread lifetime checks, this function has an execution complexity
which is quadratic in the number of existing threads.

Since: 2.10

</description>
<parameters>
<parameter name="thread_func">
<parameter_description> function to call for all GThread structures
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description>   second argument to @thread_func
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_queue_peek_tail">
<description>
Returns: the data of the last element in the queue, or %NULL if the queue

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue.
</parameter_description>
</parameter>
</parameters>
<return> the data of the last element in the queue, or %NULL if the queue
is empty.
</return>
</function>

<function name="g_queue_push_head">
<description>
Adds a new element at the head of the queue.

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue.
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> the data for the new element.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_async_queue_unref">
<description>
Decreases the reference count of the asynchronous @queue by 1. If
the reference count went to 0, the @queue will be destroyed and the
memory allocated will be freed. So you are not allowed to use the
@queue afterwards, as it might have disappeared. You do not need to
hold the lock to call this function.

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_child_watch_add_full">
<description>
Sets a function to be called when the child indicated by @pid 
exits, at the priority @priority.

If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() 
you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to 
the spawn function for the child watching to work.

Note that on platforms where #GPid must be explicitly closed
(see g_spawn_close_pid()) @pid must not be closed while the
source is still active. Typically, you will want to call
g_spawn_close_pid() in the callback function for the source.

GLib supports only a single callback per process id.


</description>
<parameters>
<parameter name="priority">
<parameter_description> the priority of the idle source. Typically this will be in the
range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.
</parameter_description>
</parameter>
<parameter name="pid">
<parameter_description>      process id of a child process to watch
</parameter_description>
</parameter>
<parameter name="function">
<parameter_description> function to call
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description>     data to pass to @function
</parameter_description>
</parameter>
<parameter name="notify">
<parameter_description>   function to call when the idle is removed, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> the ID (greater than 0) of the event source.

Since: 2.4
</return>
</function>

<function name="g_key_file_get_double_list">
<description>
Return value: the values associated with the key as a list of

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> the number of doubles returned
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError
</parameter_description>
</parameter>
</parameters>
<return> the values associated with the key as a list of
doubles, or %NULL if the key was not found or could not be parsed.

Since: 2.12
</return>
</function>

<function name="g_sequence_iter_prev">
<description>
Return value: a #GSequenceIter pointing to the previous position before

</description>
<parameters>
<parameter name="iter">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
</parameters>
<return> a #GSequenceIter pointing to the previous position before
@iter.

Since: 2.14
</return>
</function>

<function name="g_option_context_free">
<description>
Frees context and all the groups which have been 
added to it.

Since: 2.6

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GOptionContext 
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_io_channel_seek">
<description>
Sets the current position in the #GIOChannel, similar to the standard library
function fseek(). 


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel. 
</parameter_description>
</parameter>
<parameter name="offset">
<parameter_description> an offset, in bytes, which is added to the position specified by @type
</parameter_description>
</parameter>
<parameter name="type">
<parameter_description> the position in the file, which can be %G_SEEK_CUR (the current
position), %G_SEEK_SET (the start of the file), or %G_SEEK_END (the end of the
file).
</parameter_description>
</parameter>
</parameters>
<return> %G_IO_ERROR_NONE if the operation was successful.

Deprecated:2.2: Use g_io_channel_seek_position() instead.
</return>
</function>

<function name="g_utf8_strdown">
<description>
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.


</description>
<parameters>
<parameter name="str">
<parameter_description> a UTF-8 encoded string
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> length of @str, in bytes, or -1 if @str is nul-terminated.
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string, with all characters
converted to lowercase.  
</return>
</function>

<function name="g_stat">
<description>
A wrapper for the POSIX stat() function. The stat() function
Returns: 0 if the information was successfully retrieved, -1 if an error 

</description>
<parameters>
<parameter name="filename">
<parameter_description> a pathname in the GLib file name encoding (UTF-8 on Windows)
</parameter_description>
</parameter>
<parameter name="buf">
<parameter_description> a pointer to a &amp;lt;structname&amp;gt;stat&amp;lt;/structname&amp;gt; struct, which
will be filled with the file information
</parameter_description>
</parameter>
</parameters>
<return> 0 if the information was successfully retrieved, -1 if an error 
occurred

Since: 2.6
</return>
</function>

<function name="g_match_info_get_match_count">
<description>
Retrieves the number of matched substrings (including substring 0, 
that is the whole matched text), so 1 is returned if the pattern 
has no substrings in it and 0 is returned if the match failed.

If the last match was obtained using the DFA algorithm, that is 
using g_regex_match_all() or g_regex_match_all_full(), the retrieved
count is not that of the number of capturing parentheses but that of
the number of matched substrings.


</description>
<parameters>
<parameter name="match_info">
<parameter_description> a #GMatchInfo structure
</parameter_description>
</parameter>
</parameters>
<return> Number of matched substrings, or -1 if an error occurred

Since: 2.14
</return>
</function>

<function name="g_mkstemp">
<description>
Opens a temporary file. See the mkstemp() documentation
on most UNIX-like systems. 

The parameter is a string that should follow the rules for
mkstemp() templates, i.e. contain the string &quot;XXXXXX&quot;. 
g_mkstemp() is slightly more flexible than mkstemp()
in that the sequence does not have to occur at the very end of the 
template. The X string will 
be modified to form the name of a file that didn&apos;t exist.
The string should be in the GLib file name encoding. Most importantly, 
on Windows it should be in UTF-8.


</description>
<parameters>
<parameter name="tmpl">
<parameter_description> template filename
</parameter_description>
</parameter>
</parameters>
<return> A file handle (as from open()) to the file
opened for reading and writing. The file is opened in binary mode
on platforms where there is a difference. The file handle should be
closed with close(). In case of errors, -1 is returned.  
</return>
</function>

<function name="g_filename_display_basename">
<description>
Return value: a newly allocated string containing

</description>
<parameters>
<parameter name="filename">
<parameter_description> an absolute pathname in the GLib file name encoding
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string containing
a rendition of the basename of the filename in valid UTF-8

Since: 2.6
</return>
</function>

<function name="g_bookmark_file_to_file">
<description>
This function outputs @bookmark into a file.  The write process is
guaranteed to be atomic by using g_file_set_contents() internally.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="filename">
<parameter_description> path of the output file
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the file was successfully written.

Since: 2.12
</return>
</function>

<function name="g_datalist_set_flags">
<description>
Turns on flag values for a data list. This function is used
to keep a small number of boolean flags in an object with
a data list without using any additional space. It is
not generally useful except in circumstances where space
is very tight. (It is used in the base #GObject type, for
example.)

Since: 2.8

</description>
<parameters>
<parameter name="datalist">
<parameter_description> pointer to the location that holds a list
</parameter_description>
</parameter>
<parameter name="flags">
<parameter_description> the flags to turn on. The values of the flags are
restricted by %G_DATALIST_FLAGS_MASK (currently
3; giving two possible boolean flags).
A value for @flags that doesn&apos;t fit within the mask is
an error.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_utf8_validate">
<description>
Validates UTF-8 encoded text. @str is the text to validate;
if @str is nul-terminated, then @max_len can be -1, otherwise
@max_len should be the number of bytes to validate.
If @end is non-%NULL, then the end of the valid range
will be stored there (i.e. the start of the first invalid 
character if some bytes were invalid, or the end of the text 
being validated otherwise).

Note that g_utf8_validate() returns %FALSE if @max_len is 
positive and NUL is met before @max_len bytes have been read.

Return value: %TRUE if the text was valid UTF-8

</description>
<parameters>
<parameter name="str">
<parameter_description> a pointer to character data
</parameter_description>
</parameter>
<parameter name="max_len">
<parameter_description> max bytes to validate, or -1 to go until NUL
</parameter_description>
</parameter>
<parameter name="end">
<parameter_description> return location for end of valid data
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the text was valid UTF-8
</return>
</function>

<function name="iconv_cache_bucket_new">
<description>
Creates a new cache bucket, inserts it into the cache and
increments the cache size.

This assumes ownership of @key.


</description>
<parameters>
<parameter name="key">
<parameter_description> cache key
</parameter_description>
</parameter>
<parameter name="cd">
<parameter_description> iconv descriptor
</parameter_description>
</parameter>
</parameters>
<return>a pointer to the newly allocated cache bucket.
</return>
</function>

<function name="g_timeout_source_new_seconds">
<description>
Creates a new timeout source.

The source will not initially be associated with any #GMainContext
and must be added to one with g_source_attach() before it will be
executed.

The scheduling granularity/accuracy of this timeout source will be
in seconds.


</description>
<parameters>
<parameter name="interval">
<parameter_description> the timeout interval in seconds
</parameter_description>
</parameter>
</parameters>
<return> the newly-created timeout source

Since: 2.14     
</return>
</function>

<function name="g_utf8_collate_key">
<description>
Converts a string into a collation key that can be compared
with other collation keys produced by the same function using 
strcmp(). 

The results of comparing the collation keys of two strings 
with strcmp() will always be the same as comparing the two 
original keys with g_utf8_collate().

Note that this function depends on the 
&amp;lt;link linkend=&quot;setlocale&quot;&amp;gt;current locale&amp;lt;/link&amp;gt;.


</description>
<parameters>
<parameter name="str">
<parameter_description> a UTF-8 encoded string.
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> length of @str, in bytes, or -1 if @str is nul-terminated.
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string. This string should
be freed with g_free() when you are done with it.
</return>
</function>

<function name="g_async_queue_timed_pop_unlocked">
<description>
Pops data from the @queue. If no data is received before @end_time,
%NULL is returned. This function must be called while holding the
@queue&apos;s lock.

To easily calculate @end_time a combination of g_get_current_time()
and g_time_val_add() can be used.


</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue.
</parameter_description>
</parameter>
<parameter name="end_time">
<parameter_description> a #GTimeVal, determining the final time.
</parameter_description>
</parameter>
</parameters>
<return> data from the queue or %NULL, when no data is
received before @end_time.
</return>
</function>

<function name="g_io_channel_set_buffer_size">
<description>
Sets the buffer size.

</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
<parameter name="size">
<parameter_description> the size of the buffer. 0 == pick a good size
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_key_file_get_integer">
<description>
Return value: the value associated with the key as an integer, or

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError
</parameter_description>
</parameter>
</parameters>
<return> the value associated with the key as an integer, or
0 if the key was not found or could not be parsed.

Since: 2.6
</return>
</function>

<function name="g_unichar_get_mirror_char">
<description>
In Unicode, some characters are &amp;lt;firstterm&amp;gt;mirrored&amp;lt;/firstterm&amp;gt;. 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.

If @ch has the Unicode mirrored property and there is another unicode
character that typically has a glyph that is the mirror image of @ch&apos;s
glyph and @mirrored_ch is set, it puts that character in the address
pointed to by @mirrored_ch.  Otherwise the original character is put.


</description>
<parameters>
<parameter name="ch">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
<parameter name="mirrored_ch">
<parameter_description> location to store the mirrored character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @ch has a mirrored character, %FALSE otherwise

Since: 2.4
</return>
</function>

<function name="g_build_filename">
<description>
Creates a filename from a series of elements using the correct
separator for filenames.

On Unix, this function behaves identically to &amp;lt;literal&amp;gt;g_build_path
(G_DIR_SEPARATOR_S, first_element, ....)&amp;lt;/literal&amp;gt;.

On Windows, it takes into account that either the backslash
(&amp;lt;literal&amp;gt;\&amp;lt;/literal&amp;gt; or slash (&amp;lt;literal&amp;gt;/&amp;lt;/literal&amp;gt;) can be used
as separator in filenames, but otherwise behaves as on Unix. When
file pathname separators need to be inserted, the one that last
previously occurred in the parameters (reading from left to right)
is used.

No attempt is made to force the resulting filename to be an absolute
path. If the first element is a relative path, the result will
be a relative path. 


</description>
<parameters>
<parameter name="first_element">
<parameter_description> the first element in the path
</parameter_description>
</parameter>
<parameter name="Varargs">
<parameter_description> remaining elements in path, terminated by %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly-allocated string that must be freed with g_free().
</return>
</function>

<function name="g_unichar_combining_class">
<description>
Determines the canonical combining class of a Unicode character.


</description>
<parameters>
<parameter name="uc">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> the combining class of the character

Since: 2.14
</return>
</function>

<function name="g_convert_with_iconv">
<description>
Converts a string from one character set to another. 

Note that you should use g_iconv() for streaming 
conversions&amp;lt;footnote id=&quot;streaming-state&quot;&amp;gt;
&amp;lt;para&amp;gt;
Despite the fact that @byes_read can return information about partial 
characters, the &amp;lt;literal&amp;gt;g_convert_...&amp;lt;/literal&amp;gt; functions
are not generally suitable for streaming. If the underlying converter 
being used maintains internal state, then this won&apos;t be preserved 
across successive calls to g_convert(), g_convert_with_iconv() or 
g_convert_with_fallback(). (An example of this is the GNU C converter 
for CP1255 which does not emit a base character until it knows that 
the next character is not a mark that could combine with the base 
character.)
&amp;lt;/para&amp;gt;
&amp;lt;/footnote&amp;gt;. 


</description>
<parameters>
<parameter name="str">
<parameter_description>           the string to convert
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description>           the length of the string, or -1 if the string is 
nul-terminated&amp;lt;footnoteref linkend=&quot;nul-unsafe&quot;/&amp;gt;. 
</parameter_description>
</parameter>
<parameter name="converter">
<parameter_description>     conversion descriptor from g_iconv_open()
</parameter_description>
</parameter>
<parameter name="bytes_read">
<parameter_description>    location to store the number of bytes in the
input string that were successfully converted, or %NULL.
Even if the conversion was successful, this may be 
less than @len if there were partial characters
at the end of the input. If the error
#G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
stored will the byte offset after the last valid
input sequence.
</parameter_description>
</parameter>
<parameter name="bytes_written">
<parameter_description> the number of bytes stored in the output buffer (not 
including the terminating nul).
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description>         location to store the error occuring, or %NULL to ignore
errors. Any of the errors in #GConvertError may occur.
</parameter_description>
</parameter>
</parameters>
<return> If the conversion was successful, a newly allocated
nul-terminated string, which must be freed with
g_free(). Otherwise %NULL and @error will be set.
</return>
</function>

<function name="g_strdupv">
<description>
Copies %NULL-terminated array of strings. The copy is a deep copy;
the new array should be freed by first freeing each string, then
the array itself. g_strfreev() does this for you. If called
on a %NULL value, g_strdupv() simply returns %NULL.


</description>
<parameters>
<parameter name="str_array">
<parameter_description> %NULL-terminated array of strings.
</parameter_description>
</parameter>
</parameters>
<return> a new %NULL-terminated array of strings.
</return>
</function>

<function name="g_string_append">
<description>
Adds a string onto the end of a #GString, expanding 
it if necessary.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="val">
<parameter_description> the string to append onto the end of @string
</parameter_description>
</parameter>
</parameters>
<return> @string
</return>
</function>

<function name="g_ascii_dtostr">
<description>
Converts a #gdouble to a string, using the &apos;.&apos; as
decimal point. 

This functions generates enough precision that converting
the string back using g_ascii_strtod() gives the same machine-number
(on machines with IEEE compatible 64bit doubles). It is
guaranteed that the size of the resulting string will never
be larger than @G_ASCII_DTOSTR_BUF_SIZE bytes.


</description>
<parameters>
<parameter name="buffer">
<parameter_description> A buffer to place the resulting string in
</parameter_description>
</parameter>
<parameter name="buf_len">
<parameter_description> The length of the buffer.
</parameter_description>
</parameter>
<parameter name="d">
<parameter_description> The #gdouble to convert
</parameter_description>
</parameter>
</parameters>
<return> The pointer to the buffer with the converted string.
</return>
</function>

<function name="g_bookmark_file_get_size">
<description>
Gets the number of bookmarks inside @bookmark.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
</parameters>
<return> the number of bookmarks

Since: 2.12
</return>
</function>

<function name="g_bookmark_file_get_uris">
<description>
Return value: a newly allocated %NULL-terminated array of strings.

</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> return location for the number of returned URIs, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated %NULL-terminated array of strings.
Use g_strfreev() to free it.

Since: 2.12
</return>
</function>

<function name="glib_check_version">
<description>
Checks that the GLib library in use is compatible with the
given version. Generally you would pass in the constants
#GLIB_MAJOR_VERSION, #GLIB_MINOR_VERSION, #GLIB_MICRO_VERSION
as the three arguments to this function; that produces
a check that the library in use is compatible with
the version of GLib the application or module was compiled
against.

Compatibility is defined by two things: first the version
of the running library is newer than the version
@required_major.required_minor.@required_micro. Second
the running library must be binary compatible with the
version @required_major.required_minor.@required_micro
(same major version.)


</description>
<parameters>
<parameter name="required_major">
<parameter_description> the required major version.
</parameter_description>
</parameter>
<parameter name="required_minor">
<parameter_description> the required minor version.
</parameter_description>
</parameter>
<parameter name="required_micro">
<parameter_description> the required micro version.
</parameter_description>
</parameter>
</parameters>
<return> %NULL if the GLib library is compatible with the
given version, or a string describing the version mismatch.
The returned string is owned by GLib and must not be modified
or freed.

Since: 2.6
</return>
</function>

<function name="g_io_channel_write">
<description>
Writes data to a #GIOChannel. 


</description>
<parameters>
<parameter name="channel">
<parameter_description>  a #GIOChannel.
</parameter_description>
</parameter>
<parameter name="buf">
<parameter_description> the buffer containing the data to write. 
</parameter_description>
</parameter>
<parameter name="count">
<parameter_description> the number of bytes to write.
</parameter_description>
</parameter>
<parameter name="bytes_written">
<parameter_description>  the number of bytes actually written.
</parameter_description>
</parameter>
</parameters>
<return>  %G_IO_ERROR_NONE if the operation was successful.

Deprecated:2.2: Use g_io_channel_write_chars() instead.
</return>
</function>

<function name="g_key_file_load_from_data_dirs">
<description>
This function looks for a key file named @file in the paths 
returned from g_get_user_data_dir() and g_get_system_data_dirs(), 
loads the file into @key_file and returns the file&apos;s full path in 
@full_path.  If the file could not be loaded then an %error is
set to either a #GFileError or #GKeyFileError.


</description>
<parameters>
<parameter name="key_file">
<parameter_description> an empty #GKeyFile struct
</parameter_description>
</parameter>
<parameter name="file">
<parameter_description> a relative path to a filename to open and parse
</parameter_description>
</parameter>
<parameter name="full_path">
<parameter_description> return location for a string containing the full path
of the file, or %NULL
</parameter_description>
</parameter>
<parameter name="flags">
<parameter_description> flags from #GKeyFileFlags 
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if a key file could be loaded, %FALSE othewise
Since: 2.6
</return>
</function>

<function name="g_sequence_insert_sorted_iter">
<description>
Like g_sequence_insert_sorted(), but uses
a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as
the compare function.


</description>
<parameters>
<parameter name="seq">
<parameter_description> a #GSequence
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> data for the new item
</parameter_description>
</parameter>
<parameter name="iter_cmp">
<parameter_description> the #GSequenceItercompare used to compare iterators in the
sequence. It is called with two iterators pointing into @seq. It should
return 0 if the iterators are equal, a negative value if the first
iterator comes before the second, and a positive value if the second
iterator comes before the first.
</parameter_description>
</parameter>
<parameter name="cmp_data">
<parameter_description> user data passed to @cmp_func
</parameter_description>
</parameter>
</parameters>
<return> a #GSequenceIter pointing to the new item

Since: 2.14
</return>
</function>

<function name="g_main_context_find_source_by_user_data">
<description>
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.


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> the user_data for the callback.
</parameter_description>
</parameter>
</parameters>
<return> the source, if one was found, otherwise %NULL
</return>
</function>

<function name="g_queue_push_tail_link">
<description>
Adds a new element at the tail of the queue.

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue.
</parameter_description>
</parameter>
<parameter name="link_">
<parameter_description> a single #GList element, &amp;lt;emphasis&amp;gt;not&amp;lt;/emphasis&amp;gt; a list with
more than one element.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_string_hash">
<description>
Creates a hash code for @str; for use with #GHashTable.


</description>
<parameters>
<parameter name="str">
<parameter_description> a string to hash
</parameter_description>
</parameter>
</parameters>
<return> hash code for @str
</return>
</function>

<function name="g_vsprintf">
<description>
An implementation of the standard vsprintf() function which supports 
positional parameters, as specified in the Single Unix Specification.


</description>
<parameters>
<parameter name="string">
<parameter_description> the buffer to hold the output.
</parameter_description>
</parameter>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice 
&amp;lt;link linkend=&quot;string-precision&quot;&amp;gt;string precision pitfalls&amp;lt;/link&amp;gt;.
</parameter_description>
</parameter>
<parameter name="args">
<parameter_description> the list of arguments to insert in the output.
</parameter_description>
</parameter>
</parameters>
<return> the number of characters printed.

Since: 2.2
</return>
</function>

<function name="g_async_queue_try_pop">
<description>
Tries to pop data from the @queue. If no data is available, %NULL is
returned.


</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue.
</parameter_description>
</parameter>
</parameters>
<return> data from the queue or %NULL, when no data is
available immediately.
</return>
</function>

<function name="g_unichar_iscntrl">
<description>
Determines whether a character is a control character.
Given some UTF-8 text, obtain a character value with
g_utf8_get_char().


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @c is a control character
</return>
</function>

<function name="g_string_sprintfa">
<description>
Appends a formatted string onto the end of a #GString.
This function is is similar to g_string_sprintf() except that
the text is appended to the #GString. 

Deprecated: This function has been renamed to g_string_append_printf()

</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="format">
<parameter_description> the string format. See the sprintf() documentation
</parameter_description>
</parameter>
<parameter name="Varargs">
<parameter_description> the parameters to insert into the format string
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_win32_locale_filename_from_utf8">
<description>
Converts a filename from UTF-8 to the system codepage.

On NT-based Windows, on NTFS file systems, file names are in
Unicode. It is quite possible that Unicode file names contain
characters not representable in the system codepage. (For instance,
Greek or Cyrillic characters on Western European or US Windows
installations, or various less common CJK characters on CJK Windows
installations.)

In such a case, and if the filename refers to an existing file, and
the file system stores alternate short (8.3) names for directory
entries, the short form of the filename is returned. Note that the
&quot;short&quot; name might in fact be longer than the Unicode name if the
Unicode name has very short pathname components containing
non-ASCII characters. If no system codepage name for the file is
possible, %NULL is returned.

The return value is dynamically allocated and should be freed with
g_free() when no longer needed.


</description>
<parameters>
<parameter name="utf8filename">
<parameter_description> a UTF-8 encoded filename.
</parameter_description>
</parameter>
</parameters>
<return> The converted filename, or %NULL on conversion
failure and lack of short names.

Since: 2.8
</return>
</function>

<function name="g_io_channel_read_line_string">
<description>
Reads a line from a #GIOChannel, using a #GString as a buffer.


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
<parameter name="buffer">
<parameter_description> a #GString into which the line will be written.
If @buffer already contains data, the old data will
be overwritten.
</parameter_description>
</parameter>
<parameter name="terminator_pos">
<parameter_description> location to store position of line terminator, or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> a location to store an error of type #GConvertError
or #GIOChannelError
</parameter_description>
</parameter>
</parameters>
<return> the status of the operation.
</return>
</function>

<function name="g_set_error">
<description>
Does nothing if @err is %NULL; if @err is non-%NULL, then *@err must
be %NULL. A new #GError is created and assigned to *@err.

</description>
<parameters>
<parameter name="err">
<parameter_description> a return location for a #GError, or %NULL
</parameter_description>
</parameter>
<parameter name="domain">
<parameter_description> error domain
</parameter_description>
</parameter>
<parameter name="code">
<parameter_description> error code 
</parameter_description>
</parameter>
<parameter name="format">
<parameter_description> printf()-style format
</parameter_description>
</parameter>
<parameter name="Varargs">
<parameter_description> args for @format 
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_queue_peek_head_link">
<description>
Return value: the first link in @queue, or %NULL if @queue is empty

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
</parameters>
<return> the first link in @queue, or %NULL if @queue is empty

Since: 2.4
</return>
</function>

<function name="g_child_watch_source_new">
<description>
Creates a new child_watch source.

The source will not initially be associated with any #GMainContext
and must be added to one with g_source_attach() before it will be
executed.

Note that child watch sources can only be used in conjunction with
&amp;lt;literal&amp;gt;g_spawn...&amp;lt;/literal&amp;gt; when the %G_SPAWN_DO_NOT_REAP_CHILD
flag is used.

Note that on platforms where #GPid must be explicitly closed
(see g_spawn_close_pid()) @pid must not be closed while the
source is still active. Typically, you will want to call
g_spawn_close_pid() in the callback function for the source.

Note further that using g_child_watch_source_new() is not 
compatible with calling &amp;lt;literal&amp;gt;waitpid(-1)&amp;lt;/literal&amp;gt; in 
the application. Calling waitpid() for individual pids will
still work fine. 


</description>
<parameters>
<parameter name="pid">
<parameter_description> process id of a child process to watch. On Windows, a HANDLE
for the process to watch (which actually doesn&apos;t have to be a child).
</parameter_description>
</parameter>
</parameters>
<return> the newly-created child watch source

Since: 2.4
</return>
</function>

<function name="g_option_group_new">
<description>
Creates a new #GOptionGroup.


</description>
<parameters>
<parameter name="name">
<parameter_description> the name for the option group, this is used to provide
help for the options in this group with &amp;lt;option&amp;gt;--help-&amp;lt;/option&amp;gt;@name
</parameter_description>
</parameter>
<parameter name="description">
<parameter_description> a description for this group to be shown in 
&amp;lt;option&amp;gt;--help&amp;lt;/option&amp;gt;. This string is translated using the translation
domain or translation function of the group
</parameter_description>
</parameter>
<parameter name="help_description">
<parameter_description> a description for the &amp;lt;option&amp;gt;--help-&amp;lt;/option&amp;gt;@name option.
This string is translated using the translation domain or translation function
of the group
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data that will be passed to the pre- and post-parse hooks,
the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL
</parameter_description>
</parameter>
<parameter name="destroy">
<parameter_description> a function that will be called to free @user_data, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly created option group. It should be added 
to a #GOptionContext or freed with g_option_group_free().

Since: 2.6
</return>
</function>

<function name="g_mapped_file_free">
<description>
Unmaps the buffer of @file and frees it. 

Since: 2.8

</description>
<parameters>
<parameter name="file">
<parameter_description> a #GMappedFile
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_thread_pool_get_max_unused_threads">
<description>
Return value: the maximal number of unused threads

</description>
<parameters>
</parameters>
<return> the maximal number of unused threads
</return>
</function>

<function name="g_io_channel_error_from_errno">
<description>
Converts an &amp;lt;literal&amp;gt;errno&amp;lt;/literal&amp;gt; error number to a #GIOChannelError.


</description>
<parameters>
<parameter name="en">
<parameter_description> an &amp;lt;literal&amp;gt;errno&amp;lt;/literal&amp;gt; error number, e.g. %EINVAL.
</parameter_description>
</parameter>
</parameters>
<return> a #GIOChannelError error number, e.g. %G_IO_CHANNEL_ERROR_INVAL.
</return>
</function>

<function name="g_int_equal">
<description>
Compares the two #gint values being pointed to and returns 
%TRUE if they are equal.
It can be passed to g_hash_table_new() as the @key_equal_func
parameter, when using pointers to integers as keys in a #GHashTable.


</description>
<parameters>
<parameter name="v1">
<parameter_description> a pointer to a #gint key.
</parameter_description>
</parameter>
<parameter name="v2">
<parameter_description> a pointer to a #gint key to compare with @v1.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the two keys match.
</return>
</function>

<function name="g_idle_source_new">
<description>
Creates a new idle source.

The source will not initially be associated with any #GMainContext
and must be added to one with g_source_attach() before it will be
executed. Note that the default priority for idle sources is
%G_PRIORITY_DEFAULT_IDLE, as compared to other sources which
have a default priority of %G_PRIORITY_DEFAULT.


</description>
<parameters>
</parameters>
<return> the newly-created idle source
</return>
</function>

<function name="g_string_chunk_insert_len">
<description>
Adds a copy of the first @len bytes of @string to the #GStringChunk. 
The copy is nul-terminated.

Since this function does not stop at nul bytes, it is the caller&apos;s
responsibility to ensure that @string has at least @len addressable 
bytes.

The characters in the returned string can be changed, if necessary, 
though you should not change anything after the end of the string.


</description>
<parameters>
<parameter name="chunk">
<parameter_description> a #GStringChunk
</parameter_description>
</parameter>
<parameter name="string">
<parameter_description> bytes to insert
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> number of bytes of @string to insert, or -1 to insert a 
nul-terminated string 
</parameter_description>
</parameter>
</parameters>
<return> a pointer to the copy of @string within the #GStringChunk

Since: 2.4
</return>
</function>

<function name="g_sequence_sort_changed_iter">
<description>
Like g_sequence_sort_changed(), but uses
a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as
the compare function.

Since: 2.14

</description>
<parameters>
<parameter name="iter">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
<parameter name="iter_cmp">
<parameter_description> the #GSequenceItercompare used to compare iterators in the
sequence. It is called with two iterators pointing into @seq. It should
return 0 if the iterators are equal, a negative value if the first
iterator comes before the second, and a positive value if the second
iterator comes before the first.
</parameter_description>
</parameter>
<parameter name="cmp_data">
<parameter_description> user data passed to @cmp_func
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_ascii_strtoull">
<description>
Converts a string to a #guint64 value.
This function behaves like the standard strtoull() function
does in the C locale. It does this without actually
changing the current locale, since that would not be
thread-safe.

This function is typically used when reading configuration
files or other non-user input that should be locale independent.
To handle input from the user you should normally use the
locale-sensitive system strtoull() function.

If the correct value would cause overflow, %G_MAXUINT64
is returned, and %ERANGE is stored in %errno.  If the base is
outside the valid range, zero is returned, and %EINVAL is stored
in %errno.  If the string conversion fails, zero is returned, and
@endptr returns @nptr (if @endptr is non-%NULL).


</description>
<parameters>
<parameter name="nptr">
<parameter_description>    the string to convert to a numeric value.
</parameter_description>
</parameter>
<parameter name="endptr">
<parameter_description>  if non-%NULL, it returns the character after
the last character used in the conversion.
</parameter_description>
</parameter>
<parameter name="base">
<parameter_description>    to be used for the conversion, 2..36 or 0
</parameter_description>
</parameter>
</parameters>
<return> the #guint64 value or zero on error.

Since: 2.2
</return>
</function>

<function name="g_unichar_isdefined">
<description>
Determines if a given character is assigned in the Unicode
standard.


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the character has an assigned value
</return>
</function>

<function name="g_markup_vprintf_escaped">
<description>
Formats the data in @args according to @format, escaping
all string and character arguments in the fashion
of g_markup_escape_text(). See g_markup_printf_escaped().


</description>
<parameters>
<parameter name="format">
<parameter_description> printf() style format string
</parameter_description>
</parameter>
<parameter name="args">
<parameter_description> variable argument list, similar to vprintf()
</parameter_description>
</parameter>
</parameters>
<return> newly allocated result from formatting
operation. Free with g_free().

Since: 2.4
</return>
</function>

<function name="g_bookmark_file_set_is_private">
<description>
Sets the private flag of the bookmark for @uri.

If a bookmark for @uri cannot be found then it is created.

Since: 2.12

</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="is_private">
<parameter_description> %TRUE if the bookmark should be marked as private
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_key_file_get_boolean">
<description>
Return value: the value associated with the key as a boolean, or

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError
</parameter_description>
</parameter>
</parameters>
<return> the value associated with the key as a boolean, or
%FALSE if the key was not found or could not be parsed.

Since: 2.6
</return>
</function>

<function name="g_async_queue_sort">
<description>
Sorts @queue using @func. 

This function will lock @queue before it sorts the queue and unlock
it when it is finished.

If you were sorting a list of priority numbers to make sure the
lowest priority would be at the top of the queue, you could use:
&amp;lt;informalexample&amp;gt;&amp;lt;programlisting&amp;gt; 
gint32 id1;
gint32 id2;

id1 = GPOINTER_TO_INT (element1);
id2 = GPOINTER_TO_INT (element2);

return (id1 &amp;gt; id2 ? +1 : id1 == id2 ? 0 : -1);
&amp;lt;/programlisting&amp;gt;&amp;lt;/informalexample&amp;gt;

Since: 2.10

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> the #GCompareDataFunc is used to sort @queue. This
function is passed two elements of the @queue. The function
should return 0 if they are equal, a negative value if the
first element should be higher in the @queue or a positive
value if the first element should be lower in the @queue than
the second element. 
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data passed to @func
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_path_is_absolute">
<description>
Returns: %TRUE if @file_name is an absolute path. 

</description>
<parameters>
<parameter name="file_name">
<parameter_description> a file name.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @file_name is an absolute path. 
</return>
</function>

<function name="g_string_prepend_len">
<description>
Prepends @len bytes of @val to @string. 
Because @len is provided, @val may contain 
embedded nuls and need not be nul-terminated.

Since this function does not stop at nul bytes, 
it is the caller&apos;s responsibility to ensure that 
@val has at least @len addressable bytes.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="val">
<parameter_description> bytes to prepend
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> number of bytes in @val to prepend
</parameter_description>
</parameter>
</parameters>
<return> @string
</return>
</function>

<function name="g_string_overwrite_len">
<description>
Overwrites part of a string, lengthening it if necessary. 
This function will work with embedded nuls.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="pos">
<parameter_description> the position at which to start overwriting
</parameter_description>
</parameter>
<parameter name="val">
<parameter_description> the string that will overwrite the @string starting at @pos
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the number of bytes to write from @val
</parameter_description>
</parameter>
</parameters>
<return> @string

Since: 2.14
</return>
</function>

<function name="g_main_loop_is_running">
<description>
Checks to see if the main loop is currently being run via g_main_loop_run().


</description>
<parameters>
<parameter name="loop">
<parameter_description> a #GMainLoop.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the mainloop is currently being run.
</return>
</function>

<function name="g_bookmark_file_get_title">
<description>
Return value: a newly allocated string or %NULL if the specified

</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string or %NULL if the specified
URI cannot be found.

Since: 2.12
</return>
</function>

<function name="g_string_new">
<description>
Creates a new #GString, initialized with the given string.


</description>
<parameters>
<parameter name="init">
<parameter_description> the initial text to copy into the string
</parameter_description>
</parameter>
</parameters>
<return> the new #GString
</return>
</function>

<function name="g_filename_to_uri">
<description>
Converts an absolute filename to an escaped ASCII-encoded URI, with the path
component following Section 3.3. of RFC 2396.


</description>
<parameters>
<parameter name="filename">
<parameter_description> 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
</parameter_description>
</parameter>
<parameter name="hostname">
<parameter_description> A UTF-8 encoded hostname, or %NULL for none.
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store the error occuring, or %NULL to ignore
errors. Any of the errors in #GConvertError may occur.
</parameter_description>
</parameter>
</parameters>
<return> a newly-allocated string holding the resulting
URI, or %NULL on an error.
</return>
</function>

<function name="g_string_down">
<description>
Converts a #GString to lowercase.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
</parameters>
<return> the #GString.

Deprecated:2.2: This function uses the locale-specific 
tolower() function, which is almost never the right thing. 
Use g_string_ascii_down() or g_utf8_strdown() instead.
</return>
</function>

<function name="g_strup">
<description>
Converts a string to upper case. 


</description>
<parameters>
<parameter name="string">
<parameter_description> the string to convert.
</parameter_description>
</parameter>
</parameters>
<return> the string

Deprecated:2.2: This function is totally broken for the reasons discussed 
in the g_strncasecmp() docs - use g_ascii_strup() or g_utf8_strup() instead.
</return>
</function>

<function name="g_date_get_iso8601_week_of_year">
<description>
Returns: ISO 8601 week number of the year.

</description>
<parameters>
<parameter name="date">
<parameter_description> a valid #GDate
</parameter_description>
</parameter>
</parameters>
<return> ISO 8601 week number of the year.

Since: 2.6
</return>
</function>

<function name="g_win32_get_package_installation_directory">
<description>
Try to determine the installation directory for a software package.

@package should be a short identifier for the package. Typically it
is the same identifier as used for
&amp;lt;literal&amp;gt;GETTEXT_PACKAGE&amp;lt;/literal&amp;gt; in software configured using GNU
autotools. The function first looks in the Windows Registry for the
value &amp;lt;literal&amp;gt;&amp;num;InstallationDirectory&amp;lt;/literal&amp;gt; in the key
&amp;lt;literal&amp;gt;&amp;num;HKLM\Software\@package&amp;lt;/literal&amp;gt;, and if that value
exists and is a string, returns that.

It is strongly recommended that packagers of GLib-using libraries
for Windows do not store installation paths in the Registry to be
used by this function as that interfers with having several
parallel installations of the library. Parallel installations of
different versions of some GLib-using library, or GLib itself,
might well be desirable for various reasons.

For the same reason it is recommeded to always pass %NULL as
@package to this function, to avoid the temptation to use the
Registry.

If @package is %NULL, or the above value isn&apos;t found in the
Registry, but @dll_name is non-%NULL, it should name a DLL loaded
into the current process. Typically that would be the name of the
DLL calling this function, looking for its installation
directory. The function then asks Windows what directory that DLL
was loaded from. If that directory&apos;s last component is &quot;bin&quot; or
&quot;lib&quot;, the parent directory is returned, otherwise the directory
itself. If that DLL isn&apos;t loaded, the function proceeds as if
@dll_name was %NULL.

If both @package and @dll_name are %NULL, the directory from where
the main executable of the process was loaded is used instead in
the same way as above.


</description>
<parameters>
<parameter name="package">
<parameter_description> An identifier for a software package, or %NULL, in UTF-8
</parameter_description>
</parameter>
<parameter name="dll_name">
<parameter_description> The name of a DLL that a package provides, or %NULL, in UTF-8
</parameter_description>
</parameter>
</parameters>
<return> a string containing the installation directory for
@package. The string is in the GLib file name encoding, i.e. UTF-8
on Windows. The return value should be freed with g_free() when not
needed any longer.
</return>
</function>

<function name="g_thread_pool_stop_unused_threads">
<description>
Stops all currently unused threads. This does not change the
maximal number of unused threads. This function can be used to
regularly stop all unused threads e.g. from g_timeout_add().

</description>
<parameters>
</parameters>
<return></return>
</function>

<function name="g_hash_table_size">
<description>
Return value: the number of key/value pairs in the #GHashTable.

</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a #GHashTable.
</parameter_description>
</parameter>
</parameters>
<return> the number of key/value pairs in the #GHashTable.
</return>
</function>

<function name="g_key_file_remove_key">
<description>
Removes @key in @group_name from the key file. 

Since: 2.6

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key name to remove
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError or %NULL
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_source_get_priority">
<description>
Gets the priority of a source.


</description>
<parameters>
<parameter name="source">
<parameter_description> a #GSource
</parameter_description>
</parameter>
</parameters>
<return> the priority of the source
</return>
</function>

<function name="g_regex_replace_literal">
<description>
Replaces all occurances of the pattern in @regex with the
replacement text. @replacement is replaced literally, to
include backreferences use g_regex_replace().

Setting @start_position differs from just passing over a 
shortened string and setting #G_REGEX_MATCH_NOTBOL in the 
case of a pattern that begins with any kind of lookbehind 
assertion, such as &quot;\b&quot;.


</description>
<parameters>
<parameter name="regex">
<parameter_description> a #GRegex structure
</parameter_description>
</parameter>
<parameter name="string">
<parameter_description> the string to perform matches against
</parameter_description>
</parameter>
<parameter name="string_len">
<parameter_description> the length of @string, or -1 if @string is nul-terminated
</parameter_description>
</parameter>
<parameter name="start_position">
<parameter_description> starting index of the string to match
</parameter_description>
</parameter>
<parameter name="replacement">
<parameter_description> text to replace each match with
</parameter_description>
</parameter>
<parameter name="match_options">
<parameter_description> options for the match
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store the error occuring, or %NULL to ignore errors
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string containing the replacements

Since: 2.14
</return>
</function>

<function name="g_queue_find">
<description>
Finds the first link in @queue which contains @data.


</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> data to find
</parameter_description>
</parameter>
</parameters>
<return> The first link in @queue which contains @data.

Since: 2.4
</return>
</function>

<function name="g_bookmark_file_new">
<description>
Creates a new empty #GBookmarkFile object.

Use g_bookmark_file_load_from_file(), g_bookmark_file_load_from_data()
or g_bookmark_file_load_from_data_dirs() to read an existing bookmark
file.


</description>
<parameters>
</parameters>
<return> an empty #GBookmarkFile

Since: 2.12
</return>
</function>

<function name="g_bookmark_file_has_application">
<description>
Checks whether the bookmark for @uri inside @bookmark has been
registered by application @name.

In the event the URI cannot be found, %FALSE is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="name">
<parameter_description> the name of the application
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the application @name was found

Since: 2.12
</return>
</function>

<function name="g_queue_pop_nth_link">
<description>
Removes and returns the link at the given position.


</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="n">
<parameter_description> the link&apos;s position
</parameter_description>
</parameter>
</parameters>
<return> The @n&apos;th link, or %NULL if @n is off the end of @queue.

Since: 2.4
</return>
</function>

<function name="g_io_channel_set_close_on_unref">
<description>
Setting this flag to %TRUE for a channel you have already closed
can cause problems.

</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
<parameter name="do_close">
<parameter_description> Whether to close the channel on the final unref of
the GIOChannel data structure. The default value of
this is %TRUE for channels created by g_io_channel_new_file (),
and %FALSE for all other channels.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_async_queue_pop">
<description>
Pops data from the @queue. This function blocks until data become
available.


</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue.
</parameter_description>
</parameter>
</parameters>
<return> data from the queue.
</return>
</function>

<function name="g_async_queue_unref_and_unlock">
<description>
Decreases the reference count of the asynchronous @queue by 1 and
releases the lock. This function must be called while holding the
@queue&apos;s lock. If the reference count went to 0, the @queue will be
destroyed and the memory allocated will be freed.

@Deprecated: Since 2.8, reference counting is done atomically
so g_async_queue_unref() can be used regardless of the @queue&apos;s
lock.

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_option_context_get_description">
<description>
Returns: the description

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GOptionContext
</parameter_description>
</parameter>
</parameters>
<return> the description

Since: 2.12
</return>
</function>

<function name="g_stpcpy">
<description>
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.


</description>
<parameters>
<parameter name="dest">
<parameter_description> destination buffer.
</parameter_description>
</parameter>
<parameter name="src">
<parameter_description> source string.
</parameter_description>
</parameter>
</parameters>
<return> a pointer to trailing nul byte.
</return>
</function>

<function name="g_string_insert_c">
<description>
Inserts a byte into a #GString, expanding it if necessary.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="pos">
<parameter_description> the position to insert the byte
</parameter_description>
</parameter>
<parameter name="c">
<parameter_description> the byte to insert
</parameter_description>
</parameter>
</parameters>
<return> @string
</return>
</function>

<function name="g_bookmark_file_get_added">
<description>
Gets the time the bookmark for @uri was added to @bookmark

In the event the URI cannot be found, -1 is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a timestamp

Since: 2.12
</return>
</function>

<function name="g_io_channel_shutdown">
<description>
Close an IO channel. Any pending data to be written will be
flushed if @flush is %TRUE. The channel will not be freed until the
last reference is dropped using g_io_channel_unref().


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
<parameter name="flush">
<parameter_description> if %TRUE, flush pending
</parameter_description>
</parameter>
<parameter name="err">
<parameter_description> location to store a #GIOChannelError
</parameter_description>
</parameter>
</parameters>
<return> the status of the operation.
</return>
</function>

<function name="g_ucs4_to_utf16">
<description>
Convert a string from UCS-4 to UTF-16. A 0 character will be
added to the result after the converted text.


</description>
<parameters>
<parameter name="str">
<parameter_description> a UCS-4 encoded string
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the maximum length (number of characters) of @str to use. 
If @len &amp;lt; 0, then the string is terminated with a 0 character.
</parameter_description>
</parameter>
<parameter name="items_read">
<parameter_description> location to store number of bytes read, or %NULL.
If an error occurs then the index of the invalid input
is stored here.
</parameter_description>
</parameter>
<parameter name="items_written">
<parameter_description> location to store number of &amp;lt;type&amp;gt;gunichar2&amp;lt;/type&amp;gt; 
written, or %NULL. The value stored here does not 
include the trailing 0.
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store the error occuring, or %NULL to ignore
errors. Any of the errors in #GConvertError other than
%G_CONVERT_ERROR_NO_CONVERSION may occur.
</parameter_description>
</parameter>
</parameters>
<return> a pointer to a newly allocated UTF-16 string.
This value must be freed with g_free(). If an
error occurs, %NULL will be returned and
@error set.
</return>
</function>

<function name="g_thread_pool_unprocessed">
<description>
Return value: the number of unprocessed tasks

</description>
<parameters>
<parameter name="pool">
<parameter_description> a #GThreadPool
</parameter_description>
</parameter>
</parameters>
<return> the number of unprocessed tasks
</return>
</function>

<function name="g_thread_pool_set_max_unused_threads">
<description>
Sets the maximal number of unused threads to @max_threads. If
@max_threads is -1, no limit is imposed on the number of unused
threads.

</description>
<parameters>
<parameter name="max_threads">
<parameter_description> maximal number of unused threads
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_bookmark_file_set_description">
<description>
Sets @description as the description of the bookmark for @uri.

If @uri is %NULL, the description of @bookmark is set.

If a bookmark for @uri cannot be found then it is created.

Since: 2.12

</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI or %NULL
</parameter_description>
</parameter>
<parameter name="description">
<parameter_description> a string
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_utf8_get_char_validated">
<description>
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.


</description>
<parameters>
<parameter name="p">
<parameter_description> a pointer to Unicode character encoded as UTF-8
</parameter_description>
</parameter>
<parameter name="max_len">
<parameter_description> the maximum number of bytes to read, or -1, for no maximum or
if @p is nul-terminated
</parameter_description>
</parameter>
</parameters>
<return> the resulting character. If @p points to a partial
sequence at the end of a string that could begin a valid 
character (or if @max_len is zero), returns (gunichar)-2; 
otherwise, if @p does not point to a valid UTF-8 encoded 
Unicode character, returns (gunichar)-1.
</return>
</function>

<function name="g_utf8_to_ucs4_fast">
<description>
Convert a string from UTF-8 to a 32-bit fixed width
representation as UCS-4, assuming valid UTF-8 input.
This function is roughly twice as fast as g_utf8_to_ucs4()
but does no error checking on the input.


</description>
<parameters>
<parameter name="str">
<parameter_description> a UTF-8 encoded string
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the maximum length of @str to use. If @len &amp;lt; 0, then
the string is nul-terminated.
</parameter_description>
</parameter>
<parameter name="items_written">
<parameter_description> location to store the number of characters in the
result, or %NULL.
</parameter_description>
</parameter>
</parameters>
<return> a pointer to a newly allocated UCS-4 string.
This value must be freed with g_free().
</return>
</function>

<function name="g_hash_table_replace">
<description>
Inserts a new key and value into a #GHashTable similar to 
g_hash_table_insert(). The difference is that if the key already exists 
in the #GHashTable, it gets replaced by the new key. If you supplied a 
@value_destroy_func when creating the #GHashTable, the old value is freed 
using that function. If you supplied a @key_destroy_func when creating the 
#GHashTable, the old key is freed using that function. 

</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a #GHashTable.
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key to insert.
</parameter_description>
</parameter>
<parameter name="value">
<parameter_description> the value to associate with the key.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_source_remove">
<description>
Removes the source with the given id from the default main context. 
The id of
a #GSource is given by g_source_get_id(), or will be returned by the
functions g_source_attach(), g_idle_add(), g_idle_add_full(),
g_timeout_add(), g_timeout_add_full(), g_child_watch_add(),
g_child_watch_add_full(), g_io_add_watch(), and g_io_add_watch_full().

See also g_source_destroy().


</description>
<parameters>
<parameter name="tag">
<parameter_description> the ID of the source to remove.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the source was found and removed.
</return>
</function>

<function name="g_timeout_add_seconds_full">
<description>
Sets a function to be called at regular intervals, with @priority.
The function is called repeatedly until it returns %FALSE, at which
point the timeout is automatically destroyed and the function will
not be called again.

Unlike g_timeout_add(), this function operates at whole second granularity.
The initial starting point of the timer is determined by the implementation
and the implementation is expected to group multiple timers together so that
they fire all at the same time.
To allow this grouping, the @interval to the first timer is rounded
and can deviate up to one second from the specified interval.
Subsequent timer iterations will generally run at the specified interval.

Note that timeout functions may be delayed, due to the processing of other
event sources. Thus they should not be relied on for precise timing.
After each call to the timeout function, the time of the next
timeout is recalculated based on the current time and the given @interval

If you want timing more precise than whole seconds, use g_timeout_add()
instead.

The grouping of timers to fire at the same time results in a more power
and CPU efficient behavior so if your timer is in multiples of seconds
and you don&apos;t require the first timer exactly one second from now, the
use of g_timeout_add_seconds() is preferred over g_timeout_add().


</description>
<parameters>
<parameter name="priority">
<parameter_description> the priority of the timeout source. Typically this will be in
the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
</parameter_description>
</parameter>
<parameter name="interval">
<parameter_description> the time between calls to the function, in seconds
</parameter_description>
</parameter>
<parameter name="function">
<parameter_description> function to call
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description>     data to pass to @function
</parameter_description>
</parameter>
<parameter name="notify">
<parameter_description>   function to call when the timeout is removed, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> the ID (greater than 0) of the event source.

Since: 2.14
</return>
</function>

<function name="g_queue_insert_sorted">
<description>
Inserts @data into @queue using @func to determine the new position.

Since: 2.4

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> the data to insert
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> the #GCompareDataFunc used to compare elements in the queue. It is
called with two elements of the @queue and @user_data. It should
return 0 if the elements are equal, a negative value if the first
element comes before the second, and a positive value if the second
element comes before the first.
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data passed to @func.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_string_insert">
<description>
Inserts a copy of a string into a #GString, 
expanding it if necessary.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="pos">
<parameter_description> the position to insert the copy of the string
</parameter_description>
</parameter>
<parameter name="val">
<parameter_description> the string to insert
</parameter_description>
</parameter>
</parameters>
<return> @string
</return>
</function>

<function name="g_get_user_config_dir">
<description>
Return value: a string owned by GLib that must not be modified 

</description>
<parameters>
</parameters>
<return> a string owned by GLib that must not be modified 
or freed.
Since: 2.6
</return>
</function>

<function name="g_async_queue_pop_unlocked">
<description>
Pops data from the @queue. This function blocks until data become
available. This function must be called while holding the @queue&apos;s
lock.


</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue.
</parameter_description>
</parameter>
</parameters>
<return> data from the queue.
</return>
</function>

<function name="g_error_new_literal">
<description>
Creates a new #GError; unlike g_error_new(), @message is not
a printf()-style format string. Use this 
function if @message contains text you don&apos;t have control over, 
that could include printf() escape sequences.


</description>
<parameters>
<parameter name="domain">
<parameter_description> error domain
</parameter_description>
</parameter>
<parameter name="code">
<parameter_description> error code
</parameter_description>
</parameter>
<parameter name="message">
<parameter_description> error message
</parameter_description>
</parameter>
</parameters>
<return> a new #GError
</return>
</function>

<function name="g_option_group_free">
<description>
Frees a #GOptionGroup. Note that you must &amp;lt;emphasis&amp;gt;not&amp;lt;/emphasis&amp;gt;
free groups which have been added to a #GOptionContext.

Since: 2.6

</description>
<parameters>
<parameter name="group">
<parameter_description> a #GOptionGroup
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_strv_length">
<description>
Return value: length of @str_array.

</description>
<parameters>
<parameter name="str_array">
<parameter_description> a %NULL-terminated array of strings.
</parameter_description>
</parameter>
</parameters>
<return> length of @str_array.

Since: 2.6
</return>
</function>

<function name="g_queue_link_index">
<description>
Return value: The position of @link_, or -1 if the link is

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #Gqueue
</parameter_description>
</parameter>
<parameter name="link_">
<parameter_description> A #GList link
</parameter_description>
</parameter>
</parameters>
<return> The position of @link_, or -1 if the link is
not part of @queue

Since: 2.4
</return>
</function>

<function name="g_spawn_close_pid">
<description>
On some platforms, notably WIN32, the #GPid type represents a resource
which must be closed to prevent resource leaking. g_spawn_close_pid()
is provided for this purpose. It should be used on all platforms, even
though it doesn&apos;t do anything under UNIX.

</description>
<parameters>
<parameter name="pid">
<parameter_description> The process identifier to close
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_iconv_open">
<description>
Same as the standard UNIX routine iconv_open(), but
may be implemented via libiconv on UNIX flavors that lack
a native implementation.

GLib provides g_convert() and g_locale_to_utf8() which are likely
more convenient than the raw iconv wrappers.


</description>
<parameters>
<parameter name="to_codeset">
<parameter_description> destination codeset
</parameter_description>
</parameter>
<parameter name="from_codeset">
<parameter_description> source codeset
</parameter_description>
</parameter>
</parameters>
<return> a &quot;conversion descriptor&quot;, or (GIConv)-1 if
opening the converter failed.
</return>
</function>

<function name="g_rand_free">
<description>
Frees the memory allocated for the #GRand.

</description>
<parameters>
<parameter name="rand_">
<parameter_description> a #GRand.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_option_group_add_entries">
<description>
Adds the options specified in @entries to @group.

Since: 2.6

</description>
<parameters>
<parameter name="group">
<parameter_description> a #GOptionGroup
</parameter_description>
</parameter>
<parameter name="entries">
<parameter_description> a %NULL-terminated array of #GOptionEntry&amp;lt;!-- --&amp;gt;s
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_bookmark_file_set_groups">
<description>
Sets a list of group names for the item with URI @uri.  Each previously
set group name list is removed.

If @uri cannot be found then an item for it is created.

Since: 2.12

</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> an item&apos;s URI
</parameter_description>
</parameter>
<parameter name="groups">
<parameter_description> an array of group names, or %NULL to remove all groups
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> number of group name values in @groups
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_io_channel_get_close_on_unref">
<description>
Return value: Whether the channel will be closed on the final unref of

</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel.
</parameter_description>
</parameter>
</parameters>
<return> Whether the channel will be closed on the final unref of
the GIOChannel data structure.
</return>
</function>

<function name="g_key_file_get_groups">
<description>
Return value: a newly-allocated %NULL-terminated array of strings. 

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> return location for the number of returned groups, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly-allocated %NULL-terminated array of strings. 
Use g_strfreev() to free it.
Since: 2.6
</return>
</function>

<function name="g_source_ref">
<description>
Increases the reference count on a source by one.


</description>
<parameters>
<parameter name="source">
<parameter_description> a #GSource
</parameter_description>
</parameter>
</parameters>
<return> @source
</return>
</function>

<function name="g_filename_to_utf8">
<description>
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 &amp;lt;link linkend=&quot;setlocale&quot;&amp;gt;current locale&amp;lt;/link&amp;gt;.


</description>
<parameters>
<parameter name="opsysstring">
<parameter_description>   a string in the encoding for filenames
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description>           the length of the string, or -1 if the string is
nul-terminated&amp;lt;footnoteref linkend=&quot;nul-unsafe&quot;/&amp;gt;. 
</parameter_description>
</parameter>
<parameter name="bytes_read">
<parameter_description>    location to store the number of bytes in the
input string that were successfully converted, or %NULL.
Even if the conversion was successful, this may be 
less than @len if there were partial characters
at the end of the input. If the error
#G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
stored will the byte offset after the last valid
input sequence.
</parameter_description>
</parameter>
<parameter name="bytes_written">
<parameter_description> the number of bytes stored in the output buffer (not 
including the terminating nul).
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description>         location to store the error occuring, or %NULL to ignore
errors. Any of the errors in #GConvertError may occur.
</parameter_description>
</parameter>
</parameters>
<return> The converted string, or %NULL on an error.
</return>
</function>

<function name="g_strrstr">
<description>
Searches the string @haystack for the last occurrence
of the string @needle.


</description>
<parameters>
<parameter name="haystack">
<parameter_description> a nul-terminated string.
</parameter_description>
</parameter>
<parameter name="needle">
<parameter_description> the nul-terminated string to search for.
</parameter_description>
</parameter>
</parameters>
<return> a pointer to the found occurrence, or
%NULL if not found.
</return>
</function>

<function name="g_match_info_get_regex">
<description>
Returns: #GRegex object used in @match_info

</description>
<parameters>
<parameter name="match_info">
<parameter_description> a #GMatchInfo
</parameter_description>
</parameter>
</parameters>
<return> #GRegex object used in @match_info

Since: 2.14
</return>
</function>

<function name="g_sequence_foreach_range">
<description>
Calls @func for each item in the range (@begin, @end) passing
@user_data to the function.

Since: 2.14

</description>
<parameters>
<parameter name="begin">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
<parameter name="end">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> a #GFunc
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data passed to @func
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_main_context_wait">
<description>
Tries to become the owner of the specified context,
as with g_main_context_acquire(). But if another thread
is the owner, atomically drop @mutex and wait on @cond until 
that owner releases ownership or until @cond is signaled, then
try again (once) to become the owner.


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext
</parameter_description>
</parameter>
<parameter name="cond">
<parameter_description> a condition variable
</parameter_description>
</parameter>
<parameter name="mutex">
<parameter_description> a mutex, currently held
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the operation succeeded, and
this thread is now the owner of @context.
</return>
</function>

<function name="g_date_set_time_t">
<description>
Sets the value of a date from a &amp;lt;type&amp;gt;time_t&amp;lt;/type&amp;gt; value. 

To set the value of a date to the current day, you could write:
&amp;lt;informalexample&amp;gt;&amp;lt;programlisting&amp;gt; 
g_date_set_time_t (date, time (NULL)); 
&amp;lt;/programlisting&amp;gt;&amp;lt;/informalexample&amp;gt;

Since: 2.10

</description>
<parameters>
<parameter name="date">
<parameter_description> a #GDate 
</parameter_description>
</parameter>
<parameter name="timet">
<parameter_description> &amp;lt;type&amp;gt;time_t&amp;lt;/type&amp;gt; value to set
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_key_file_set_comment">
<description>
Places a comment above @key from @group_name.
@group_name. If @key is %NULL then @comment will
be written above @group_name.  If both @key
and @group_name are NULL, then @comment will
be written above the first group in the file.

Since: 2.6

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name, or %NULL
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="comment">
<parameter_description> a comment
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_io_channel_error_quark">
<description>

</description>
<parameters>
</parameters>
<return> The quark used as %G_IO_CHANNEL_ERROR
</return>
</function>

<function name="g_option_context_add_group">
<description>
Adds a #GOptionGroup to the @context, so that parsing with @context
will recognize the options in the group. Note that the group will
be freed together with the context when g_option_context_free() is
called, so you must not free the group yourself after adding it
to a context.

Since: 2.6

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GOptionContext
</parameter_description>
</parameter>
<parameter name="group">
<parameter_description> the group to add
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_hash_table_foreach_remove">
<description>
Calls the given function for each key/value pair in the #GHashTable.
If the function returns %TRUE, then the key/value pair is removed from the
#GHashTable. If you supplied key or value destroy functions when creating
the #GHashTable, they are used to free the memory allocated for the removed
keys and values.


</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a #GHashTable.
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> the function to call for each key/value pair.
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data to pass to the function.
</parameter_description>
</parameter>
</parameters>
<return> the number of key/value pairs removed.
</return>
</function>

<function name="g_rand_new_with_seed_array">
<description>
Creates a new random number generator initialized with @seed.


</description>
<parameters>
<parameter name="seed">
<parameter_description> an array of seeds to initialize the random number generator.
</parameter_description>
</parameter>
<parameter name="seed_length">
<parameter_description> an array of seeds to initialize the random number generator.
</parameter_description>
</parameter>
</parameters>
<return> the new #GRand.

Since: 2.4
</return>
</function>

<function name="g_string_prepend_unichar">
<description>
Converts a Unicode character into UTF-8, and prepends it
to the string.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="wc">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> @string
</return>
</function>

<function name="g_rand_set_seed_array">
<description>
Initializes the random number generator by an array of
longs.  Array can be of arbitrary size, though only the
first 624 values are taken.  This function is useful
if you have many low entropy seeds, or if you require more then
32bits of actual entropy for your application.

Since: 2.4

</description>
<parameters>
<parameter name="rand_">
<parameter_description> a #GRand.
</parameter_description>
</parameter>
<parameter name="seed">
<parameter_description> array to initialize with
</parameter_description>
</parameter>
<parameter name="seed_length">
<parameter_description> length of array
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_regex_match_simple">
<description>
Scans for a match in @string for @pattern.

This function is equivalent to g_regex_match() but it does not
require to compile the pattern with g_regex_new(), avoiding some
lines of code when you need just to do a match without extracting
substrings, capture counts, and so on.

If this function is to be called on the same @pattern more than
once, it&apos;s more efficient to compile the pattern once with
g_regex_new() and then use g_regex_match().


</description>
<parameters>
<parameter name="pattern">
<parameter_description> the regular expression
</parameter_description>
</parameter>
<parameter name="string">
<parameter_description> the string to scan for matches
</parameter_description>
</parameter>
<parameter name="compile_options">
<parameter_description> compile options for the regular expression
</parameter_description>
</parameter>
<parameter name="match_options">
<parameter_description> match options
</parameter_description>
</parameter>
</parameters>
<return> %TRUE is the string matched, %FALSE otherwise

Since: 2.14
</return>
</function>

<function name="g_locale_to_utf8">
<description>
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 &amp;lt;link linkend=&quot;setlocale&quot;&amp;gt;current locale&amp;lt;/link&amp;gt; into a
UTF-8 string.


</description>
<parameters>
<parameter name="opsysstring">
<parameter_description>   a string in the encoding of the current locale. On Windows
this means the system codepage.
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description>           the length of the string, or -1 if the string is
nul-terminated&amp;lt;footnoteref linkend=&quot;nul-unsafe&quot;/&amp;gt;. 
</parameter_description>
</parameter>
<parameter name="bytes_read">
<parameter_description>    location to store the number of bytes in the
input string that were successfully converted, or %NULL.
Even if the conversion was successful, this may be 
less than @len if there were partial characters
at the end of the input. If the error
#G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
stored will the byte offset after the last valid
input sequence.
</parameter_description>
</parameter>
<parameter name="bytes_written">
<parameter_description> the number of bytes stored in the output buffer (not 
including the terminating nul).
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description>         location to store the error occuring, or %NULL to ignore
errors. Any of the errors in #GConvertError may occur.
</parameter_description>
</parameter>
</parameters>
<return> The converted string, or %NULL on an error.
</return>
</function>

<function name="g_key_file_get_string">
<description>
Return value: a newly allocated string or %NULL if the specified 

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string or %NULL if the specified 
key cannot be found.

Since: 2.6
</return>
</function>

<function name="g_source_remove_poll">
<description>
Removes a file descriptor from the set of file descriptors polled for
this source. 

</description>
<parameters>
<parameter name="source">
<parameter_description>a #GSource 
</parameter_description>
</parameter>
<parameter name="fd">
<parameter_description> a #GPollFD structure previously passed to g_source_add_poll().
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_regex_match_all_full">
<description>
Using the standard algorithm for regular expression matching only 
the longest match in the string is retrieved, it is not possibile 
to obtain all the available matches. For instance matching
&quot;&amp;lt;a&amp;gt; &amp;lt;b&amp;gt; &amp;lt;c&amp;gt;&quot; against the pattern &quot;&amp;lt;.*&amp;gt;&quot; 
you get &quot;&amp;lt;a&amp;gt; &amp;lt;b&amp;gt; &amp;lt;c&amp;gt;&quot;.

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;&amp;lt;a&amp;gt; &amp;lt;b&amp;gt; &amp;lt;c&amp;gt;&quot; against the pattern &quot;&amp;lt;.*&amp;gt;&quot; 
you would obtain three matches: &quot;&amp;lt;a&amp;gt; &amp;lt;b&amp;gt; &amp;lt;c&amp;gt;&quot;,
&quot;&amp;lt;a&amp;gt; &amp;lt;b&amp;gt;&quot; and &quot;&amp;lt;a&amp;gt;&quot;.

The number of matched strings is retrieved using
g_match_info_get_match_count(). To obtain the matched strings and 
their position you can use, respectively, g_match_info_fetch() and 
g_match_info_fetch_pos(). Note that the strings are returned in 
reverse order of length; that is, the longest matching string is 
given first.

Note that the DFA algorithm is slower than the standard one and it 
is not able to capture substrings, so backreferences do not work.

Setting @start_position differs from just passing over a shortened 
string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern 
that begins with any kind of lookbehind assertion, such as &quot;\b&quot;.

A #GMatchInfo structure, used to get information on the match, is 
stored in @match_info if not %NULL. Note that if @match_info is 
not %NULL then it is created even if the function returns %FALSE, 
i.e. you must free it regardless if regular expression actually 
matched.


</description>
<parameters>
<parameter name="regex">
<parameter_description> a #GRegex structure from g_regex_new()
</parameter_description>
</parameter>
<parameter name="string">
<parameter_description> the string to scan for matches
</parameter_description>
</parameter>
<parameter name="string_len">
<parameter_description> the length of @string, or -1 if @string is nul-terminated
</parameter_description>
</parameter>
<parameter name="start_position">
<parameter_description> starting index of the string to match
</parameter_description>
</parameter>
<parameter name="match_options">
<parameter_description> match options
</parameter_description>
</parameter>
<parameter name="match_info">
<parameter_description> pointer to location where to store the #GMatchInfo, 
or %NULL if you do not need it
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store the error occuring, or %NULL to ignore errors
</parameter_description>
</parameter>
</parameters>
<return> %TRUE is the string matched, %FALSE otherwise

Since: 2.14
</return>
</function>

<function name="g_get_real_name">
<description>
Gets the real name of the user. This usually comes from the user&apos;s entry 
in the &amp;lt;filename&amp;gt;passwd&amp;lt;/filename&amp;gt; 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.


</description>
<parameters>
</parameters>
<return> the user&apos;s real name.
</return>
</function>

<function name="g_strfreev">
<description>
Frees a %NULL-terminated array of strings, and the array itself.
If called on a %NULL value, g_strfreev() simply returns. 

</description>
<parameters>
<parameter name="str_array">
<parameter_description> a %NULL-terminated array of strings to free.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_string_append_c">
<description>
Adds a byte onto the end of a #GString, expanding 
it if necessary.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="c">
<parameter_description> the byte to append onto the end of @string
</parameter_description>
</parameter>
</parameters>
<return> @string
</return>
</function>

<function name="g_key_file_set_value">
<description>
Associates a new value with @key under @group_name.  If @key
cannot be found then it is created. If @group_name cannot be
found then it is created.

Since: 2.6

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="value">
<parameter_description> a string
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_nullify_pointer">
<description>
Set the pointer at the specified location to %NULL.

</description>
<parameters>
<parameter name="nullify_location">
<parameter_description> the memory address of the pointer.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_key_file_set_integer_list">
<description>
Associates a list of integer values with @key under
@group_name.  If @key cannot be found then it is created.

Since: 2.6

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="list">
<parameter_description> an array of integer values
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> number of integer values in @list
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_path_skip_root">
<description>
Returns: a pointer into @file_name after the root component.

</description>
<parameters>
<parameter name="file_name">
<parameter_description> a file name.
</parameter_description>
</parameter>
</parameters>
<return> a pointer into @file_name after the root component.
</return>
</function>

<function name="g_utf8_strlen">
<description>
Return value: the length of the string in characters

</description>
<parameters>
<parameter name="p">
<parameter_description> pointer to the start of a UTF-8 encoded string.
</parameter_description>
</parameter>
<parameter name="max">
<parameter_description> the maximum number of bytes to examine. If @max
is less than 0, then the string is assumed to be
nul-terminated. If @max is 0, @p will not be examined and 
may be %NULL.
</parameter_description>
</parameter>
</parameters>
<return> the length of the string in characters
</return>
</function>

<function name="g_iconv">
<description>
Same as the standard UNIX routine iconv(), but
may be implemented via libiconv on UNIX flavors that lack
a native implementation.

GLib provides g_convert() and g_locale_to_utf8() which are likely
more convenient than the raw iconv wrappers.


</description>
<parameters>
<parameter name="converter">
<parameter_description> conversion descriptor from g_iconv_open()
</parameter_description>
</parameter>
<parameter name="inbuf">
<parameter_description> bytes to convert
</parameter_description>
</parameter>
<parameter name="inbytes_left">
<parameter_description> inout parameter, bytes remaining to convert in @inbuf
</parameter_description>
</parameter>
<parameter name="outbuf">
<parameter_description> converted output bytes
</parameter_description>
</parameter>
<parameter name="outbytes_left">
<parameter_description> inout parameter, bytes available to fill in @outbuf
</parameter_description>
</parameter>
</parameters>
<return> count of non-reversible conversions, or -1 on error
</return>
</function>

<function name="g_main_context_dispatch">
<description>
Dispatches all pending sources.

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_sequence_swap">
<description>
Swaps the items pointed to by @a and @b. It is allowed for @a and @b
to point into difference sequences.

Since: 2.14

</description>
<parameters>
<parameter name="a">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
<parameter name="b">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_path_get_basename">
<description>
Gets the last component of the filename. If @file_name ends with a 
directory separator it gets the component before the last slash. If 
@file_name consists only of directory separators (and on Windows, 
possibly a drive letter), a single separator is returned. If
@file_name is empty, it gets &quot;.&quot;.


</description>
<parameters>
<parameter name="file_name">
<parameter_description> the name of the file.
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string containing the last component of 
the filename.
</return>
</function>

<function name="g_queue_remove_all">
<description>
Remove all elemeents in @queue which contains @data.

Since: 2.4

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> data to remove
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_async_queue_push_sorted_unlocked">
<description>
Inserts @data into @queue using @func to determine the new
position.

This function requires that the @queue is sorted before pushing on
new elements.

This function is called while holding the @queue&apos;s lock.

For an example of @func see g_async_queue_sort(). 

Since: 2.10

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> the @data to push into the @queue
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> the #GCompareDataFunc is used to sort @queue. This function
is passed two elements of the @queue. The function should return
0 if they are equal, a negative value if the first element
should be higher in the @queue or a positive value if the first
element should be lower in the @queue than the second element.
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data passed to @func.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_option_context_set_help_enabled">
<description>
Enables or disables automatic generation of &amp;lt;option&amp;gt;--help&amp;lt;/option&amp;gt; 
output. By default, g_option_context_parse() recognizes
&amp;lt;option&amp;gt;--help&amp;lt;/option&amp;gt;, &amp;lt;option&amp;gt;-?&amp;lt;/option&amp;gt;, &amp;lt;option&amp;gt;--help-all&amp;lt;/option&amp;gt;
and &amp;lt;option&amp;gt;--help-&amp;lt;/option&amp;gt;&amp;lt;replaceable&amp;gt;groupname&amp;lt;/replaceable&amp;gt; and creates
suitable output to stdout. 

Since: 2.6

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GOptionContext
</parameter_description>
</parameter>
<parameter name="help_enabled">
<parameter_description> %TRUE to enable &amp;lt;option&amp;gt;--help&amp;lt;/option&amp;gt;, %FALSE to disable it
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_string_sprintf">
<description>
Writes a formatted string into a #GString.
This is similar to the standard sprintf() function,
except that the #GString buffer automatically expands 
to contain the results. The previous contents of the 
#GString are destroyed. 

Deprecated: This function has been renamed to g_string_printf().

</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="format">
<parameter_description> the string format. See the sprintf() documentation
</parameter_description>
</parameter>
<parameter name="Varargs">
<parameter_description> the parameters to insert into the format string
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_key_file_free">
<description>
Frees a #GKeyFile.

Since: 2.6

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_tree_traverse">
<description>
Calls the given function for each node in the #GTree. 

Deprecated:2.2: The order of a balanced tree is somewhat arbitrary. If you 
just want to visit all nodes in sorted order, use g_tree_foreach() 
instead. If you really need to visit nodes in a different order, consider
using an &amp;lt;link linkend=&quot;glib-N-ary-Trees&quot;&amp;gt;N-ary Tree&amp;lt;/link&amp;gt;.

</description>
<parameters>
<parameter name="tree">
<parameter_description> a #GTree.
</parameter_description>
</parameter>
<parameter name="traverse_func">
<parameter_description> the function to call for each node visited. If this 
function returns %TRUE, the traversal is stopped.
</parameter_description>
</parameter>
<parameter name="traverse_type">
<parameter_description> the order in which nodes are visited, one of %G_IN_ORDER,
%G_PRE_ORDER and %G_POST_ORDER.
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data to pass to the function.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_string_overwrite">
<description>
Overwrites part of a string, lengthening it if necessary.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="pos">
<parameter_description> the position at which to start overwriting
</parameter_description>
</parameter>
<parameter name="val">
<parameter_description> the string that will overwrite the @string starting at @pos
</parameter_description>
</parameter>
</parameters>
<return> @string

Since: 2.14
</return>
</function>

<function name="g_rand_int_range">
<description>
Return value: A random number.

</description>
<parameters>
<parameter name="rand_">
<parameter_description> a #GRand.
</parameter_description>
</parameter>
<parameter name="begin">
<parameter_description> lower closed bound of the interval.
</parameter_description>
</parameter>
<parameter name="end">
<parameter_description> upper open bound of the interval.
</parameter_description>
</parameter>
</parameters>
<return> A random number.
</return>
</function>

<function name="g_get_filename_charsets">
<description>
Determines the preferred character sets used for filenames.
The first character set from the @charsets is the filename encoding, the
subsequent character sets are used when trying to generate a displayable
representation of a filename, see g_filename_display_name().

On Unix, the character sets are determined by consulting the
environment variables &amp;lt;envar&amp;gt;G_FILENAME_ENCODING&amp;lt;/envar&amp;gt; and
&amp;lt;envar&amp;gt;G_BROKEN_FILENAMES&amp;lt;/envar&amp;gt;. On Windows, the character set
used in the GLib API is always UTF-8 and said environment variables
have no effect.

&amp;lt;envar&amp;gt;G_FILENAME_ENCODING&amp;lt;/envar&amp;gt; may be set to a comma-separated list 
of character set names. The special token &quot;&amp;commat;locale&quot; is taken to 
mean the character set for the &amp;lt;link linkend=&quot;setlocale&quot;&amp;gt;current 
locale&amp;lt;/link&amp;gt;. If &amp;lt;envar&amp;gt;G_FILENAME_ENCODING&amp;lt;/envar&amp;gt; is not set, but 
&amp;lt;envar&amp;gt;G_BROKEN_FILENAMES&amp;lt;/envar&amp;gt; is, the character set of the current 
locale is taken as the filename encoding. If neither environment variable 
is set, UTF-8 is taken as the filename encoding, but the character
set of the current locale is also put in the list of encodings.

The returned @charsets belong to GLib and must not be freed.

Note that on Unix, regardless of the locale character set or
&amp;lt;envar&amp;gt;G_FILENAME_ENCODING&amp;lt;/envar&amp;gt; value, the actual file names present 
on a system might be in any random encoding or just gibberish.


</description>
<parameters>
<parameter name="charsets">
<parameter_description> return location for the %NULL-terminated list of encoding names
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the filename encoding is UTF-8.

Since: 2.6
</return>
</function>

<function name="g_regex_get_pattern">
<description>
Gets the pattern string associated with @regex, i.e. a copy of 
the string passed to g_regex_new().


</description>
<parameters>
<parameter name="regex">
<parameter_description> a #GRegex structure
</parameter_description>
</parameter>
</parameters>
<return> the pattern of @regex

Since: 2.14
</return>
</function>

<function name="g_source_get_current_time">
<description>
Gets the &quot;current time&quot; to be used when checking 
this source. The advantage of calling this function over
calling g_get_current_time() directly is that when 
checking multiple sources, GLib can cache a single value
instead of having to repeatedly get the system time.

</description>
<parameters>
<parameter name="source">
<parameter_description>  a #GSource
</parameter_description>
</parameter>
<parameter name="timeval">
<parameter_description> #GTimeVal structure in which to store current time.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_async_queue_push_unlocked">
<description>
Pushes the @data into the @queue. @data must not be %NULL. This
function must be called while holding the @queue&apos;s lock.

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue.
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> @data to push into the @queue.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_regex_get_max_backref">
<description>
Returns: the number of the highest back reference

</description>
<parameters>
<parameter name="regex">
<parameter_description> a #GRegex
</parameter_description>
</parameter>
</parameters>
<return> the number of the highest back reference

Since: 2.14
</return>
</function>

<function name="g_queue_peek_tail_link">
<description>
Return value: the last link in @queue, or %NULL if @queue is empty

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
</parameters>
<return> the last link in @queue, or %NULL if @queue is empty

Since: 2.4
</return>
</function>

<function name="g_build_path">
<description>
Creates a path from a series of elements using @separator as the
separator between elements. At the boundary between two elements,
any trailing occurrences of separator in the first element, or
leading occurrences of separator in the second element are removed
and exactly one copy of the separator is inserted.

Empty elements are ignored.

The number of leading copies of the separator on the result is
the same as the number of leading copies of the separator on
the first non-empty element.

The number of trailing copies of the separator on the result is
the same as the number of trailing copies of the separator on
the last non-empty element. (Determination of the number of
trailing copies is done without stripping leading copies, so
if the separator is &amp;lt;literal&amp;gt;ABA&amp;lt;/literal&amp;gt;, &amp;lt;literal&amp;gt;ABABA&amp;lt;/literal&amp;gt;
has 1 trailing copy.)

However, if there is only a single non-empty element, and there
are no characters in that element not part of the leading or
trailing separators, then the result is exactly the original value
of that element.

Other than for determination of the number of leading and trailing
copies of the separator, elements consisting only of copies
of the separator are ignored.


</description>
<parameters>
<parameter name="separator">
<parameter_description> a string used to separator the elements of the path.
</parameter_description>
</parameter>
<parameter name="first_element">
<parameter_description> the first element in the path
</parameter_description>
</parameter>
<parameter name="Varargs">
<parameter_description> remaining elements in path, terminated by %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly-allocated string that must be freed with g_free().
</return>
</function>

<function name="g_ascii_xdigit_value">
<description>
Determines the numeric value of a character as a hexidecimal
digit. Differs from g_unichar_xdigit_value() because it takes
a char, so there&apos;s no worry about sign extension if characters
are signed.


</description>
<parameters>
<parameter name="c">
<parameter_description> an ASCII character.
</parameter_description>
</parameter>
</parameters>
<return> If @c is a hex digit (according to
g_ascii_isxdigit()), its numeric value. Otherwise, -1.
</return>
</function>

<function name="g_bookmark_file_get_description">
<description>
Retrieves the description of the bookmark for @uri.

In the event the URI cannot be found, %NULL is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string or %NULL if the specified
URI cannot be found.

Since: 2.12
</return>
</function>

<function name="g_sequence_free">
<description>
Frees the memory allocated for @seq. If @seq has a data destroy 
function associated with it, that function is called on all items in
@seq.

Since: 2.14

</description>
<parameters>
<parameter name="seq">
<parameter_description> a #GSequence
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_random_set_seed">
<description>
Sets the seed for the global random number generator, which is used
by the &amp;lt;function&amp;gt;g_random_*&amp;lt;/function&amp;gt; functions, to @seed.

</description>
<parameters>
<parameter name="seed">
<parameter_description> a value to reinitialize the global random number generator.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_sequence_append">
<description>
Adds a new item to the end of @seq.


</description>
<parameters>
<parameter name="seq">
<parameter_description> a #GSequencePointer
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> the data for the new item
</parameter_description>
</parameter>
</parameters>
<return> an iterator pointing to the new item

Since: 2.14
</return>
</function>

<function name="g_source_set_priority">
<description>
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.

</description>
<parameters>
<parameter name="source">
<parameter_description> a #GSource
</parameter_description>
</parameter>
<parameter name="priority">
<parameter_description> the new priority.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_regex_split_simple">
<description>
Breaks the string on the pattern, and returns an array of 
the tokens. If the pattern contains capturing parentheses, 
then the text for each of the substrings will also be returned. 
If the pattern does not match anywhere in the string, then the 
whole string is returned as the first token.

This function is equivalent to g_regex_split() but it does 
not require to compile the pattern with g_regex_new(), avoiding 
some lines of code when you need just to do a split without 
extracting substrings, capture counts, and so on.

If this function is to be called on the same @pattern more than
once, it&apos;s more efficient to compile the pattern once with
g_regex_new() and then use g_regex_split().

As a special case, the result of splitting the empty string &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 
a empty vector is typically more useful than consistent handling 
of empty elements. If you do need to represent empty elements, 
you&apos;ll need to check for the empty string before calling this 
function.

A pattern that can match empty strings splits @string into 
separate characters wherever it matches the empty string between 
characters. For example splitting &quot;ab c&quot; using as a separator 
&quot;\s*&quot;, you will get &quot;a&quot;, &quot;b&quot; and &quot;c&quot;.


</description>
<parameters>
<parameter name="pattern">
<parameter_description> the regular expression
</parameter_description>
</parameter>
<parameter name="string">
<parameter_description> the string to scan for matches
</parameter_description>
</parameter>
<parameter name="compile_options">
<parameter_description> compile options for the regular expression
</parameter_description>
</parameter>
<parameter name="match_options">
<parameter_description> match options
</parameter_description>
</parameter>
</parameters>
<return> a %NULL-terminated gchar ** array. Free it using g_strfreev()

Since: 2.14
</return>
</function>

<function name="g_sequence_foreach">
<description>
Calls @func for each item in the sequence passing @user_data
to the function.

Since: 2.14

</description>
<parameters>
<parameter name="seq">
<parameter_description> a #GSequence
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> the function to call for each item in @seq
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data passed to @func
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_hash_table_steal_all">
<description>
Removes all keys and their associated values from a #GHashTable 
without calling the key and value destroy functions.

Since: 2.12

</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a #GHashTable.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_file_open_tmp">
<description>
Opens a file for writing in the preferred directory for temporary
files (as returned by g_get_tmp_dir()). 

@tmpl should be a string in the GLib file name encoding containing 
a sequence of six &apos;X&apos; characters, as the parameter to g_mkstemp().
However, unlike these functions, the template should only be a
basename, no directory components are allowed. If template is
%NULL, a default template is used.

Note that in contrast to g_mkstemp() (and mkstemp()) 
@tmpl is not modified, and might thus be a read-only literal string.

The actual name used is returned in @name_used if non-%NULL. This
string should be freed with g_free() when not needed any longer.
The returned name is in the GLib file name encoding.


</description>
<parameters>
<parameter name="tmpl">
<parameter_description> Template for file name, as in g_mkstemp(), basename only,
or %NULL, to a default template
</parameter_description>
</parameter>
<parameter name="name_used">
<parameter_description> location to store actual name used
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError
</parameter_description>
</parameter>
</parameters>
<return> A file handle (as from open()) to 
the file opened for reading and writing. The file is opened in binary 
mode on platforms where there is a difference. The file handle should be
closed with close(). In case of errors, -1 is returned 
and @error will be set.
</return>
</function>

<function name="g_main_context_remove_poll">
<description>
Removes file descriptor from the set of file descriptors to be
polled for a particular context.

</description>
<parameters>
<parameter name="context">
<parameter_description>a #GMainContext 
</parameter_description>
</parameter>
<parameter name="fd">
<parameter_description> a #GPollFD descriptor previously added with g_main_context_add_poll()
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_source_get_id">
<description>
Return value: the ID (greater than 0) for the source

</description>
<parameters>
<parameter name="source">
<parameter_description> a #GSource
</parameter_description>
</parameter>
</parameters>
<return> the ID (greater than 0) for the source
</return>
</function>

<function name="g_mapped_file_get_contents">
<description>
Returns: the contents of @file.

</description>
<parameters>
<parameter name="file">
<parameter_description> a #GMappedFile
</parameter_description>
</parameter>
</parameters>
<return> the contents of @file.

Since: 2.8
</return>
</function>

<function name="g_direct_equal">
<description>
Compares two #gpointer arguments and returns %TRUE if they are equal.
It can be passed to g_hash_table_new() as the @key_equal_func
parameter, when using pointers as keys in a #GHashTable.


</description>
<parameters>
<parameter name="v1">
<parameter_description> a key.
</parameter_description>
</parameter>
<parameter name="v2">
<parameter_description> a key to compare with @v1.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the two keys match.
</return>
</function>

<function name="g_hash_table_new">
<description>
Creates a new #GHashTable with a reference count of 1.


</description>
<parameters>
<parameter name="hash_func">
<parameter_description> a function to create a hash value from a key.
Hash values are used to determine where keys are stored within the
#GHashTable data structure. The g_direct_hash(), g_int_hash() and 
g_str_hash() functions are provided for some common types of keys. 
If hash_func is %NULL, g_direct_hash() is used.
</parameter_description>
</parameter>
<parameter name="key_equal_func">
<parameter_description> a function to check two keys for equality.  This is
used when looking up keys in the #GHashTable.  The g_direct_equal(),
g_int_equal() and g_str_equal() functions are provided for the most
common types of keys. If @key_equal_func is %NULL, keys are compared
directly in a similar fashion to g_direct_equal(), but without the
overhead of a function call.
</parameter_description>
</parameter>
</parameters>
<return> a new #GHashTable.
</return>
</function>

<function name="g_tree_nnodes">
<description>
Gets the number of nodes in a #GTree.


</description>
<parameters>
<parameter name="tree">
<parameter_description> a #GTree.
</parameter_description>
</parameter>
</parameters>
<return> the number of nodes in the #GTree.
</return>
</function>

<function name="g_bookmark_file_load_from_data">
<description>
Loads a bookmark file from memory into an empty #GBookmarkFile
structure.  If the object cannot be created then @error is set to a
#GBookmarkFileError.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> an empty #GBookmarkFile struct
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> desktop bookmarks loaded in memory
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> the length of @data in bytes
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if a desktop bookmark could be loaded.

Since: 2.12
</return>
</function>

<function name="g_option_context_set_translation_domain">
<description>
A convenience function to use gettext() for translating
user-visible strings. 

Since: 2.12

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GOptionContext
</parameter_description>
</parameter>
<parameter name="domain">
<parameter_description> the domain to use
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_win32_getlocale">
<description>
The setlocale() function in the Microsoft C library uses locale
names of the form &quot;English_United States.1252&quot; etc. We want the
UNIXish standard form &quot;en_US&quot;, &quot;zh_TW&quot; etc. This function gets the
current thread locale from Windows - without any encoding info -
and returns it as a string of the above form for use in forming
file names etc. The returned string should be deallocated with
g_free().


</description>
<parameters>
</parameters>
<return> newly-allocated locale name.
</return>
</function>

<function name="g_sequence_iter_get_sequence">
<description>
Return value: the #GSequence that @iter points into.

</description>
<parameters>
<parameter name="iter">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
</parameters>
<return> the #GSequence that @iter points into.

Since: 2.14
</return>
</function>

<function name="g_markup_parse_context_get_element">
<description>
Retrieves the name of the currently open element.

Since: 2.2

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMarkupParseContext
</parameter_description>
</parameter>
</parameters>
<return> the name of the currently open element, or %NULL
</return>
</function>

<function name="g_rename">
<description>
A wrapper for the POSIX rename() function. The rename() function 
renames a file, moving it between directories if required.

See your C library manual for more details about how rename() works
on your system. Note in particular that on Win9x it is not possible
to rename a file if a file with the new name already exists. Also
it is not possible in general on Windows to rename an open file.


</description>
<parameters>
<parameter name="oldfilename">
<parameter_description> a pathname in the GLib file name encoding (UTF-8 on Windows)
</parameter_description>
</parameter>
<parameter name="newfilename">
<parameter_description> a pathname in the GLib file name encoding
</parameter_description>
</parameter>
</parameters>
<return> 0 if the renaming succeeded, -1 if an error occurred

Since: 2.6
</return>
</function>

<function name="g_io_channel_get_buffer_size">
<description>
Gets the buffer size.


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
</parameters>
<return> the size of the buffer.
</return>
</function>

<function name="g_queue_copy">
<description>
Copies a @queue. Note that is a shallow copy. If the elements in the
queue consist of pointers to data, the pointers are copied, but the
actual data is not.


</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
</parameters>
<return> A copy of @queue

Since: 2.4
</return>
</function>

<function name="g_queue_sort">
<description>
Sorts @queue using @compare_func. 

Since: 2.4

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="compare_func">
<parameter_description> the #GCompareDataFunc used to sort @queue. This function
is passed two elements of the queue and should return 0 if they are
equal, a negative value if the first comes before the second, and
a positive value if the second comes before the first.
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data passed to @compare_func
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_tree_lookup_extended">
<description>
Looks up a key in the #GTree, returning the original key and the
associated value and a #gboolean which is %TRUE if the key was found. This 
is useful if you need to free the memory allocated for the original key, 
for example before calling g_tree_remove().


</description>
<parameters>
<parameter name="tree">
<parameter_description> a #GTree.
</parameter_description>
</parameter>
<parameter name="lookup_key">
<parameter_description> the key to look up.
</parameter_description>
</parameter>
<parameter name="orig_key">
<parameter_description> returns the original key.
</parameter_description>
</parameter>
<parameter name="value">
<parameter_description> returns the value associated with the key.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the key was found in the #GTree.
</return>
</function>

<function name="g_unichar_isupper">
<description>
Determines if a character is uppercase.


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @c is an uppercase character
</return>
</function>

<function name="g_unichar_digit_value">
<description>
Determines the numeric value of a character as a decimal
digit.


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> If @c is a decimal digit (according to
g_unichar_isdigit()), its numeric value. Otherwise, -1.
</return>
</function>

<function name="g_bookmark_file_remove_application">
<description>
Removes application registered with @name from the list of applications
that have registered a bookmark for @uri inside @bookmark.

In the event the URI cannot be found, %FALSE is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
In the event that no application with name @app_name has registered
a bookmark for @uri,  %FALSE is returned and error is set to
#G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="name">
<parameter_description> the name of the application
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the application was successfully removed.

Since: 2.12
</return>
</function>

<function name="g_ptr_array_foreach">
<description>
Calls a function for each element of a #GPtrArray.

Since: 2.4

</description>
<parameters>
<parameter name="array">
<parameter_description> a #GPtrArray
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> the function to call for each array element
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data to pass to the function
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_string_assign">
<description>
Copies the bytes from a string into a #GString, 
destroying any previous contents. It is rather like 
the standard strcpy() function, except that you do not 
have to worry about having enough space to copy the string.


</description>
<parameters>
<parameter name="string">
<parameter_description> the destination #GString. Its current contents 
are destroyed.
</parameter_description>
</parameter>
<parameter name="rval">
<parameter_description> the string to copy into @string
</parameter_description>
</parameter>
</parameters>
<return> @string
</return>
</function>

<function name="g_option_context_set_main_group">
<description>
Sets a #GOptionGroup as main group of the @context. 
This has the same effect as calling g_option_context_add_group(), 
the only difference is that the options in the main group are 
treated differently when generating &amp;lt;option&amp;gt;--help&amp;lt;/option&amp;gt; output.

Since: 2.6

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GOptionContext
</parameter_description>
</parameter>
<parameter name="group">
<parameter_description> the group to set as main group
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_file_get_contents">
<description>
Reads an entire file into allocated memory, with good error
checking. 

If the call was successful, it returns %TRUE and sets @contents to the file 
contents and @length to the length of the file contents in bytes. The string 
stored in @contents will be nul-terminated, so for text files you can pass 
%NULL for the @length argument. If the call was not successful, it returns 
%FALSE and sets @error. The error domain is #G_FILE_ERROR. Possible error  
codes are those in the #GFileError enumeration. In the error case, 
@contents is set to %NULL and @length is set to zero.


</description>
<parameters>
<parameter name="filename">
<parameter_description> name of a file to read contents from, in the GLib file name encoding
</parameter_description>
</parameter>
<parameter name="contents">
<parameter_description> location to store an allocated string
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> location to store length in bytes of the contents, or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE on success, %FALSE if an error occurred
</return>
</function>

<function name="g_thread_pool_get_num_unused_threads">
<description>
Return value: the number of currently unused threads

</description>
<parameters>
</parameters>
<return> the number of currently unused threads
</return>
</function>

<function name="g_string_truncate">
<description>
Cuts off the end of the GString, leaving the first @len bytes. 


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the new size of @string
</parameter_description>
</parameter>
</parameters>
<return> @string
</return>
</function>

<function name="g_key_file_set_string">
<description>
Associates a new string value with @key under @group_name.  If
@key cannot be found then it is created.  If @group_name
cannot be found then it is created.

Since: 2.6

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="string">
<parameter_description> a string
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_key_file_get_boolean_list">
<description>
Return value: the values associated with the key as a list of

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> the number of booleans returned
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError
</parameter_description>
</parameter>
</parameters>
<return> the values associated with the key as a list of
booleans, or %NULL if the key was not found or could not be parsed.

Since: 2.6
</return>
</function>

<function name="g_fopen">
<description>
A wrapper for the POSIX fopen() function. The fopen() function opens
a file and associates a new stream with it. 

See the C library manual for more details about fopen().


</description>
<parameters>
<parameter name="filename">
<parameter_description> a pathname in the GLib file name encoding (UTF-8 on Windows)
</parameter_description>
</parameter>
<parameter name="mode">
<parameter_description> a string describing the mode in which the file should be 
opened
</parameter_description>
</parameter>
</parameters>
<return> A &amp;lt;type&amp;gt;FILE&amp;lt;/type&amp;gt; pointer if the file was successfully
opened, or %NULL if an error occurred

Since: 2.6
</return>
</function>

<function name="g_error_copy">
<description>
Makes a copy of @error.


</description>
<parameters>
<parameter name="error">
<parameter_description> a #GError
</parameter_description>
</parameter>
</parameters>
<return> a new #GError
</return>
</function>

<function name="g_match_info_fetch_named_pos">
<description>
Retrieves the position of the capturing parentheses named @name.

If @name is a valid sub pattern name but it didn&apos;t match anything 
(e.g. sub pattern &quot;X&quot;, matching &quot;b&quot; against &quot;(?P&amp;lt;X&amp;gt;a)?b&quot;) 
then @start_pos and @end_pos are set to -1 and %TRUE is returned.


</description>
<parameters>
<parameter name="match_info">
<parameter_description> #GMatchInfo structure
</parameter_description>
</parameter>
<parameter name="name">
<parameter_description> name of the subexpression
</parameter_description>
</parameter>
<parameter name="start_pos">
<parameter_description> pointer to location where to store the start position
</parameter_description>
</parameter>
<parameter name="end_pos">
<parameter_description> pointer to location where to store the end position
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the position was fetched, %FALSE otherwise. If 
the position cannot be fetched, @start_pos and @end_pos are left
unchanged

Since: 2.14
</return>
</function>

<function name="g_regex_split">
<description>
Breaks the string on the pattern, and returns an array of the tokens.
If the pattern contains capturing parentheses, then the text for each
of the substrings will also be returned. If the pattern does not match
anywhere in the string, then the whole string is returned as the first
token.

As a special case, the result of splitting the empty string &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 a empty vector is
typically more useful than consistent handling of empty elements. If
you do need to represent empty elements, you&apos;ll need to check for the
empty string before calling this function.

A pattern that can match empty strings splits @string into separate
characters wherever it matches the empty string between characters.
For example splitting &quot;ab c&quot; using as a separator &quot;\s*&quot;, you will get
&quot;a&quot;, &quot;b&quot; and &quot;c&quot;.


</description>
<parameters>
<parameter name="regex">
<parameter_description> a #GRegex structure
</parameter_description>
</parameter>
<parameter name="string">
<parameter_description> the string to split with the pattern
</parameter_description>
</parameter>
<parameter name="match_options">
<parameter_description> match time option flags
</parameter_description>
</parameter>
</parameters>
<return> a %NULL-terminated gchar ** array. Free it using g_strfreev()

Since: 2.14
</return>
</function>

<function name="g_mapped_file_new">
<description>
Maps a file into memory. On UNIX, this is using the mmap() function.

If @writable is %TRUE, the mapped buffer may be modified, otherwise
it is an error to modify the mapped buffer. Modifications to the buffer 
are not visible to other processes mapping the same file, and are not 
written back to the file.

Note that modifications of the underlying file might affect the contents
of the #GMappedFile. Therefore, mapping should only be used if the file 
will not be modified, or if all modifications of the file are done
atomically (e.g. using g_file_set_contents()). 


</description>
<parameters>
<parameter name="filename">
<parameter_description> The path of the file to load, in the GLib filename encoding
</parameter_description>
</parameter>
<parameter name="writable">
<parameter_description> wether the mapping should be writable
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated #GMappedFile which must be freed
with g_mapped_file_free(), or %NULL if the mapping failed. 

Since: 2.8
</return>
</function>

<function name="g_io_channel_read">
<description>
Reads data from a #GIOChannel. 


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel. 
</parameter_description>
</parameter>
<parameter name="buf">
<parameter_description> a buffer to read the data into (which should be at least count bytes long).
</parameter_description>
</parameter>
<parameter name="count">
<parameter_description> the number of bytes to read from the #GIOChannel.
</parameter_description>
</parameter>
<parameter name="bytes_read">
<parameter_description> returns the number of bytes actually read. 
</parameter_description>
</parameter>
</parameters>
<return> %G_IO_ERROR_NONE if the operation was successful. 

Deprecated:2.2: Use g_io_channel_read_chars() instead.
</return>
</function>

<function name="g_ucs4_to_utf8">
<description>
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.


</description>
<parameters>
<parameter name="str">
<parameter_description> a UCS-4 encoded string
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the maximum length (number of characters) of @str to use. 
If @len &amp;lt; 0, then the string is terminated with a 0 character.
</parameter_description>
</parameter>
<parameter name="items_read">
<parameter_description> location to store number of characters read, or %NULL.
</parameter_description>
</parameter>
<parameter name="items_written">
<parameter_description> location to store number of bytes written or %NULL.
The value here stored does not include the trailing 0
byte. 
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store the error occuring, or %NULL to ignore
errors. Any of the errors in #GConvertError other than
%G_CONVERT_ERROR_NO_CONVERSION may occur.
</parameter_description>
</parameter>
</parameters>
<return> a pointer to a newly allocated UTF-8 string.
This value must be freed with g_free(). If an
error occurs, %NULL will be returned and
@error set. In that case, @items_read will be
set to the position of the first invalid input 
character.
</return>
</function>

<function name="g_unichar_isprint">
<description>
Determines whether a character is printable.
Unlike g_unichar_isgraph(), returns %TRUE for spaces.
Given some UTF-8 text, obtain a character value with
g_utf8_get_char().


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @c is printable
</return>
</function>

<function name="g_source_set_callback">
<description>
Sets the callback function for a source. The callback for a source is
called from the source&apos;s dispatch function.

The exact type of @func depends on the type of source; ie. you
should not count on @func being called with @data as its first
parameter.

Typically, you won&apos;t use this function. Instead use functions specific
to the type of source you are using.

</description>
<parameters>
<parameter name="source">
<parameter_description> the source
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> a callback function
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> the data to pass to callback function
</parameter_description>
</parameter>
<parameter name="notify">
<parameter_description> a function to call when @data is no longer in use, or %NULL.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_sequence_sort_iter">
<description>
Like g_sequence_sort(), but uses a #GSequenceIterCompareFunc instead
of a GCompareDataFunc as the compare function

Since: 2.14

</description>
<parameters>
<parameter name="seq">
<parameter_description> a #GSequence
</parameter_description>
</parameter>
<parameter name="cmp_func">
<parameter_description> the #GSequenceItercompare used to compare iterators in the
sequence. It is called with two iterators pointing into @seq. It should
return 0 if the iterators are equal, a negative value if the first
iterator comes before the second, and a positive value if the second
iterator comes before the first.
</parameter_description>
</parameter>
<parameter name="cmp_data">
<parameter_description> user data passed to @cmp_func
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_bookmark_file_to_data">
<description>
This function outputs @bookmark as a string.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> return location for the length of the returned string, or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string holding
the contents of the #GBookmarkFile

Since: 2.12
</return>
</function>

<function name="g_main_loop_get_context">
<description>
Return value: the #GMainContext of @loop

</description>
<parameters>
<parameter name="loop">
<parameter_description> a #GMainLoop.
</parameter_description>
</parameter>
</parameters>
<return> the #GMainContext of @loop
</return>
</function>

<function name="g_async_queue_lock">
<description>
Acquires the @queue&apos;s lock. After that you can only call the
&amp;lt;function&amp;gt;g_async_queue_*_unlocked()&amp;lt;/function&amp;gt; function variants on that
@queue. Otherwise it will deadlock.

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_utf8_strup">
<description>
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.)


</description>
<parameters>
<parameter name="str">
<parameter_description> a UTF-8 encoded string
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> length of @str, in bytes, or -1 if @str is nul-terminated.
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string, with all characters
converted to uppercase.  
</return>
</function>

<function name="g_source_set_can_recurse">
<description>
Sets whether a source can be called recursively. If @can_recurse is
%TRUE, then while the source is being dispatched then this source
will be processed normally. Otherwise, all processing of this
source is blocked until the dispatch function returns.

</description>
<parameters>
<parameter name="source">
<parameter_description> a #GSource
</parameter_description>
</parameter>
<parameter name="can_recurse">
<parameter_description> whether recursion is allowed for this source
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_io_channel_seek_position">
<description>
Replacement for g_io_channel_seek() with the new API.


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
<parameter name="offset">
<parameter_description> The offset in bytes from the position specified by @type
</parameter_description>
</parameter>
<parameter name="type">
<parameter_description> a #GSeekType. The type %G_SEEK_CUR is only allowed in those
cases where a call to g_io_channel_set_encoding ()
is allowed. See the documentation for
g_io_channel_set_encoding () for details.
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> A location to return an error of type #GIOChannelError
</parameter_description>
</parameter>
</parameters>
<return> the status of the operation.
</return>
</function>

<function name="g_printf">
<description>
An implementation of the standard printf() function which supports 
positional parameters, as specified in the Single Unix Specification.


</description>
<parameters>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice 
&amp;lt;link linkend=&quot;string-precision&quot;&amp;gt;string precision pitfalls&amp;lt;/link&amp;gt;.
</parameter_description>
</parameter>
<parameter name="Varargs">
<parameter_description> the arguments to insert in the output.
</parameter_description>
</parameter>
</parameters>
<return> the number of characters printed.

Since: 2.2
</return>
</function>

<function name="g_queue_insert_before">
<description>
Inserts @data into @queue before @sibling.

@sibling must be part of @queue.

Since: 2.4

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="sibling">
<parameter_description> a #GList link that &amp;lt;emphasis&amp;gt;must&amp;lt;/emphasis&amp;gt; be part of @queue
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> the data to insert
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_queue_clear">
<description>
Removes all the elements in @queue. If queue elements contain
dynamically-allocated memory, they should be freed first.

Since: 2.14

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_setenv">
<description>
Sets an environment variable. Both the variable&apos;s name and value
should be in the GLib file name encoding. On UNIX, this means that
they can be any sequence of bytes. On Windows, they should be in
UTF-8.

Note that on some systems, when variables are overwritten, the memory 
used for the previous variables and its value isn&apos;t reclaimed.


</description>
<parameters>
<parameter name="variable">
<parameter_description> the environment variable to set, must not contain &apos;=&apos;.
</parameter_description>
</parameter>
<parameter name="value">
<parameter_description> the value for to set the variable to.
</parameter_description>
</parameter>
<parameter name="overwrite">
<parameter_description> whether to change the variable if it already exists.
</parameter_description>
</parameter>
</parameters>
<return> %FALSE if the environment variable couldn&apos;t be set.

Since: 2.4
</return>
</function>

<function name="g_regex_replace_eval">
<description>
Replaces occurances of the pattern in regex with the output of 
@eval for that occurance.

Setting @start_position differs from just passing over a shortened 
string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern 
that begins with any kind of lookbehind assertion, such as &quot;\b&quot;.


</description>
<parameters>
<parameter name="regex">
<parameter_description> a #GRegex structure from g_regex_new()
</parameter_description>
</parameter>
<parameter name="string">
<parameter_description> string to perform matches against
</parameter_description>
</parameter>
<parameter name="string_len">
<parameter_description> the length of @string, or -1 if @string is nul-terminated
</parameter_description>
</parameter>
<parameter name="start_position">
<parameter_description> starting index of the string to match
</parameter_description>
</parameter>
<parameter name="match_options">
<parameter_description> options for the match
</parameter_description>
</parameter>
<parameter name="eval">
<parameter_description> a function to call for each match
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data to pass to the function
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store the error occuring, or %NULL to ignore errors
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string containing the replacements

Since: 2.14
</return>
</function>

<function name="g_hash_table_lookup_extended">
<description>
Looks up a key in the #GHashTable, returning the original key and the
associated value and a #gboolean which is %TRUE if the key was found. This 
is useful if you need to free the memory allocated for the original key, 
for example before calling g_hash_table_remove().


</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a #GHashTable.
</parameter_description>
</parameter>
<parameter name="lookup_key">
<parameter_description> the key to look up.
</parameter_description>
</parameter>
<parameter name="orig_key">
<parameter_description> returns the original key.
</parameter_description>
</parameter>
<parameter name="value">
<parameter_description> returns the value associated with the key.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the key was found in the #GHashTable.
</return>
</function>

<function name="g_bookmark_file_get_mime_type">
<description>
Retrieves the MIME type of the resource pointed by @uri.

In the event the URI cannot be found, %NULL is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.  In the
event that the MIME type cannot be found, %NULL is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string or %NULL if the specified
URI cannot be found.

Since: 2.12
</return>
</function>

<function name="g_datalist_unset_flags">
<description>
Turns off flag values for a data list. See g_datalist_unset_flags()

Since: 2.8

</description>
<parameters>
<parameter name="datalist">
<parameter_description> pointer to the location that holds a list
</parameter_description>
</parameter>
<parameter name="flags">
<parameter_description> the flags to turn off. The values of the flags are
restricted by %G_DATALIST_FLAGS_MASK (currently
3: giving two possible boolean flags).
A value for @flags that doesn&apos;t fit within the mask is
an error.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_utf8_collate_key_for_filename">
<description>
Converts a string into a collation key that can be compared
with other collation keys produced by the same function using strcmp(). 

In order to sort filenames correctly, this function treats the dot &apos;.&apos; 
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;.

Note that this function depends on the 
&amp;lt;link linkend=&quot;setlocale&quot;&amp;gt;current locale&amp;lt;/link&amp;gt;.


</description>
<parameters>
<parameter name="str">
<parameter_description> a UTF-8 encoded string.
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> length of @str, in bytes, or -1 if @str is nul-terminated.
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string. This string should
be freed with g_free() when you are done with it.

Since: 2.8
</return>
</function>

<function name="g_convert_with_fallback">
<description>
Converts a string from one character set to another, possibly
including fallback sequences for characters not representable
in the output. Note that it is not guaranteed that the specification
for the fallback sequences in @fallback will be honored. Some
systems may do a approximate conversion from @from_codeset
to @to_codeset in their iconv() functions, 
in which case GLib will simply return that approximate conversion.

Note that you should use g_iconv() for streaming 
conversions&amp;lt;footnoteref linkend=&quot;streaming-state&quot;/&amp;gt;.


</description>
<parameters>
<parameter name="str">
<parameter_description>          the string to convert
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description>          the length of the string, or -1 if the string is 
nul-terminated&amp;lt;footnoteref linkend=&quot;nul-unsafe&quot;/&amp;gt;. 
</parameter_description>
</parameter>
<parameter name="to_codeset">
<parameter_description>   name of character set into which to convert @str
</parameter_description>
</parameter>
<parameter name="from_codeset">
<parameter_description> character set of @str.
</parameter_description>
</parameter>
<parameter name="fallback">
<parameter_description>     UTF-8 string to use in place of character not
present in the target encoding. (The string must be
representable in the target encoding). 
                  If %NULL, characters not in the target encoding will 
                  be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
</parameter_description>
</parameter>
<parameter name="bytes_read">
<parameter_description>   location to store the number of bytes in the
input string that were successfully converted, or %NULL.
Even if the conversion was successful, this may be 
less than @len if there were partial characters
at the end of the input.
</parameter_description>
</parameter>
<parameter name="bytes_written">
<parameter_description> the number of bytes stored in the output buffer (not 
including the terminating nul).
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description>        location to store the error occuring, or %NULL to ignore
errors. Any of the errors in #GConvertError may occur.
</parameter_description>
</parameter>
</parameters>
<return> If the conversion was successful, a newly allocated
nul-terminated string, which must be freed with
g_free(). Otherwise %NULL and @error will be set.
</return>
</function>

<function name="g_sequence_move_range">
<description>
Inserts the (@begin, @end) range at the destination pointed to by ptr.
The @begin and @end iters must point into the same sequence. It is
allowed for @dest to point to a different sequence than the one pointed
into by @begin and @end.

If @dest is NULL, the range indicated by @begin and @end is
removed from the sequence. If @dest iter points to a place within
the (@begin, @end) range, the range does not move.

Since: 2.14

</description>
<parameters>
<parameter name="dest">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
<parameter name="begin">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
<parameter name="end">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_bookmark_file_set_modified">
<description>
Sets the last time the bookmark for @uri was last modified.

If no bookmark for @uri is found then it is created.

The &quot;modified&quot; time should only be set when the bookmark&apos;s meta-data
was actually changed.  Every function of #GBookmarkFile that
modifies a bookmark also changes the modification time, except for
g_bookmark_file_set_visited().

Since: 2.12

</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="modified">
<parameter_description> a timestamp or -1 to use the current time
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_strrstr_len">
<description>
Searches the string @haystack for the last occurrence
of the string @needle, limiting the length of the search
to @haystack_len. 


</description>
<parameters>
<parameter name="haystack">
<parameter_description> a nul-terminated string.
</parameter_description>
</parameter>
<parameter name="haystack_len">
<parameter_description> the maximum length of @haystack.
</parameter_description>
</parameter>
<parameter name="needle">
<parameter_description> the nul-terminated string to search for.
</parameter_description>
</parameter>
</parameters>
<return> a pointer to the found occurrence, or
%NULL if not found.
</return>
</function>

<function name="g_getenv">
<description>
Return value: the value of the environment variable, or %NULL if

</description>
<parameters>
<parameter name="variable">
<parameter_description> the environment variable to get, in the GLib file name encoding.
</parameter_description>
</parameter>
</parameters>
<return> the value of the environment variable, or %NULL if
the environment variable is not found. The returned string may be
overwritten by the next call to g_getenv(), g_setenv() or
g_unsetenv().
</return>
</function>

<function name="g_main_context_release">
<description>
Releases ownership of a context previously acquired by this thread
with g_main_context_acquire(). If the context was acquired multiple
times, the only release ownership when g_main_context_release()
is called as many times as it was acquired.

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_string_ascii_down">
<description>
Converts all upper case ASCII letters to lower case ASCII letters.


</description>
<parameters>
<parameter name="string">
<parameter_description> a GString
</parameter_description>
</parameter>
</parameters>
<return> passed-in @string pointer, with all the upper case
characters converted to lower case in place, with
semantics that exactly match g_ascii_tolower().
</return>
</function>

<function name="g_queue_peek_nth">
<description>
Return value: The data for the @n&apos;th element of @queue, or %NULL if @n is

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="n">
<parameter_description> the position of the element.
</parameter_description>
</parameter>
</parameters>
<return> The data for the @n&apos;th element of @queue, or %NULL if @n is
off the end of @queue.

Since: 2.4
</return>
</function>

<function name="g_bookmark_file_get_icon">
<description>
Gets the icon of the bookmark for @uri.

In the event the URI cannot be found, %FALSE is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="href">
<parameter_description> return location for the icon&apos;s location or %NULL
</parameter_description>
</parameter>
<parameter name="mime_type">
<parameter_description> return location for the icon&apos;s MIME type or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the icon for the bookmark for the URI was found.
You should free the returned strings.

Since: 2.12
</return>
</function>

<function name="g_io_channel_flush">
<description>
Flushes the write buffer for the GIOChannel.


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store an error of type #GIOChannelError
</parameter_description>
</parameter>
</parameters>
<return> the status of the operation: One of
#G_IO_CHANNEL_NORMAL, #G_IO_CHANNEL_AGAIN, or
#G_IO_CHANNEL_ERROR.
</return>
</function>

<function name="g_str_has_suffix">
<description>
Looks whether the string @str ends with @suffix.


</description>
<parameters>
<parameter name="str">
<parameter_description> a nul-terminated string.
</parameter_description>
</parameter>
<parameter name="suffix">
<parameter_description> the nul-terminated suffix to look for.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @str end with @suffix, %FALSE otherwise.

Since: 2.2
</return>
</function>

<function name="g_bookmark_file_set_mime_type">
<description>
Sets @mime_type as the MIME type of the bookmark for @uri.

If a bookmark for @uri cannot be found then it is created.

Since: 2.12

</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="mime_type">
<parameter_description> a MIME type
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_regex_match">
<description>
Scans for a match in string for the pattern in @regex. 
The @match_options are combined with the match options specified 
when the @regex structure was created, letting you have more 
flexibility in reusing #GRegex structures.

A #GMatchInfo structure, used to get information on the match, 
is stored in @match_info if not %NULL. Note that if @match_info 
is not %NULL then it is created even if the function returns %FALSE, 
i.e. you must free it regardless if regular expression actually matched.

To retrieve all the non-overlapping matches of the pattern in 
string you can use g_match_info_next().

&amp;lt;informalexample&amp;gt;&amp;lt;programlisting&amp;gt;
static void
print_uppercase_words (const gchar *string)
{
/&amp;ast; Print all uppercase-only words. &amp;ast;/
GRegex *regex;
GMatchInfo *match_info;
&amp;nbsp;
regex = g_regex_new (&quot;[A-Z]+&quot;, 0, 0, NULL);
g_regex_match (regex, string, 0, &amp;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);
}
&amp;lt;/programlisting&amp;gt;&amp;lt;/informalexample&amp;gt;


</description>
<parameters>
<parameter name="regex">
<parameter_description> a #GRegex structure from g_regex_new()
</parameter_description>
</parameter>
<parameter name="string">
<parameter_description> the string to scan for matches
</parameter_description>
</parameter>
<parameter name="match_options">
<parameter_description> match options
</parameter_description>
</parameter>
<parameter name="match_info">
<parameter_description> pointer to location where to store the #GMatchInfo, 
or %NULL if you do not need it
</parameter_description>
</parameter>
</parameters>
<return> %TRUE is the string matched, %FALSE otherwise

Since: 2.14
</return>
</function>

<function name="g_rand_set_seed">
<description>
Sets the seed for the random number generator #GRand to @seed.

</description>
<parameters>
<parameter name="rand_">
<parameter_description> a #GRand.
</parameter_description>
</parameter>
<parameter name="seed">
<parameter_description> a value to reinitialize the random number generator.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_key_file_remove_comment">
<description>
Removes a comment above @key from @group_name.
@group_name. If @key is %NULL then @comment will
be written above @group_name.  If both @key
and @group_name are NULL, then @comment will
be written above the first group in the file.

Since: 2.6

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name, or %NULL
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_unichar_istitle">
<description>
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.


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the character is titlecase
</return>
</function>

<function name="g_main_loop_ref">
<description>
Increases the reference count on a #GMainLoop object by one.


</description>
<parameters>
<parameter name="loop">
<parameter_description> a #GMainLoop
</parameter_description>
</parameter>
</parameters>
<return> @loop
</return>
</function>

<function name="g_key_file_get_keys">
<description>
Return value: a newly-allocated %NULL-terminated array of

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> return location for the number of keys returned, or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly-allocated %NULL-terminated array of
strings. Use g_strfreev() to free it.

Since: 2.6
</return>
</function>

<function name="g_bookmark_file_move_item">
<description>
Changes the URI of a bookmark item from @old_uri to @new_uri.  Any
existing bookmark for @new_uri will be overwritten.  If @new_uri is
%NULL, then the bookmark is removed.

In the event the URI cannot be found, %FALSE is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="old_uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="new_uri">
<parameter_description> a valid URI, or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the URI was successfully changed

Since: 2.12
</return>
</function>

<function name="g_open">
<description>
A wrapper for the POSIX open() function. The open() function is
used to convert a pathname into a file descriptor. Note that on
POSIX systems file descriptors are implemented by the operating
system. On Windows, it&apos;s the C library that implements open() and
file descriptors. The actual Windows API for opening files is
something different.

See the C library manual for more details about open().


</description>
<parameters>
<parameter name="filename">
<parameter_description> a pathname in the GLib file name encoding (UTF-8 on Windows)
</parameter_description>
</parameter>
<parameter name="flags">
<parameter_description> as in open()
</parameter_description>
</parameter>
<parameter name="mode">
<parameter_description> as in open()
</parameter_description>
</parameter>
</parameters>
<return> a new file descriptor, or -1 if an error occurred. The
return value can be used exactly like the return value from open().

Since: 2.6
</return>
</function>

<function name="g_unichar_ismark">
<description>
Determines whether a character is a mark (non-spacing mark,
combining mark, or enclosing mark in Unicode speak).
Given some UTF-8 text, obtain a character value
with g_utf8_get_char().

Note: in most cases where isalpha characters are allowed,
ismark characters should be allowed to as they are essential
for writing most European languages as well as many non-Latin
scripts.


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @c is a mark character

Since: 2.14
</return>
</function>

<function name="g_mem_is_system_malloc">
<description>
Checks whether the allocator used by g_malloc() is the system&apos;s
malloc implementation. If it returns %TRUE memory allocated with
malloc() can be used interchangeable with memory allocated using g_malloc(). 
This function is useful for avoiding an extra copy of allocated memory returned
by a non-GLib-based API.

A different allocator can be set using g_mem_set_vtable().


</description>
<parameters>
</parameters>
<return> if %TRUE, malloc() and g_malloc() can be mixed.
</return>
</function>

<function name="g_bookmark_file_get_app_info">
<description>
Gets the registration informations of @app_name for the bookmark for
@uri.  See g_bookmark_file_set_app_info() for more informations about
the returned data.

The string returned in @app_exec must be freed.

In the event the URI cannot be found, %FALSE is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.  In the
event that no application with name @app_name has registered a bookmark
for @uri,  %FALSE is returned and error is set to
#G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting
the command line fails, an error of the #G_SHELL_ERROR domain is
set and %FALSE is returned.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="name">
<parameter_description> an application&apos;s name
</parameter_description>
</parameter>
<parameter name="exec">
<parameter_description> location for the command line of the application, or %NULL
</parameter_description>
</parameter>
<parameter name="count">
<parameter_description> return location for the registration count, or %NULL
</parameter_description>
</parameter>
<parameter name="stamp">
<parameter_description> return location for the last registration time, or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE on success.

Since: 2.12
</return>
</function>

<function name="g_str_has_prefix">
<description>
Looks whether the string @str begins with @prefix.


</description>
<parameters>
<parameter name="str">
<parameter_description> a nul-terminated string.
</parameter_description>
</parameter>
<parameter name="prefix">
<parameter_description> the nul-terminated prefix to look for.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @str begins with @prefix, %FALSE otherwise.

Since: 2.2
</return>
</function>

<function name="g_match_info_fetch_pos">
<description>
Retrieves the position of the @match_num&amp;lt;!-- --&amp;gt;&apos;th capturing 
parentheses. 0 is the full text of the match, 1 is the first 
paren set, 2 the second, and so on.

If @match_num is a valid sub pattern but it didn&apos;t match anything 
(e.g. sub pattern 1, matching &quot;b&quot; against &quot;(a)?b&quot;) then @start_pos 
and @end_pos are set to -1 and %TRUE is returned.

If the match was obtained using the DFA algorithm, that is using
g_regex_match_all() or g_regex_match_all_full(), the retrieved
position is not that of a set of parentheses but that of a matched
substring. Substrings are matched in reverse order of length, so 
0 is the longest match.


</description>
<parameters>
<parameter name="match_info">
<parameter_description> #GMatchInfo structure
</parameter_description>
</parameter>
<parameter name="match_num">
<parameter_description> number of the sub expression
</parameter_description>
</parameter>
<parameter name="start_pos">
<parameter_description> pointer to location where to store the start position
</parameter_description>
</parameter>
<parameter name="end_pos">
<parameter_description> pointer to location where to store the end position
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the position was fetched, %FALSE otherwise. If 
the position cannot be fetched, @start_pos and @end_pos are left 
unchanged

Since: 2.14
</return>
</function>

<function name="g_parse_debug_string">
<description>
Parses a string containing debugging options
into a %guint containing bit flags. This is used 
within GDK and GTK+ to parse the debug options passed on the
command line or through environment variables.


</description>
<parameters>
<parameter name="string">
<parameter_description> a list of debug options separated by colons, spaces, or
commas; or the string &quot;all&quot; to set all flags.
</parameter_description>
</parameter>
<parameter name="keys">
<parameter_description> pointer to an array of #GDebugKey which associate 
strings with bit flags.
</parameter_description>
</parameter>
<parameter name="nkeys">
<parameter_description> the number of #GDebugKey&amp;lt;!-- --&amp;gt;s in the array.
</parameter_description>
</parameter>
</parameters>
<return> the combined set of bit flags.
</return>
</function>

<function name="g_unichar_ispunct">
<description>
Determines whether a character is punctuation or a symbol.
Given some UTF-8 text, obtain a character value with
g_utf8_get_char().


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @c is a punctuation or symbol character
</return>
</function>

<function name="g_unsetenv">
<description>
Removes an environment variable from the environment.

Note that on some systems, when variables are overwritten, the memory 
used for the previous variables and its value isn&apos;t reclaimed.
Furthermore, this function can&apos;t be guaranteed to operate in a 
threadsafe way.

Since: 2.4 

</description>
<parameters>
<parameter name="variable">
<parameter_description> the environment variable to remove, must not contain &apos;=&apos;.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_queue_pop_head_link">
<description>
Removes the first element of the queue.


</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue.
</parameter_description>
</parameter>
</parameters>
<return> the #GList element at the head of the queue, or %NULL if the queue
is empty.
</return>
</function>

<function name="g_utf16_to_utf8">
<description>
Convert a string from UTF-16 to UTF-8. The result will be
terminated with a 0 byte.

Note that the input is expected to be already in native endianness,
an initial byte-order-mark character is not handled specially.
g_convert() can be used to convert a byte buffer of UTF-16 data of 
ambiguous endianess.


</description>
<parameters>
<parameter name="str">
<parameter_description> a UTF-16 encoded string
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the maximum length (number of &amp;lt;type&amp;gt;gunichar2&amp;lt;/type&amp;gt;) of @str to use. 
If @len &amp;lt; 0, then the string is terminated with a 0 character.
</parameter_description>
</parameter>
<parameter name="items_read">
<parameter_description> location to store number of words read, or %NULL.
If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
returned in case @str contains a trailing partial
character. If an error occurs then the index of the
invalid input is stored here.
</parameter_description>
</parameter>
<parameter name="items_written">
<parameter_description> location to store number of bytes written, or %NULL.
The value stored here does not include the trailing
0 byte.
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store the error occuring, or %NULL to ignore
errors. Any of the errors in #GConvertError other than
%G_CONVERT_ERROR_NO_CONVERSION may occur.
</parameter_description>
</parameter>
</parameters>
<return> a pointer to a newly allocated UTF-8 string.
This value must be freed with g_free(). If an
error occurs, %NULL will be returned and
@error set.
</return>
</function>

<function name="g_vprintf">
<description>
An implementation of the standard vprintf() function which supports 
positional parameters, as specified in the Single Unix Specification.


</description>
<parameters>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice 
&amp;lt;link linkend=&quot;string-precision&quot;&amp;gt;string precision pitfalls&amp;lt;/link&amp;gt;.
</parameter_description>
</parameter>
<parameter name="args">
<parameter_description> the list of arguments to insert in the output.
</parameter_description>
</parameter>
</parameters>
<return> the number of characters printed.

Since: 2.2
</return>
</function>

<function name="g_bookmark_file_set_icon">
<description>
Sets the icon for the bookmark for @uri.  If @href is %NULL, unsets
the currently set icon.

If no bookmark for @uri is found it is created.

Since: 2.12

</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="href">
<parameter_description> the URI of the icon for the bookmark, or %NULL
</parameter_description>
</parameter>
<parameter name="mime_type">
<parameter_description> the MIME type of the icon for the bookmark
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_bookmark_file_has_group">
<description>
Checks whether @group appears in the list of groups to which
the bookmark for @uri belongs to.

In the event the URI cannot be found, %FALSE is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="group">
<parameter_description> the group name to be searched
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @group was found.

Since: 2.12
</return>
</function>

<function name="g_rand_new">
<description>
Creates a new random number generator initialized with a seed taken
either from &amp;lt;filename&amp;gt;/dev/urandom&amp;lt;/filename&amp;gt; (if existing) or from 
the current time (as a fallback).


</description>
<parameters>
</parameters>
<return> the new #GRand.
</return>
</function>

<function name="g_hash_table_find">
<description>
Calls the given function for key/value pairs in the #GHashTable until 
@predicate returns %TRUE.  The function is passed the key and value of 
each pair, and the given @user_data parameter. The hash table may not
be modified while iterating over it (you can&apos;t add/remove items).

Note, that hash tables are really only optimized for forward lookups,
i.e. g_hash_table_lookup().
So code that frequently issues g_hash_table_find() or
g_hash_table_foreach() (e.g. in the order of once per every entry in a
hash table) should probably be reworked to use additional or different
data structures for reverse lookups (keep in mind that an O(n) find/foreach
operation issued for all n values in a hash table ends up needing O(n*n)
operations).


</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a #GHashTable.
</parameter_description>
</parameter>
<parameter name="predicate">
<parameter_description>  function to test the key/value pairs for a certain property.
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description>  user data to pass to the function.
</parameter_description>
</parameter>
</parameters>
<return> The value of the first key/value pair is returned, for which
func evaluates to %TRUE. If no pair with the requested property is found,
%NULL is returned.

Since: 2.4
</return>
</function>

<function name="g_sequence_get">
<description>
Return value: the data that @iter points to

</description>
<parameters>
<parameter name="iter">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
</parameters>
<return> the data that @iter points to

Since: 2.14
</return>
</function>

<function name="g_sequence_insert_sorted">
<description>
Inserts @data into @sequence using @func to determine the new position.
The sequence must already be sorted according to @cmp_func; otherwise the
new position of @data is undefined.


</description>
<parameters>
<parameter name="seq">
<parameter_description> a #GSequence
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> the data to insert
</parameter_description>
</parameter>
<parameter name="cmp_func">
<parameter_description> the #GCompareDataFunc used to compare items in the sequence. It
is called with two items of the @seq and @user_data. It should
return 0 if the items are equal, a negative value if the first
item comes before the second, and a positive value if the second
item comes before the first.
</parameter_description>
</parameter>
<parameter name="cmp_data">
<parameter_description> user data passed to @cmp_func.
</parameter_description>
</parameter>
</parameters>
<return> a #GSequenceIter pointing to the new item.

Since: 2.14
</return>
</function>

<function name="g_get_user_cache_dir">
<description>
Return value: a string owned by GLib that must not be modified 

</description>
<parameters>
</parameters>
<return> a string owned by GLib that must not be modified 
or freed.
Since: 2.6
</return>
</function>

<function name="g_markup_parse_context_get_position">
<description>
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;


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMarkupParseContext
</parameter_description>
</parameter>
<parameter name="line_number">
<parameter_description> return location for a line number, or %NULL
</parameter_description>
</parameter>
<parameter name="char_number">
<parameter_description> return location for a char-on-line number, or %NULL
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_sequence_iter_next">
<description>
Return value: a #GSequenceIter pointing to the next position after @iter.

</description>
<parameters>
<parameter name="iter">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
</parameters>
<return> a #GSequenceIter pointing to the next position after @iter.

Since: 2.14
</return>
</function>

<function name="g_io_channel_new_file">
<description>
Open a file @filename as a #GIOChannel using mode @mode. This
channel will be closed when the last reference to it is dropped,
so there is no need to call g_io_channel_close() (though doing
so will not cause problems, as long as no attempt is made to
access the channel after it is closed).


</description>
<parameters>
<parameter name="filename">
<parameter_description> A string containing the name of a file.
</parameter_description>
</parameter>
<parameter name="mode">
<parameter_description> One of &quot;r&quot;, &quot;w&quot;, &quot;a&quot;, &quot;r+&quot;, &quot;w+&quot;, &quot;a+&quot;. These have
the same meaning as in fopen().
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> A location to return an error of type %G_FILE_ERROR.
</parameter_description>
</parameter>
</parameters>
<return> A #GIOChannel on success, %NULL on failure.
</return>
</function>

<function name="g_thread_pool_set_max_idle_time">
<description>
This function will set the maximum @interval that a thread waiting
in the pool for new tasks can be idle for before being
stopped. This function is similar to calling
g_thread_pool_stop_unused_threads() on a regular timeout, except,
this is done on a per thread basis.    

By setting @interval to 0, idle threads will not be stopped.

This function makes use of g_async_queue_timed_pop () using
@interval.

Since: 2.10

</description>
<parameters>
<parameter name="interval">
<parameter_description> the maximum @interval (1/1000ths of a second) a thread
can be idle. 
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_int_hash">
<description>
Converts a pointer to a #gint to a hash value.
It can be passed to g_hash_table_new() as the @hash_func parameter, 
when using pointers to integers values as keys in a #GHashTable.


</description>
<parameters>
<parameter name="v">
<parameter_description> a pointer to a #gint key
</parameter_description>
</parameter>
</parameters>
<return> a hash value corresponding to the key.
</return>
</function>

<function name="g_main_loop_new">
<description>
Creates a new #GMainLoop structure.


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext  (if %NULL, the default context will be used).
</parameter_description>
</parameter>
<parameter name="is_running">
<parameter_description> set to %TRUE to indicate that the loop is running. This
is not very important since calling g_main_loop_run() will set this to
%TRUE anyway.
</parameter_description>
</parameter>
</parameters>
<return> a new #GMainLoop.
</return>
</function>

<function name="g_source_get_can_recurse">
<description>
Checks whether a source is allowed to be called recursively.
see g_source_set_can_recurse().


</description>
<parameters>
<parameter name="source">
<parameter_description> a #GSource
</parameter_description>
</parameter>
</parameters>
<return> whether recursion is allowed.
</return>
</function>

<function name="g_sequence_iter_is_begin">
<description>
Return value: whether @iter is the begin iterator

</description>
<parameters>
<parameter name="iter">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
</parameters>
<return> whether @iter is the begin iterator

Since: 2.14
</return>
</function>

<function name="g_string_printf">
<description>
Writes a formatted string into a #GString.
This is similar to the standard sprintf() function,
except that the #GString buffer automatically expands 
to contain the results. The previous contents of the 
#GString are destroyed.

</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="format">
<parameter_description> the string format. See the printf() documentation
</parameter_description>
</parameter>
<parameter name="Varargs">
<parameter_description> the parameters to insert into the format string
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_utf8_strchr">
<description>
Finds the leftmost occurrence of the given Unicode character
in a UTF-8 encoded string, while limiting the search to @len bytes.
If @len is -1, allow unbounded search.


</description>
<parameters>
<parameter name="p">
<parameter_description> a nul-terminated UTF-8 encoded string
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the maximum length of @p
</parameter_description>
</parameter>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %NULL if the string does not contain the character, 
otherwise, a pointer to the start of the leftmost occurrence of 
the character in the string.
</return>
</function>

<function name="g_win32_get_package_installation_subdirectory">
<description>
Returns: a string containing the complete path to @subdir inside

</description>
<parameters>
<parameter name="package">
<parameter_description> An identifier for a software package, in UTF-8, or %NULL
</parameter_description>
</parameter>
<parameter name="dll_name">
<parameter_description> The name of a DLL that a package provides, in UTF-8, or %NULL
</parameter_description>
</parameter>
<parameter name="subdir">
<parameter_description> A subdirectory of the package installation directory, also in UTF-8
</parameter_description>
</parameter>
</parameters>
<return> a string containing the complete path to @subdir inside
the installation directory of @package. The returned string is in
the GLib file name encoding, i.e. UTF-8 on Windows. The return
value should be freed with g_free() when no longer needed.
</return>
</function>

<function name="g_sequence_search">
<description>
Return value: an #GSequenceIter pointing to the position where @data

</description>
<parameters>
<parameter name="seq">
<parameter_description> a #GSequence
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> data for the new item
</parameter_description>
</parameter>
<parameter name="cmp_func">
<parameter_description> the #GCompareDataFunc used to compare items in the sequence. It
is called with two items of the @seq and @user_data. It should
return 0 if the items are equal, a negative value if the first
item comes before the second, and a positive value if the second
item comes before the first.
</parameter_description>
</parameter>
<parameter name="cmp_data">
<parameter_description> user data passed to @cmp_func.
</parameter_description>
</parameter>
</parameters>
<return> an #GSequenceIter pointing to the position where @data
would have been inserted according to @cmp_func and @cmp_data.

Since: 2.14
</return>
</function>

<function name="g_key_file_get_string_list">
<description>
Return value: a %NULL-terminated string array or %NULL if the specified 

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> return location for the number of returned strings, or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a %NULL-terminated string array or %NULL if the specified 
key cannot be found. The array should be freed with g_strfreev().

Since: 2.6
</return>
</function>

<function name="g_regex_unref">
<description>
Decreases reference count of @regex by 1. When reference count drops
to zero, it frees all the memory associated with the regex structure.

Since: 2.14

</description>
<parameters>
<parameter name="regex">
<parameter_description> a #GRegex
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_tree_height">
<description>
Gets the height of a #GTree.

If the #GTree contains no nodes, the height is 0.
If the #GTree contains only one root node the height is 1.
If the root node has children the height is 2, etc.


</description>
<parameters>
<parameter name="tree">
<parameter_description> a #GTree.
</parameter_description>
</parameter>
</parameters>
<return> the height of the #GTree.
</return>
</function>

<function name="g_shell_parse_argv">
<description>
Parses a command line into an argument vector, in much the same way
the shell would, but without many of the expansions the shell would
perform (variable expansion, globs, operators, filename expansion,
etc. are not supported). The results are defined to be the same as
those you would get from a UNIX98 /bin/sh, as long as the input
contains none of the unsupported shell expansions. If the input
does contain such expansions, they are passed through
literally. Possible errors are those from the #G_SHELL_ERROR
domain. Free the returned vector with g_strfreev().


</description>
<parameters>
<parameter name="command_line">
<parameter_description> command line to parse
</parameter_description>
</parameter>
<parameter name="argcp">
<parameter_description> return location for number of args
</parameter_description>
</parameter>
<parameter name="argvp">
<parameter_description> return location for array of args
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for error
</parameter_description>
</parameter>
</parameters>
<return> %TRUE on success, %FALSE if error set
</return>
</function>

<function name="g_get_user_name">
<description>
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.


</description>
<parameters>
</parameters>
<return> the user name of the current user.
</return>
</function>

<function name="g_match_info_is_partial_match">
<description>
Usually if the string passed to g_regex_match*() matches as far as
it goes, but is too short to match the entire pattern, %FALSE is
returned. There are circumstances where it might be helpful to
distinguish this case from other cases in which there is no match.

Consider, for example, an application where a human is required to
type in data for a field with specific formatting requirements. An
example might be a date in the form ddmmmyy, defined by the pattern
&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.

GRegex supports the concept of partial matching by means of the
#G_REGEX_MATCH_PARTIAL flag. When this is set the return code for
g_regex_match() or g_regex_match_full() is, as usual, %TRUE
for a complete match, %FALSE otherwise. But, when these functions
return %FALSE, you can check if the match was partial calling
g_match_info_is_partial_match().

When using partial matching you cannot use g_match_info_fetch*().

Because of the way certain internal optimizations are implemented 
the partial matching algorithm cannot be used with all patterns. 
So repeated single characters such as &quot;a{2,4}&quot; and repeated single 
meta-sequences such as &quot;\d+&quot; are not permitted if the maximum number 
of occurrences is greater than one. Optional items such as &quot;\d?&quot; 
(where the maximum is one) are permitted. Quantifiers with any values 
are permitted after parentheses, so the invalid examples above can be 
coded thus &quot;(a){2,4}&quot; and &quot;(\d)+&quot;. If #G_REGEX_MATCH_PARTIAL is set 
for a pattern that does not conform to the restrictions, matching 
functions return an error.


</description>
<parameters>
<parameter name="match_info">
<parameter_description> a #GMatchInfo structure
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the match was partial, %FALSE otherwise

Since: 2.14
</return>
</function>

<function name="g_main_loop_quit">
<description>
Stops a #GMainLoop from running. Any calls to g_main_loop_run()
for the loop will return.

</description>
<parameters>
<parameter name="loop">
<parameter_description> a #GMainLoop
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_ascii_strtod">
<description>
Converts a string to a #gdouble value.
This function behaves like the standard strtod() function
does in the C locale. It does this without actually
changing the current locale, since that would not be
thread-safe.

This function is typically used when reading configuration
files or other non-user input that should be locale independent.
To handle input from the user you should normally use the
locale-sensitive system strtod() function.

To convert from a #gdouble to a string in a locale-insensitive
way, use g_ascii_dtostr().

If the correct value would cause overflow, plus or minus %HUGE_VAL
is returned (according to the sign of the value), and %ERANGE is
stored in %errno. If the correct value would cause underflow,
zero is returned and %ERANGE is stored in %errno.

This function resets %errno before calling strtod() so that
you can reliably detect overflow and underflow.


</description>
<parameters>
<parameter name="nptr">
<parameter_description>    the string to convert to a numeric value.
</parameter_description>
</parameter>
<parameter name="endptr">
<parameter_description>  if non-%NULL, it returns the character after
the last character used in the conversion.
</parameter_description>
</parameter>
</parameters>
<return> the #gdouble value.
</return>
</function>

<function name="g_queue_peek_nth_link">
<description>
Return value: The link at the @n&apos;th position, or %NULL if @n is off the

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="n">
<parameter_description> the position of the link
</parameter_description>
</parameter>
</parameters>
<return> The link at the @n&apos;th position, or %NULL if @n is off the
end of the list

Since: 2.4
</return>
</function>

<function name="g_unichar_to_utf8">
<description>
Converts a single character to UTF-8.


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character code
</parameter_description>
</parameter>
<parameter name="outbuf">
<parameter_description> output buffer, must have at least 6 bytes of space.
If %NULL, the length will be computed and returned
and nothing will be written to @outbuf.
</parameter_description>
</parameter>
</parameters>
<return> number of bytes written
</return>
</function>

<function name="g_match_info_fetch_all">
<description>
Bundles up pointers to each of the matching substrings from a match
and stores them in an array of gchar pointers. The first element in
the returned array is the match number 0, i.e. the entire matched
text.

If a sub pattern didn&apos;t match anything (e.g. sub pattern 1, matching
&quot;b&quot; against &quot;(a)?b&quot;) then an empty string is inserted.

If the last match was obtained using the DFA algorithm, that is using
g_regex_match_all() or g_regex_match_all_full(), the retrieved
strings are not that matched by sets of parentheses but that of the
matched substring. Substrings are matched in reverse order of length,
so the first one is the longest match.

The strings are fetched from the string passed to the match function,
so you cannot call this function after freeing the string.


</description>
<parameters>
<parameter name="match_info">
<parameter_description> a #GMatchInfo structure
</parameter_description>
</parameter>
</parameters>
<return> a %NULL-terminated array of gchar * pointers. It must be 
freed using g_strfreev(). If the previous match failed %NULL is
returned

Since: 2.14
</return>
</function>

<function name="g_iconv_close">
<description>
Same as the standard UNIX routine iconv_close(), but
may be implemented via libiconv on UNIX flavors that lack
a native implementation. Should be called to clean up
the conversion descriptor from g_iconv_open() when
you are done converting things.

GLib provides g_convert() and g_locale_to_utf8() which are likely
more convenient than the raw iconv wrappers.


</description>
<parameters>
<parameter name="converter">
<parameter_description> a conversion descriptor from g_iconv_open()
</parameter_description>
</parameter>
</parameters>
<return> -1 on error, 0 on success
</return>
</function>

<function name="g_async_queue_ref_unlocked">
<description>
Increases the reference count of the asynchronous @queue by 1.

@Deprecated: Since 2.8, reference counting is done atomically
so g_async_queue_ref() can be used regardless of the @queue&apos;s
lock.

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_utf8_casefold">
<description>
Converts a string into a form that is independent of case. The
result will not correspond to any particular case, but can be
compared for equality or ordered with the results of calling
g_utf8_casefold() on other strings.

Note that calling g_utf8_casefold() followed by g_utf8_collate() is
only an approximation to the correct linguistic case insensitive
ordering, though it is a fairly good one. Getting this exactly
right would require a more sophisticated collation function that
takes case sensitivity into account. GLib does not currently
provide such a function.


</description>
<parameters>
<parameter name="str">
<parameter_description> a UTF-8 encoded string
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> length of @str, in bytes, or -1 if @str is nul-terminated.
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string, that is a
case independent form of @str.
</return>
</function>

<function name="g_ascii_strcasecmp">
<description>
Compare two strings, ignoring the case of ASCII characters.

Unlike the BSD strcasecmp() function, this only recognizes standard
ASCII letters and ignores the locale, treating all non-ASCII
bytes as if they are not letters.

This function should be used only on strings that are known to be
in encodings where the bytes corresponding to ASCII letters always
represent themselves. This includes UTF-8 and the ISO-8859-*
charsets, but not for instance double-byte encodings like the
Windows Codepage 932, where the trailing bytes of double-byte
characters include all ASCII letters. If you compare two CP932
strings using this function, you will get false matches.


</description>
<parameters>
<parameter name="s1">
<parameter_description> string to compare with @s2.
</parameter_description>
</parameter>
<parameter name="s2">
<parameter_description> string to compare with @s1.
</parameter_description>
</parameter>
</parameters>
<return> 0 if the strings match, a negative value if @s1 &amp;lt; @s2, 
or a positive value if @s1 &amp;gt; @s2.
</return>
</function>

<function name="g_utf8_get_char">
<description>
Converts a sequence of bytes encoded as UTF-8 to a Unicode character.
If @p does not point to a valid UTF-8 encoded character, results are
undefined. If you are not sure that the bytes are complete
valid Unicode characters, you should use g_utf8_get_char_validated()
instead.


</description>
<parameters>
<parameter name="p">
<parameter_description> a pointer to Unicode character encoded as UTF-8
</parameter_description>
</parameter>
</parameters>
<return> the resulting character
</return>
</function>

<function name="g_unichar_isgraph">
<description>
Determines whether a character is printable and not a space
(returns %FALSE for control characters, format characters, and
spaces). g_unichar_isprint() is similar, but returns %TRUE for
spaces. Given some UTF-8 text, obtain a character value with
g_utf8_get_char().


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @c is printable unless it&apos;s a space
</return>
</function>

<function name="g_main_context_default">
<description>
Return value: the default main context.

</description>
<parameters>
</parameters>
<return> the default main context.
</return>
</function>

<function name="g_string_chunk_free">
<description>
Frees all memory allocated by the #GStringChunk.
After calling g_string_chunk_free() it is not safe to
access any of the strings which were contained within it.

</description>
<parameters>
<parameter name="chunk">
<parameter_description> a #GStringChunk 
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_ascii_toupper">
<description>
Convert a character to ASCII upper case.

Unlike the standard C library toupper() function, this only
recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are upper case
letters in a particular character set. Also unlike the standard
library function, this takes and returns a char, not an int, so
don&apos;t call it on %EOF but no need to worry about casting to #guchar
before passing a possibly non-ASCII character in.


</description>
<parameters>
<parameter name="c">
<parameter_description> any character.
</parameter_description>
</parameter>
</parameters>
<return> the result of converting @c to upper case.
If @c is not an ASCII lower case letter,
@c is returned unchanged.
</return>
</function>

<function name="g_shell_quote">
<description>
Quotes a string so that the shell (/bin/sh) will interpret the
quoted string to mean @unquoted_string. If you pass a filename to
the shell, for example, you should first quote it with this
function.  The return value must be freed with g_free(). The
quoting style used is undefined (single or double quotes may be
used).


</description>
<parameters>
<parameter name="unquoted_string">
<parameter_description> a literal string
</parameter_description>
</parameter>
</parameters>
<return> quoted string
</return>
</function>

<function name="g_chdir">
<description>
A wrapper for the POSIX chdir() function. The function changes the
current directory of the process to @path.

See your C library manual for more details about chdir().


</description>
<parameters>
<parameter name="path">
<parameter_description> a pathname in the GLib file name encoding (UTF-8 on Windows)
</parameter_description>
</parameter>
</parameters>
<return> 0 on success, -1 if an error occurred.

Since: 2.8
</return>
</function>

<function name="g_get_current_dir">
<description>
Gets the current directory.
The returned string should be freed when no longer needed. The encoding 
of the returned string is system defined. On Windows, it is always UTF-8.


</description>
<parameters>
</parameters>
<return> the current directory.
</return>
</function>

<function name="g_source_remove_by_funcs_user_data">
<description>
Removes a source from the default main loop context given the
source functions and user data. If multiple sources exist with the
same source functions and user data, only one will be destroyed.


</description>
<parameters>
<parameter name="funcs">
<parameter_description> The @source_funcs passed to g_source_new()
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> the user data for the callback
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if a source was found and removed. 
</return>
</function>

<function name="g_string_set_size">
<description>
Sets the length of a #GString. If the length is less than
the current length, the string will be truncated. If the
length is greater than the current length, the contents
of the newly added area are undefined. (However, as
always, string-&amp;gt;str[string-&amp;gt;len] will be a nul byte.) 


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the new length
</parameter_description>
</parameter>
</parameters>
<return> @string
</return>
</function>

<function name="g_bookmark_file_remove_group">
<description>
Removes @group from the list of groups to which the bookmark
for @uri belongs to.

In the event the URI cannot be found, %FALSE is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
In the event no group was defined, %FALSE is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="group">
<parameter_description> the group name to be removed
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @group was successfully removed.

Since: 2.12
</return>
</function>

<function name="g_bookmark_file_set_app_info">
<description>
Sets the meta-data of application @name inside the list of
applications that have registered a bookmark for @uri inside
@bookmark.

You should rarely use this function; use g_bookmark_file_add_application()
and g_bookmark_file_remove_application() instead.

@name can be any UTF-8 encoded string used to identify an
application.
@exec can have one of these two modifiers: &quot;%f&quot;, which will
be expanded as the local file name retrieved from the bookmark&apos;s
URI; &quot;%u&quot;, which will be expanded as the bookmark&apos;s URI.
The expansion is done automatically when retrieving the stored
command line using the g_bookmark_file_get_app_info() function.
@count is the number of times the application has registered the
bookmark; if is &amp;lt; 0, the current registration count will be increased
by one, if is 0, the application with @name will be removed from
the list of registered applications.
@stamp is the Unix time of the last registration; if it is -1, the
current time will be used.

If you try to remove an application by setting its registration count to
zero, and no bookmark for @uri is found, %FALSE is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; similarly,
in the event that no application @name has registered a bookmark
for @uri,  %FALSE is returned and error is set to
#G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED.  Otherwise, if no bookmark
for @uri is found, one is created.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="name">
<parameter_description> an application&apos;s name
</parameter_description>
</parameter>
<parameter name="exec">
<parameter_description> an application&apos;s command line
</parameter_description>
</parameter>
<parameter name="count">
<parameter_description> the number of registrations done for this application
</parameter_description>
</parameter>
<parameter name="stamp">
<parameter_description> the time of the last registration for this application
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the application&apos;s meta-data was successfully
changed.

Since: 2.12
</return>
</function>

<function name="g_strsplit_set">
<description>
Splits @string into a number of tokens not containing any of the characters
in @delimiter. A token is the (possibly empty) longest string that does not
contain any of the characters in @delimiters. If @max_tokens is reached, the
remainder is appended to the last token.

For example the result of g_strsplit_set (&quot;abc:def/ghi&quot;, &quot;:/&quot;, -1) is a
%NULL-terminated vector containing the three strings &quot;abc&quot;, &quot;def&quot;, 
and &quot;ghi&quot;.

The result if g_strsplit_set (&quot;:def/ghi:&quot;, &quot;:/&quot;, -1) is a %NULL-terminated
vector containing the four strings &quot;&quot;, &quot;def&quot;, &quot;ghi&quot;, and &quot;&quot;.

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 a empty vector is typically
more useful than consistent handling of empty elements. If you do need
to represent empty elements, you&apos;ll need to check for the empty string
before calling g_strsplit_set().

Note that this function works on bytes not characters, so it can&apos;t be used 
to delimit UTF-8 strings for anything but ASCII characters.


</description>
<parameters>
<parameter name="string">
<parameter_description> The string to be tokenized
</parameter_description>
</parameter>
<parameter name="delimiters">
<parameter_description> A nul-terminated string containing bytes that are used
to split the string.
</parameter_description>
</parameter>
<parameter name="max_tokens">
<parameter_description> The maximum number of tokens to split @string into. 
If this is less than 1, the string is split completely
</parameter_description>
</parameter>
</parameters>
<return> a newly-allocated %NULL-terminated array of strings. Use 
g_strfreev() to free it.

Since: 2.4
</return>
</function>

<function name="g_main_context_find_source_by_id">
<description>
Finds a #GSource given a pair of context and ID.


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext (if %NULL, the default context will be used)
</parameter_description>
</parameter>
<parameter name="source_id">
<parameter_description> the source ID, as returned by g_source_get_id(). 
</parameter_description>
</parameter>
</parameters>
<return> the #GSource if found, otherwise, %NULL
</return>
</function>

<function name="g_key_file_to_data">
<description>
This function outputs @key_file as a string.  


</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> return location for the length of the 
returned string, or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string holding
the contents of the #GKeyFile 

Since: 2.6
</return>
</function>

<function name="g_match_info_matches">
<description>
Returns: %TRUE if the previous match operation succeeded, 

</description>
<parameters>
<parameter name="match_info">
<parameter_description> a #GMatchInfo structure
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the previous match operation succeeded, 
%FALSE otherwise

Since: 2.14
</return>
</function>

<function name="g_main_context_prepare">
<description>
Prepares to poll sources within a main loop. The resulting information
for polling is determined by calling g_main_context_query ().


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext
</parameter_description>
</parameter>
<parameter name="priority">
<parameter_description> location to store priority of highest priority
source already ready.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if some source is ready to be dispatched
prior to polling.
</return>
</function>

<function name="g_key_file_load_from_dirs">
<description>
This function looks for a key file named @file in the paths
specified in @search_dirs, loads the file into @key_file and
Return value: %TRUE if a key file could be loaded, %FALSE othewise

</description>
<parameters>
<parameter name="key_file">
<parameter_description> an empty #GKeyFile struct
</parameter_description>
</parameter>
<parameter name="file">
<parameter_description> a relative path to a filename to open and parse
</parameter_description>
</parameter>
<parameter name="search_dirs">
<parameter_description> %NULL-terminated array of directories to search
</parameter_description>
</parameter>
<parameter name="full_path">
<parameter_description> return location for a string containing the full path
of the file, or %NULL
</parameter_description>
</parameter>
<parameter name="flags">
<parameter_description> flags from #GKeyFileFlags
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if a key file could be loaded, %FALSE othewise

Since: 2.14
</return>
</function>

<function name="g_hash_table_get_values">
<description>
Retrieves every value inside @hash_table. The returned data is
valid until @hash_table is modified.


</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a #GHashTable
</parameter_description>
</parameter>
</parameters>
<return> a #GList containing all the values inside the hash
table. The content of the list is owned by the hash table and
should not be modified or freed. Use g_list_free() when done
using the list.

Since: 2.14
</return>
</function>

<function name="g_option_group_set_translate_func">
<description>
Sets the function which is used to translate user-visible
strings, for &amp;lt;option&amp;gt;--help&amp;lt;/option&amp;gt; output. Different
groups can use different #GTranslateFunc&amp;lt;!-- --&amp;gt;s. If @func
is %NULL, strings are not translated.

If you are using gettext(), you only need to set the translation
domain, see g_option_group_set_translation_domain().

Since: 2.6

</description>
<parameters>
<parameter name="group">
<parameter_description> a #GOptionGroup
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> the #GTranslateFunc, or %NULL 
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> user data to pass to @func, or %NULL
</parameter_description>
</parameter>
<parameter name="destroy_notify">
<parameter_description> a function which gets called to free @data, or %NULL
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_strnfill">
<description>
Creates a new string @length bytes long filled with @fill_char.
The returned string should be freed when no longer needed.


</description>
<parameters>
<parameter name="length">
<parameter_description> the length of the new string
</parameter_description>
</parameter>
<parameter name="fill_char">
<parameter_description> the byte to fill the string with
</parameter_description>
</parameter>
</parameters>
<return> a newly-allocated string filled the @fill_char
</return>
</function>

<function name="g_key_file_set_integer">
<description>
Associates a new integer value with @key under @group_name.
If @key cannot be found then it is created.

Since: 2.6

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="value">
<parameter_description> an integer value
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_get_codeset">
<description>
Get the codeset for the current locale.


</description>
<parameters>
</parameters>
<return> a newly allocated string containing the name
of the codeset. This string must be freed with g_free().
</return>
</function>

<function name="g_vasprintf">
<description>
An implementation of the GNU vasprintf() function which supports 
positional parameters, as specified in the Single Unix Specification.
This function is similar to g_vsprintf(), except that it allocates a 
string to hold the output, instead of putting the output in a buffer 
you allocate in advance.


</description>
<parameters>
<parameter name="string">
<parameter_description> the return location for the newly-allocated string.
</parameter_description>
</parameter>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice
&amp;lt;link linkend=&quot;string-precision&quot;&amp;gt;string precision pitfalls&amp;lt;/link&amp;gt;.
</parameter_description>
</parameter>
<parameter name="args">
<parameter_description> the list of arguments to insert in the output.
</parameter_description>
</parameter>
</parameters>
<return> the number of characters printed.

Since: 2.4
</return>
</function>

<function name="g_get_language_names">
<description>
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;.

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;.

This function consults the environment variables &amp;lt;envar&amp;gt;LANGUAGE&amp;lt;/envar&amp;gt;, 
&amp;lt;envar&amp;gt;LC_ALL&amp;lt;/envar&amp;gt;, &amp;lt;envar&amp;gt;LC_MESSAGES&amp;lt;/envar&amp;gt; and &amp;lt;envar&amp;gt;LANG&amp;lt;/envar&amp;gt; 
to find the list of locales specified by the user.


</description>
<parameters>
</parameters>
<return> a %NULL-terminated array of strings owned by GLib 
that must not be modified or freed.

Since: 2.6
</return>
</function>

<function name="g_hash_table_foreach_steal">
<description>
Calls the given function for each key/value pair in the #GHashTable.
If the function returns %TRUE, then the key/value pair is removed from the
#GHashTable, but no key or value destroy functions are called.


</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a #GHashTable.
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> the function to call for each key/value pair.
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data to pass to the function.
</parameter_description>
</parameter>
</parameters>
<return> the number of key/value pairs removed.
</return>
</function>

<function name="g_key_file_get_comment">
<description>
Retrieves a comment above @key from @group_name.
@group_name. If @key is %NULL then @comment will
be read from above @group_name.  If both @key
and @group_name are NULL, then @comment will
be read from above the first group in the file.


</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name, or %NULL
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError
</parameter_description>
</parameter>
</parameters>
<return> a comment that should be freed with g_free()

Since: 2.6
</return>
</function>

<function name="g_thread_pool_set_sort_function">
<description>
Sets the function used to sort the list of tasks. This allows the
tasks to be processed by a priority determined by @func, and not
just in the order in which they were added to the pool.

Note, if the maximum number of threads is more than 1, the order
that threads are executed can not be guranteed 100%. Threads are
scheduled by the operating system and are executed at random. It
cannot be assumed that threads are executed in the order they are
created. 

Since: 2.10

</description>
<parameters>
<parameter name="pool">
<parameter_description> a #GThreadPool
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> the #GCompareDataFunc used to sort the list of tasks. 
This function is passed two tasks. It should return
0 if the order in which they are handled does not matter, 
a negative value if the first task should be processed before
the second or a positive value if the second task should be 
processed first.
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data passed to @func.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_creat">
<description>
A wrapper for the POSIX creat() function. The creat() function is
used to convert a pathname into a file descriptor, creating a file
if necessar. Note that on POSIX systems file descriptors are
implemented by the operating system. On Windows, it&apos;s the C library
that implements creat() and file descriptors. The actual Windows
API for opening files is something different.

See the C library manual for more details about creat().


</description>
<parameters>
<parameter name="filename">
<parameter_description> a pathname in the GLib file name encoding (UTF-8 on Windows)
</parameter_description>
</parameter>
<parameter name="mode">
<parameter_description> as in creat()
</parameter_description>
</parameter>
</parameters>
<return> a new file descriptor, or -1 if an error occurred. The
return value can be used exactly like the return value from creat().

Since: 2.8
</return>
</function>

<function name="g_win32_error_message">
<description>
Translate a Win32 error code (as returned by GetLastError()) into
the corresponding message. The message is either language neutral,
or in the thread&apos;s language, or the user&apos;s language, the system&apos;s
language, or US English (see docs for FormatMessage()). The
returned string is in UTF-8. It should be deallocated with
g_free().


</description>
<parameters>
<parameter name="error">
<parameter_description> error code.
</parameter_description>
</parameter>
</parameters>
<return> newly-allocated error message
</return>
</function>

<function name="g_utf16_to_ucs4">
<description>
Convert a string from UTF-16 to UCS-4. The result will be
terminated with a 0 character.


</description>
<parameters>
<parameter name="str">
<parameter_description> a UTF-16 encoded string
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the maximum length (number of &amp;lt;type&amp;gt;gunichar2&amp;lt;/type&amp;gt;) of @str to use. 
If @len &amp;lt; 0, then the string is terminated with a 0 character.
</parameter_description>
</parameter>
<parameter name="items_read">
<parameter_description> location to store number of words read, or %NULL.
If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
returned in case @str contains a trailing partial
character. If an error occurs then the index of the
invalid input is stored here.
</parameter_description>
</parameter>
<parameter name="items_written">
<parameter_description> location to store number of characters written, or %NULL.
The value stored here does not include the trailing
0 character.
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store the error occuring, or %NULL to ignore
errors. Any of the errors in #GConvertError other than
%G_CONVERT_ERROR_NO_CONVERSION may occur.
</parameter_description>
</parameter>
</parameters>
<return> a pointer to a newly allocated UCS-4 string.
This value must be freed with g_free(). If an
error occurs, %NULL will be returned and
@error set.
</return>
</function>

<function name="g_tree_insert">
<description>
Inserts a key/value pair into a #GTree. If the given key already exists 
in the #GTree its corresponding value is set to the new value. If you 
supplied a value_destroy_func when creating the #GTree, the old value is 
freed using that function. If you supplied a @key_destroy_func when 
creating the #GTree, the passed key is freed using that function.

The tree is automatically &apos;balanced&apos; as new key/value pairs are added,
so that the distance from the root to every leaf is as small as possible.

</description>
<parameters>
<parameter name="tree">
<parameter_description> a #GTree.
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> the key to insert.
</parameter_description>
</parameter>
<parameter name="value">
<parameter_description> the value corresponding to the key.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_base64_encode_close">
<description>
Flush the status from a sequence of calls to g_base64_encode_step().


</description>
<parameters>
<parameter name="break_lines">
<parameter_description> whether to break long lines
</parameter_description>
</parameter>
<parameter name="out">
<parameter_description> pointer to destination buffer
</parameter_description>
</parameter>
<parameter name="state">
<parameter_description> Saved state from g_base64_encode_step()
</parameter_description>
</parameter>
<parameter name="save">
<parameter_description> Saved state from g_base64_encode_step()
</parameter_description>
</parameter>
</parameters>
<return> The number of bytes of output that was written

Since: 2.12
</return>
</function>

<function name="g_async_queue_unlock">
<description>
Releases the queue&apos;s lock.

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_source_add_poll">
<description>
Adds a file descriptor to the set of file descriptors polled for
this source. This is usually combined with g_source_new() to add an
event source. The event source&apos;s check function will typically test
the @revents field in the #GPollFD struct and return %TRUE if events need
to be processed.

</description>
<parameters>
<parameter name="source">
<parameter_description>a #GSource 
</parameter_description>
</parameter>
<parameter name="fd">
<parameter_description> a #GPollFD structure holding information about a file
descriptor to watch.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_hash_table_unref">
<description>
Atomically decrements the reference count of @hash_table by one.
If the reference count drops to 0, all keys and values will be
destroyed, and all memory allocated by the hash table is released.
This function is MT-safe and may be called from any thread.

Since: 2.10

</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a valid #GHashTable.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_rand_new_with_seed">
<description>
Creates a new random number generator initialized with @seed.


</description>
<parameters>
<parameter name="seed">
<parameter_description> a value to initialize the random number generator.
</parameter_description>
</parameter>
</parameters>
<return> the new #GRand.
</return>
</function>

<function name="g_sequence_iter_is_end">
<description>
Return value: Whether @iter is the end iterator.

</description>
<parameters>
<parameter name="iter">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
</parameters>
<return> Whether @iter is the end iterator.

Since: 2.14
</return>
</function>

<function name="g_queue_pop_tail_link">
<description>
Removes the last element of the queue.


</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue.
</parameter_description>
</parameter>
</parameters>
<return> the #GList element at the tail of the queue, or %NULL if the queue
is empty.
</return>
</function>

<function name="g_async_queue_push_sorted">
<description>
Inserts @data into @queue using @func to determine the new
position. 

This function requires that the @queue is sorted before pushing on
new elements.

This function will lock @queue before it sorts the queue and unlock
it when it is finished.

For an example of @func see g_async_queue_sort(). 

Since: 2.10

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> the @data to push into the @queue
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> the #GCompareDataFunc is used to sort @queue. This function
is passed two elements of the @queue. The function should return
0 if they are equal, a negative value if the first element
should be higher in the @queue or a positive value if the first
element should be lower in the @queue than the second element.
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data passed to @func.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_unichar_xdigit_value">
<description>
Determines the numeric value of a character as a hexidecimal
digit.


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> If @c is a hex digit (according to
g_unichar_isxdigit()), its numeric value. Otherwise, -1.
</return>
</function>

<function name="g_string_append_vprintf">
<description>
Appends a formatted string onto the end of a #GString.
This function is is similar to g_string_append_printf()
except that the arguments to the format string are passed
as a va_list.

Since: 2.14

</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="format">
<parameter_description> the string format. See the printf() documentation
</parameter_description>
</parameter>
<parameter name="args">
<parameter_description> the list of arguments to insert in the output
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_win32_get_windows_version">
<description>
Returns: The version information.

</description>
<parameters>
</parameters>
<return> The version information.

Since: 2.6
</return>
</function>

<function name="g_path_get_dirname">
<description>
Gets the directory components of a file name.  If the file name has no
directory components &quot;.&quot; is returned.  The returned string should be
freed when no longer needed.


</description>
<parameters>
<parameter name="file_name">
<parameter_description> the name of the file.
</parameter_description>
</parameter>
</parameters>
<return> the directory components of the file.
</return>
</function>

<function name="g_unichar_type">
<description>
Classifies a Unicode character by type.


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> the type of the character.
</return>
</function>

<function name="g_filename_from_uri">
<description>
Converts an escaped ASCII-encoded URI to a local filename in the
encoding used for filenames. 


</description>
<parameters>
<parameter name="uri">
<parameter_description> a uri describing a filename (escaped, encoded in ASCII).
</parameter_description>
</parameter>
<parameter name="hostname">
<parameter_description> Location to store hostname for the URI, or %NULL.
If there is no hostname in the URI, %NULL will be
stored in this location.
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store the error occuring, or %NULL to ignore
errors. Any of the errors in #GConvertError may occur.
</parameter_description>
</parameter>
</parameters>
<return> a newly-allocated string holding the resulting
filename, or %NULL on an error.
</return>
</function>

<function name="g_option_context_get_help_enabled">
<description>
Returns: %TRUE if automatic help generation is turned on.

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GOptionContext
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if automatic help generation is turned on.

Since: 2.6
</return>
</function>

<function name="g_option_context_set_description">
<description>
Adds a string to be displayed in &amp;lt;option&amp;gt;--help&amp;lt;/option&amp;gt; output
after the list of options. This text often includes a bug reporting
address.

Note that the summary is translated (see 
g_option_context_set_translate_func()).

Since: 2.12

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GOptionContext
</parameter_description>
</parameter>
<parameter name="description">
<parameter_description> a string to be shown in &amp;lt;option&amp;gt;--help&amp;lt;/option&amp;gt; output 
after the list of options, or %NULL
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_set_prgname">
<description>
Sets the name of the program. This name should &amp;lt;emphasis&amp;gt;not&amp;lt;/emphasis&amp;gt; 
be localized, contrast with g_set_application_name(). Note that for 
thread-safety reasons this function can only be called once.

</description>
<parameters>
<parameter name="prgname">
<parameter_description> the name of the program.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_source_get_context">
<description>
Gets the #GMainContext with which the source is associated.
Calling this function on a destroyed source is an error.


</description>
<parameters>
<parameter name="source">
<parameter_description> a #GSource
</parameter_description>
</parameter>
</parameters>
<return> the #GMainContext with which the source is associated,
or %NULL if the context has not yet been added
to a source.
</return>
</function>

<function name="g_unichar_tolower">
<description>
Converts a character to lower case.


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character.
</parameter_description>
</parameter>
</parameters>
<return> the result of converting @c to lower case.
If @c is not an upperlower or titlecase character,
or has no lowercase equivalent @c is returned unchanged.
</return>
</function>

<function name="g_spawn_async_with_pipes">
<description>
Executes a child program asynchronously (your program will not
block waiting for the child to exit). The child program is
specified by the only argument that must be provided, @argv. @argv
should be a %NULL-terminated array of strings, to be passed as the
argument vector for the child. The first string in @argv is of
course the name of the program to execute. By default, the name of
the program must be a full path; the &amp;lt;envar&amp;gt;PATH&amp;lt;/envar&amp;gt; shell variable 
will only be searched if you pass the %G_SPAWN_SEARCH_PATH flag.

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 argument vectors 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&apos;s
tools it is enough to make the program have a wmain() instead of
main(). wmain() has a wide character argument vector as parameter.

At least currently, mingw doesn&apos;t support wmain(), so if you use
mingw to develop the spawned program, it will have to call the
undocumented function __wgetmainargs() to get the wide character
argument vector and environment. See gspawn-win32-helper.c in the
GLib sources or init.c in the mingw runtime sources for a prototype
for that function. Alternatively, you can retrieve the Win32 system
level wide character command line passed to the spawned program
using the GetCommandLineW() function.

On Windows the low-level child process creation API
&amp;lt;function&amp;gt;CreateProcess()&amp;lt;/function&amp;gt; doesn&apos;t use argument vectors,
but a command line. The C runtime library&apos;s
&amp;lt;function&amp;gt;spawn*()&amp;lt;/function&amp;gt; family of functions (which
g_spawn_async_with_pipes() eventually calls) paste the argument
vector elements together into a command line, and the C runtime startup code
does a corresponding reconstruction of an argument vector from the
command line, to be passed to main(). Complications arise when you have
argument vector elements that contain spaces of double quotes. The
&amp;lt;function&amp;gt;spawn*()&amp;lt;/function&amp;gt; functions don&apos;t do any quoting or
escaping, but on the other hand the startup code does do unquoting
and unescaping in order to enable receiving arguments with embedded
spaces or double quotes. To work around this asymmetry,
g_spawn_async_with_pipes() will do quoting and escaping on argument
vector elements that need it before calling the C runtime
spawn() function.

@envp is a %NULL-terminated array of strings, where each string
has the form &amp;lt;literal&amp;gt;KEY=VALUE&amp;lt;/literal&amp;gt;. This will become
the child&apos;s environment. If @envp is %NULL, the child inherits its
parent&apos;s environment.

@flags should be the bitwise OR of any flags you want to affect the
function&apos;s behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that 
the child will not automatically be reaped; you must use a
#GChildWatch source to be notified about the death of the child 
process. Eventually you must call g_spawn_close_pid() on the
@child_pid, in order to free resources which may be associated
with the child process. (On Unix, using a #GChildWatch source is
equivalent to calling waitpid() or handling the %SIGCHLD signal 
manually. On Windows, calling g_spawn_close_pid() is equivalent
to calling CloseHandle() on the process handle returned in 
@child_pid).

%G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that the parent&apos;s open file
descriptors will be inherited by the child; otherwise all
descriptors except stdin/stdout/stderr will be closed before
calling exec() in the child. %G_SPAWN_SEARCH_PATH 
means that &amp;lt;literal&amp;gt;argv[0]&amp;lt;/literal&amp;gt; need not be an absolute path, it
will be looked for in the user&apos;s &amp;lt;envar&amp;gt;PATH&amp;lt;/envar&amp;gt;. 
%G_SPAWN_STDOUT_TO_DEV_NULL means that the child&apos;s standard output will 
be discarded, instead of going to the same location as the parent&apos;s 
standard output. If you use this flag, @standard_output must be %NULL.
%G_SPAWN_STDERR_TO_DEV_NULL means that the child&apos;s standard error
will be discarded, instead of going to the same location as the parent&apos;s
standard error. If you use this flag, @standard_error must be %NULL.
%G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent&apos;s
standard input (by default, the child&apos;s standard input is attached to
/dev/null). If you use this flag, @standard_input must be %NULL.
%G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is
the file to execute, while the remaining elements are the
actual argument vector to pass to the file. Normally
g_spawn_async_with_pipes() uses @argv[0] as the file to execute, and
passes all of @argv to the child.

@child_setup and @user_data are a function and user data. On POSIX
platforms, the function is called in the child after GLib has
performed all the setup it plans to perform (including creating
pipes, closing file descriptors, etc.) but before calling
exec(). That is, @child_setup is called just
before calling exec() in the child. Obviously
actions taken in this function will only affect the child, not the
parent. On Windows, there is no separate fork() and exec()
functionality. Child processes are created and run with
a single API call, CreateProcess(). @child_setup is
called in the parent process just before creating the child
process. You should carefully consider what you do in @child_setup
if you intend your software to be portable to Windows.

If non-%NULL, @child_pid will on Unix be filled with the child&apos;s
process ID. You can use the process ID to send signals to the
child, or to use g_child_watch_add() (or waitpid()) if you specified the
%G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be
filled with a handle to the child process only if you specified the
%G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child
process using the Win32 API, for example wait for its termination
with the &amp;lt;function&amp;gt;WaitFor*()&amp;lt;/function&amp;gt; functions, or examine its
exit code with GetExitCodeProcess(). You should close the handle 
with CloseHandle() or g_spawn_close_pid() when you no longer need it.

If non-%NULL, the @standard_input, @standard_output, @standard_error
locations will be filled with file descriptors for writing to the child&apos;s
standard input or reading from its standard output or standard error.
The caller of g_spawn_async_with_pipes() must close these file descriptors
when they are no longer in use. If these parameters are %NULL, the corresponding
pipe won&apos;t be created.

If @standard_input is NULL, the child&apos;s standard input is attached to 
/dev/null unless %G_SPAWN_CHILD_INHERITS_STDIN is set.

If @standard_error is NULL, the child&apos;s standard error goes to the same 
location as the parent&apos;s standard error unless %G_SPAWN_STDERR_TO_DEV_NULL 
is set.

If @standard_output is NULL, the child&apos;s standard output goes to the same 
location as the parent&apos;s standard output unless %G_SPAWN_STDOUT_TO_DEV_NULL 
is set.

@error can be %NULL to ignore errors, or non-%NULL to report errors.
If an error is set, the function returns %FALSE. Errors
are reported even if they occur in the child (for example if the
executable in &amp;lt;literal&amp;gt;argv[0]&amp;lt;/literal&amp;gt; is not found). Typically
the &amp;lt;literal&amp;gt;message&amp;lt;/literal&amp;gt; field of returned errors should be displayed
to users. Possible errors are those from the #G_SPAWN_ERROR domain.

If an error occurs, @child_pid, @standard_input, @standard_output,
and @standard_error will not be filled with valid values.

If @child_pid is not %NULL and an error does not occur then the returned
pid must be closed using g_spawn_close_pid().

&amp;lt;note&amp;gt;&amp;lt;para&amp;gt;
If you are writing a GTK+ application, and the program you 
are spawning is a graphical application, too, then you may
want to use gdk_spawn_on_screen_with_pipes() instead to ensure that 
the spawned program opens its windows no the right screen.
&amp;lt;/para&amp;gt;&amp;lt;/note&amp;gt;


</description>
<parameters>
<parameter name="working_directory">
<parameter_description> child&apos;s current working directory, or %NULL to inherit parent&apos;s, in the GLib file name encoding
</parameter_description>
</parameter>
<parameter name="argv">
<parameter_description> child&apos;s argument vector, in the GLib file name encoding
</parameter_description>
</parameter>
<parameter name="envp">
<parameter_description> child&apos;s environment, or %NULL to inherit parent&apos;s, in the GLib file name encoding
</parameter_description>
</parameter>
<parameter name="flags">
<parameter_description> flags from #GSpawnFlags
</parameter_description>
</parameter>
<parameter name="child_setup">
<parameter_description> function to run in the child just before exec()
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data for @child_setup
</parameter_description>
</parameter>
<parameter name="child_pid">
<parameter_description> return location for child process ID, or %NULL
</parameter_description>
</parameter>
<parameter name="standard_input">
<parameter_description> return location for file descriptor to write to child&apos;s stdin, or %NULL
</parameter_description>
</parameter>
<parameter name="standard_output">
<parameter_description> return location for file descriptor to read child&apos;s stdout, or %NULL
</parameter_description>
</parameter>
<parameter name="standard_error">
<parameter_description> return location for file descriptor to read child&apos;s stderr, or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for error
</parameter_description>
</parameter>
</parameters>
<return> %TRUE on success, %FALSE if an error was set
</return>
</function>

<function name="g_sequence_get_iter_at_pos">
<description>
Return value: The #GSequenceIter at position @pos

</description>
<parameters>
<parameter name="seq">
<parameter_description> a #GSequence
</parameter_description>
</parameter>
<parameter name="pos">
<parameter_description> a position in @seq, or -1 for the end.
</parameter_description>
</parameter>
</parameters>
<return> The #GSequenceIter at position @pos

Since: 2.14
</return>
</function>

<function name="g_utf8_pointer_to_offset">
<description>
Converts from a pointer to position within a string to a integer
character offset.

Since 2.10, this function allows @pos to be before @str, and returns
a negative offset in this case.


</description>
<parameters>
<parameter name="str">
<parameter_description> a UTF-8 encoded string
</parameter_description>
</parameter>
<parameter name="pos">
<parameter_description> a pointer to a position within @str
</parameter_description>
</parameter>
</parameters>
<return> the resulting character offset
</return>
</function>

<function name="g_bookmark_file_set_visited">
<description>
Sets the time the bookmark for @uri was last visited.

If no bookmark for @uri is found then it is created.

The &quot;visited&quot; time should only be set if the bookmark was launched, 
either using the command line retrieved by g_bookmark_file_get_app_info()
or by the default application for the bookmark&apos;s MIME type, retrieved
using g_bookmark_file_get_mime_type().  Changing the &quot;visited&quot; time
does not affect the &quot;modified&quot; time.

Since: 2.12

</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="visited">
<parameter_description> a timestamp or -1 to use the current time
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_rand_copy">
<description>
Copies a #GRand into a new one with the same exact state as before.
This way you can take a snapshot of the random number generator for
replaying later.


</description>
<parameters>
<parameter name="rand_">
<parameter_description> a #GRand.
</parameter_description>
</parameter>
</parameters>
<return> the new #GRand.

Since: 2.4
</return>
</function>

<function name="g_spawn_sync">
<description>
Executes a child synchronously (waits for the child to exit before returning).
All output from the child is stored in @standard_output and @standard_error,
if those parameters are non-%NULL. If @exit_status is non-%NULL, the exit 
status of the child is stored there as it would be returned by 
waitpid(); standard UNIX macros such as WIFEXITED() and WEXITSTATUS() 
must be used to evaluate the exit status. If an error occurs, no data is 
returned in @standard_output, @standard_error, or @exit_status.

This function calls g_spawn_async_with_pipes() internally; see that
function for full details on the other parameters and details on
how these functions work on Windows.


</description>
<parameters>
<parameter name="working_directory">
<parameter_description> child&apos;s current working directory, or %NULL to inherit parent&apos;s
</parameter_description>
</parameter>
<parameter name="argv">
<parameter_description> child&apos;s argument vector
</parameter_description>
</parameter>
<parameter name="envp">
<parameter_description> child&apos;s environment, or %NULL to inherit parent&apos;s
</parameter_description>
</parameter>
<parameter name="flags">
<parameter_description> flags from #GSpawnFlags
</parameter_description>
</parameter>
<parameter name="child_setup">
<parameter_description> function to run in the child just before exec()
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data for @child_setup
</parameter_description>
</parameter>
<parameter name="standard_output">
<parameter_description> return location for child output 
</parameter_description>
</parameter>
<parameter name="standard_error">
<parameter_description> return location for child error messages
</parameter_description>
</parameter>
<parameter name="exit_status">
<parameter_description> return location for child exit status, as returned by waitpid()
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for error
</parameter_description>
</parameter>
</parameters>
<return> %TRUE on success, %FALSE if an error was set.
</return>
</function>

<function name="g_queue_index">
<description>
Return value: The position of the first element in @queue which contains @data, or -1 if no element in @queue contains @data.

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> the data to find.
</parameter_description>
</parameter>
</parameters>
<return> The position of the first element in @queue which contains @data, or -1 if no element in @queue contains @data.

Since: 2.4
</return>
</function>

<function name="g_utf8_strrchr">
<description>
Find the rightmost occurrence of the given Unicode character
in a UTF-8 encoded string, while limiting the search to @len bytes.
If @len is -1, allow unbounded search.


</description>
<parameters>
<parameter name="p">
<parameter_description> a nul-terminated UTF-8 encoded string
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the maximum length of @p
</parameter_description>
</parameter>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %NULL if the string does not contain the character, 
otherwise, a pointer to the start of the rightmost occurrence of the 
character in the string.
</return>
</function>

<function name="g_option_context_set_ignore_unknown_options">
<description>
Sets whether to ignore unknown options or not. If an argument is 
ignored, it is left in the @argv array after parsing. By default, 
g_option_context_parse() treats unknown options as error.

This setting does not affect non-option arguments (i.e. arguments 
which don&apos;t start with a dash). But note that GOption cannot reliably
determine whether a non-option belongs to a preceding unknown option.

Since: 2.6

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GOptionContext
</parameter_description>
</parameter>
<parameter name="ignore_unknown">
<parameter_description> %TRUE to ignore unknown options, %FALSE to produce
an error when unknown options are met
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_clear_error">
<description>
If @err is %NULL, does nothing. If @err is non-%NULL,
calls g_error_free() on *@err and sets *@err to %NULL.

</description>
<parameters>
<parameter name="err">
<parameter_description> a #GError return location
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_sequence_get_end_iter">
<description>
Return value: the end iterator for @seq

</description>
<parameters>
<parameter name="seq">
<parameter_description> a #GSequence 
</parameter_description>
</parameter>
</parameters>
<return> the end iterator for @seq

Since: 2.14
</return>
</function>

<function name="g_ascii_tolower">
<description>
Convert a character to ASCII lower case.

Unlike the standard C library tolower() function, this only
recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are lower case
letters in a particular character set. Also unlike the standard
library function, this takes and returns a char, not an int, so
don&apos;t call it on %EOF but no need to worry about casting to #guchar
before passing a possibly non-ASCII character in.


</description>
<parameters>
<parameter name="c">
<parameter_description> any character.
</parameter_description>
</parameter>
</parameters>
<return> the result of converting @c to lower case.
If @c is not an ASCII upper case letter,
@c is returned unchanged.
</return>
</function>

<function name="g_queue_get_length">
<description>
Return value: The number of items in @queue.

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
</parameters>
<return> The number of items in @queue.

Since: 2.4
</return>
</function>

<function name="g_io_channel_get_line_term">
<description>
This returns the string that #GIOChannel uses to determine
where in the file a line break occurs. A value of %NULL
indicates auto detection.


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> a location to return the length of the line terminator
</parameter_description>
</parameter>
</parameters>
<return> The line termination string. This value
is owned by GLib and must not be freed.
</return>
</function>

<function name="g_utf8_strreverse">
<description>
Reverses a UTF-8 string. @str must be valid UTF-8 encoded text. 
(Use g_utf8_validate() on all text before trying to use UTF-8 
utility functions with it.)

Note that unlike g_strreverse(), this function returns
newly-allocated memory, which should be freed with g_free() when
no longer needed. 


</description>
<parameters>
<parameter name="str">
<parameter_description> a UTF-8 encoded string
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the maximum length of @str to use. If @len &amp;lt; 0, then
the string is nul-terminated.
</parameter_description>
</parameter>
</parameters>
<return> a newly-allocated string which is the reverse of @str.

Since: 2.2
</return>
</function>

<function name="g_random_int_range">
<description>
Return value: A random number.

</description>
<parameters>
<parameter name="begin">
<parameter_description> lower closed bound of the interval.
</parameter_description>
</parameter>
<parameter name="end">
<parameter_description> upper open bound of the interval.
</parameter_description>
</parameter>
</parameters>
<return> A random number.
</return>
</function>

<function name="g_datalist_get_flags">
<description>
Gets flags values packed in together with the datalist.
See g_datalist_set_flags().


</description>
<parameters>
<parameter name="datalist">
<parameter_description> pointer to the location that holds a list
</parameter_description>
</parameter>
</parameters>
<return> the flags of the datalist

Since: 2.8
</return>
</function>

<function name="g_idle_remove_by_data">
<description>
Removes the idle function with the given data.


</description>
<parameters>
<parameter name="data">
<parameter_description> the data for the idle source&apos;s callback.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if an idle source was found and removed.
</return>
</function>

<function name="g_queue_new">
<description>
Creates a new #GQueue. 


</description>
<parameters>
</parameters>
<return> a new #GQueue.
</return>
</function>

<function name="g_basename">
<description>
Gets the name of the file without any leading directory components.  
It returns a pointer into the given file name string.


</description>
<parameters>
<parameter name="file_name">
<parameter_description> the name of the file.
</parameter_description>
</parameter>
</parameters>
<return> the name of the file without any leading directory components.

Deprecated:2.2: Use g_path_get_basename() instead, but notice that
g_path_get_basename() allocates new memory for the returned string, unlike
this function which returns a pointer into the argument.
</return>
</function>

<function name="g_unlink">
<description>
A wrapper for the POSIX unlink() function. The unlink() function 
deletes a name from the filesystem. If this was the last link to the 
file and no processes have it opened, the diskspace occupied by the
file is freed.

See your C library manual for more details about unlink(). Note
that on Windows, it is in general not possible to delete files that
are open to some process, or mapped into memory.


</description>
<parameters>
<parameter name="filename">
<parameter_description> a pathname in the GLib file name encoding (UTF-8 on Windows)
</parameter_description>
</parameter>
</parameters>
<return> 0 if the name was successfully deleted, -1 if an error 
occurred

Since: 2.6
</return>
</function>

<function name="g_io_channel_get_buffered">
<description>
Return Value: %TRUE if the @channel is buffered. 

</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the @channel is buffered. 
</return>
</function>

<function name="g_io_channel_read_to_end">
<description>
Reads all the remaining data from the file.


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
<parameter name="str_return">
<parameter_description> Location to store a pointer to a string holding
the remaining data in the #GIOChannel. This data should
be freed with g_free() when no longer needed. This
data is terminated by an extra nul character, but there 
may be other nuls in the intervening data.
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> Location to store length of the data
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> A location to return an error of type #GConvertError
or #GIOChannelError
</parameter_description>
</parameter>
</parameters>
<return> %G_IO_STATUS_NORMAL on success. 
This function never returns %G_IO_STATUS_EOF.
</return>
</function>

<function name="g_sequence_remove">
<description>
Removes the item pointed to by @iter. It is an error to pass the
end iterator to this function.

If the sequnce has a data destroy function associated with it, this
function is called on the data for the removed item.

Since: 2.14

</description>
<parameters>
<parameter name="iter">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_unichar_islower">
<description>
Determines whether a character is a lowercase letter.
Given some UTF-8 text, obtain a character value with
g_utf8_get_char().


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @c is a lowercase letter
</return>
</function>

<function name="g_async_queue_try_pop_unlocked">
<description>
Tries to pop data from the @queue. If no data is available, %NULL is
returned. This function must be called while holding the @queue&apos;s
lock.


</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue.
</parameter_description>
</parameter>
</parameters>
<return> data from the queue or %NULL, when no data is
available immediately.
</return>
</function>

<function name="g_main_depth">
<description>
Returns the depth of the stack of calls to

</description>
<parameters>
</parameters>
<return>the depth of the stack of calls to
g_main_context_dispatch() on any #GMainContext in the current thread.
That is, when called from the toplevel, it gives 0. When
called from within a callback from g_main_context_iteration()
(or g_main_loop_run(), etc.) it returns 1. When called from within 
a callback to a recursive call to g_main_context_iterate(),
it returns 2. And so forth.

This function is useful in a situation like the following:
Imagine an extremely simple &quot;garbage collected&quot; system.

&amp;lt;example&amp;gt;
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-&amp;gt;next);
g_free (l-&amp;gt;data);
g_list_free (free_list);
free_list = NULL;
}

[...]

while (TRUE); 
{
g_main_context_iteration (NULL, TRUE);
free_allocated_memory();
}
&amp;lt;/example&amp;gt;

This works from an application, however, if you want to do the same
thing from a library, it gets more difficult, since you no longer
control the main loop. You might think you can simply use an idle
function to make the call to free_allocated_memory(), but that
doesn&apos;t work, since the idle function could be called from a
recursive callback. This can be fixed by using g_main_depth()

&amp;lt;example&amp;gt;
gpointer
allocate_memory (gsize size)
{ 
FreeListBlock *block = g_new (FreeListBlock, 1);\
block-&amp;gt;mem = g_malloc (size);
block-&amp;gt;depth = g_main_depth ();   
free_list = g_list_prepend (free_list, block);
return block-&amp;gt;mem;
}

void
free_allocated_memory (void)
{
GList *l;

int depth = g_main_depth ();
for (l = free_list; l; );
{
GList *next = l-&amp;gt;next;
FreeListBlock *block = l-&amp;gt;data;
if (block-&amp;gt;depth &amp;gt; depth)
{
g_free (block-&amp;gt;mem);
g_free (block);
free_list = g_list_delete_link (free_list, l);
}

l = next;
}
}
&amp;lt;/example&amp;gt;

There is a temptation to use g_main_depth() to solve
problems with reentrancy. For instance, while waiting for data
to be received from the network in response to a menu item,
the menu item might be selected again. It might seem that
one could make the menu item&apos;s callback return immediately
and do nothing if g_main_depth() returns a value greater than 1.
However, this should be avoided since the user then sees selecting
the menu item do nothing. Furthermore, you&apos;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:

&amp;lt;orderedlist&amp;gt;
&amp;lt;listitem&amp;gt;
&amp;lt;para&amp;gt;
Use gtk_widget_set_sensitive() or modal dialogs to prevent
the user from interacting with elements while the main
loop is recursing.
&amp;lt;/para&amp;gt;
&amp;lt;/listitem&amp;gt;
&amp;lt;listitem&amp;gt;
&amp;lt;para&amp;gt;
Avoid main loop recursion in situations where you can&apos;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.
&amp;lt;/para&amp;gt;
&amp;lt;/listitem&amp;gt;
&amp;lt;/orderedlist&amp;gt;
</return>
</function>

<function name="g_hash_table_remove_all">
<description>
Removes all keys and their associated values from a #GHashTable.

If the #GHashTable was created using g_hash_table_new_full(), the keys
and values are freed using the supplied destroy functions, otherwise you
have to make sure that any dynamically allocated values are freed
yourself.

Since: 2.12

</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a #GHashTable
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_rand_double_range">
<description>
Return value: A random number.

</description>
<parameters>
<parameter name="rand_">
<parameter_description> a #GRand.
</parameter_description>
</parameter>
<parameter name="begin">
<parameter_description> lower closed bound of the interval.
</parameter_description>
</parameter>
<parameter name="end">
<parameter_description> upper open bound of the interval.
</parameter_description>
</parameter>
</parameters>
<return> A random number.
</return>
</function>

<function name="g_hash_table_remove">
<description>
Removes a key and its associated value from a #GHashTable.

If the #GHashTable was created using g_hash_table_new_full(), the
key and value are freed using the supplied destroy functions, otherwise
you have to make sure that any dynamically allocated values are freed 
yourself.


</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a #GHashTable.
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> the key to remove.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the key was found and removed from the #GHashTable.
</return>
</function>

<function name="g_string_up">
<description>
Converts a #GString to uppercase.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString 
</parameter_description>
</parameter>
</parameters>
<return> @string

Deprecated:2.2: This function uses the locale-specific 
toupper() function, which is almost never the right thing. 
Use g_string_ascii_up() or g_utf8_strup() instead.
</return>
</function>

<function name="g_error_matches">
<description>
Return value: whether @error has @domain and @code

</description>
<parameters>
<parameter name="error">
<parameter_description> a #GError
</parameter_description>
</parameter>
<parameter name="domain">
<parameter_description> an error domain
</parameter_description>
</parameter>
<parameter name="code">
<parameter_description> an error code
</parameter_description>
</parameter>
</parameters>
<return> whether @error has @domain and @code
</return>
</function>

<function name="g_string_sized_new">
<description>
Creates a new #GString, with enough space for @dfl_size 
bytes. This is useful if you are going to add a lot of 
text to the string and don&apos;t want it to be reallocated 
too often.


</description>
<parameters>
<parameter name="dfl_size">
<parameter_description> the default size of the space allocated to 
hold the string
</parameter_description>
</parameter>
</parameters>
<return> the new #GString
</return>
</function>

<function name="_glib_get_locale_dir">
<description>
Return the path to the lib\locale subfolder of the GLib
installation folder. The path is in the system codepage. We have to
use system codepage as bindtextdomain() doesn&apos;t have a UTF-8
interface.

</description>
<parameters>
</parameters>
<return></return>
</function>

<function name="g_filename_display_name">
<description>
Converts a filename into a valid UTF-8 string. The conversion is 
not necessarily reversible, so you should keep the original around 
and use the return value of this function only for display purposes.
Unlike g_filename_to_utf8(), the result is guaranteed to be non-%NULL 
even if the filename actually isn&apos;t in the GLib file name encoding.

If GLib can not make sense of the encoding of @filename, as a last resort it 
replaces unknown characters with U+FFFD, the Unicode replacement character.
You can search the result for the UTF-8 encoding of this character (which is
&quot;\357\277\275&quot; in octal notation) to find out if @filename was in an invalid
encoding.

If you know the whole pathname of the file you should use
g_filename_display_basename(), since that allows location-based
translation of filenames.


</description>
<parameters>
<parameter name="filename">
<parameter_description> a pathname hopefully in the GLib file name encoding
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string containing
a rendition of the filename in valid UTF-8

Since: 2.6
</return>
</function>

<function name="g_option_context_add_main_entries">
<description>
A convenience function which creates a main group if it doesn&apos;t 
exist, adds the @entries to it and sets the translation domain.

Since: 2.6

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GOptionContext
</parameter_description>
</parameter>
<parameter name="entries">
<parameter_description> a %NULL-terminated array of #GOptionEntry&amp;lt;!-- --&amp;gt;s
</parameter_description>
</parameter>
<parameter name="translation_domain">
<parameter_description> a translation domain to use for translating
the &amp;lt;option&amp;gt;--help&amp;lt;/option&amp;gt; output for the options in @entries
with gettext(), or %NULL
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_dir_open">
<description>
Opens a directory for reading. The names of the files in the
directory can then be retrieved using g_dir_read_name().


</description>
<parameters>
<parameter name="path">
<parameter_description> the path to the directory you are interested in. On Unix
in the on-disk encoding. On Windows in UTF-8
</parameter_description>
</parameter>
<parameter name="flags">
<parameter_description> Currently must be set to 0. Reserved for future use.
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL.
If non-%NULL, an error will be set if and only if
g_dir_open() fails.
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated #GDir on success, %NULL on failure.
If non-%NULL, you must free the result with g_dir_close()
when you are finished with it.
</return>
</function>

<function name="g_lstat">
<description>
A wrapper for the POSIX lstat() function. The lstat() function is
like stat() except that in the case of symbolic links, it returns
information about the symbolic link itself and not the file that it
refers to. If the system does not support symbolic links g_lstat()
is identical to g_stat().

See the C library manual for more details about lstat().


</description>
<parameters>
<parameter name="filename">
<parameter_description> a pathname in the GLib file name encoding (UTF-8 on Windows)
</parameter_description>
</parameter>
<parameter name="buf">
<parameter_description> a pointer to a &amp;lt;structname&amp;gt;stat&amp;lt;/structname&amp;gt; struct, which
will be filled with the file information
</parameter_description>
</parameter>
</parameters>
<return> 0 if the information was successfully retrieved, -1 if an error 
occurred

Since: 2.6
</return>
</function>

<function name="g_thread_pool_push">
<description>
Inserts @data into the list of tasks to be executed by @pool. When
the number of currently running threads is lower than the maximal
allowed number of threads, a new thread is started (or reused) with
the properties given to g_thread_pool_new (). Otherwise @data stays
in the queue until a thread in this pool finishes its previous task
and processes @data. 

@error can be %NULL to ignore errors, or non-%NULL to report
errors. An error can only occur when a new thread couldn&apos;t be
created. In that case @data is simply appended to the queue of work
to do.  

</description>
<parameters>
<parameter name="pool">
<parameter_description> a #GThreadPool
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> a new task for @pool
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for error
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_regex_ref">
<description>
Increases reference count of @regex by 1.


</description>
<parameters>
<parameter name="regex">
<parameter_description> a #GRegex
</parameter_description>
</parameter>
</parameters>
<return> @regex

Since: 2.14
</return>
</function>

<function name="g_string_prepend_c">
<description>
Adds a byte onto the start of a #GString, 
expanding it if necessary.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="c">
<parameter_description> the byte to prepend on the start of the #GString
</parameter_description>
</parameter>
</parameters>
<return> @string
</return>
</function>

<function name="g_sequence_sort_changed">
<description>
Moves the data pointed to a new position as indicated by @cmp_func. This
function should be called for items in a sequence already sorted according
to @cmp_func whenever some aspect of an item changes so that @cmp_func
may return different values for that item.

Since: 2.14

</description>
<parameters>
<parameter name="iter">
<parameter_description> A #GSequenceIter
</parameter_description>
</parameter>
<parameter name="cmp_func">
<parameter_description> the #GCompareDataFunc used to compare items in the sequence. It
is called with two items of the @seq and @user_data. It should
return 0 if the items are equal, a negative value if the first
item comes before the second, and a positive value if the second
item comes before the first.
</parameter_description>
</parameter>
<parameter name="cmp_data">
<parameter_description> user data passed to @cmp_func.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_strip_context">
<description>
An auxiliary function for gettext() support (see Q_()).


</description>
<parameters>
<parameter name="msgid">
<parameter_description> a string
</parameter_description>
</parameter>
<parameter name="msgval">
<parameter_description> another string
</parameter_description>
</parameter>
</parameters>
<return> @msgval, unless @msgval is identical to @msgid and contains
a &apos;|&apos; character, in which case a pointer to the substring of msgid after
the first &apos;|&apos; character is returned. 

Since: 2.4
</return>
</function>

<function name="g_main_context_query">
<description>
Determines information necessary to poll this main loop.


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext
</parameter_description>
</parameter>
<parameter name="max_priority">
<parameter_description> maximum priority source to check
</parameter_description>
</parameter>
<parameter name="timeout_">
<parameter_description> location to store timeout to be used in polling
</parameter_description>
</parameter>
<parameter name="fds">
<parameter_description> location to store #GPollFD records that need to be polled.
</parameter_description>
</parameter>
<parameter name="n_fds">
<parameter_description> length of @fds.
</parameter_description>
</parameter>
</parameters>
<return> the number of records actually stored in @fds,
or, if more than @n_fds records need to be stored, the number
of records that need to be stored.
</return>
</function>

<function name="g_get_home_dir">
<description>
Gets the current user&apos;s home directory as defined in the 
password database.

Note that in contrast to traditional UNIX tools, this function 
prefers &amp;lt;filename&amp;gt;passwd&amp;lt;/filename&amp;gt; entries over the &amp;lt;envar&amp;gt;HOME&amp;lt;/envar&amp;gt; 
environment variable. 

One of the reasons for this decision is that applications in many 
cases need special handling to deal with the case where 
&amp;lt;envar&amp;gt;HOME&amp;lt;/envar&amp;gt; is
&amp;lt;simplelist&amp;gt;
&amp;lt;member&amp;gt;Not owned by the user&amp;lt;/member&amp;gt;
&amp;lt;member&amp;gt;Not writeable&amp;lt;/member&amp;gt;
&amp;lt;member&amp;gt;Not even readable&amp;lt;/member&amp;gt;
&amp;lt;/simplelist&amp;gt;
Since applications are in general &amp;lt;emphasis&amp;gt;not&amp;lt;/emphasis&amp;gt; written 
to deal with these situations it was considered better to make 
g_get_homedir() not pay attention to &amp;lt;envar&amp;gt;HOME&amp;lt;/envar&amp;gt; and to 
return the real home directory for the user. If applications
want to pay attention to &amp;lt;envar&amp;gt;HOME&amp;lt;/envar&amp;gt;, they can do:
&amp;lt;informalexample&amp;gt;&amp;lt;programlisting&amp;gt;
const char *homedir = g_getenv (&quot;HOME&quot;);
if (!homedir)
homedir = g_get_homedir (&amp;lt;!-- --&amp;gt;);
&amp;lt;/programlisting&amp;gt;&amp;lt;/informalexample&amp;gt;


</description>
<parameters>
</parameters>
<return> the current user&apos;s home directory
</return>
</function>

<function name="g_memmove">
<description>
Copies a block of memory @len bytes long, from @src to @dest.
The source and destination areas may overlap.

In order to use this function, you must include 
&amp;lt;filename&amp;gt;string.h&amp;lt;/filename&amp;gt; yourself, because this macro will 
typically simply resolve to memmove() and GLib does not include 
&amp;lt;filename&amp;gt;string.h&amp;lt;/filename&amp;gt; for you.

</description>
<parameters>
<parameter name="dest">
<parameter_description> the destination address to copy the bytes to.
</parameter_description>
</parameter>
<parameter name="src">
<parameter_description> the source address to copy the bytes from.
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the number of bytes to copy.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_queue_free">
<description>
Frees the memory allocated for the #GQueue. Only call this function if
@queue was created with g_queue_new(). If queue elements contain
dynamically-allocated memory, they should be freed first.

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_match_info_expand_references">
<description>
Returns: the expanded string, or %NULL if an error occurred

</description>
<parameters>
<parameter name="match_info">
<parameter_description> a #GMatchInfo or %NULL
</parameter_description>
</parameter>
<parameter name="string_to_expand">
<parameter_description> the string to expand
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store the error occuring, or %NULL to ignore errors
</parameter_description>
</parameter>
</parameters>
<return> the expanded string, or %NULL if an error occurred

Since: 2.14
</return>
</function>

<function name="g_key_file_load_from_data">
<description>
Loads a key file from memory into an empty #GKeyFile structure.  If
the object cannot be created then %error is set to a
#GKeyFileError. 


</description>
<parameters>
<parameter name="key_file">
<parameter_description> an empty #GKeyFile struct
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> key file loaded in memory.
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> the length of @data in bytes
</parameter_description>
</parameter>
<parameter name="flags">
<parameter_description> flags from #GKeyFileFlags
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if a key file could be loaded, %FALSE othewise
Since: 2.6
</return>
</function>

<function name="g_string_ascii_up">
<description>
Converts all lower case ASCII letters to upper case ASCII letters.


</description>
<parameters>
<parameter name="string">
<parameter_description> a GString
</parameter_description>
</parameter>
</parameters>
<return> passed-in @string pointer, with all the lower case
characters converted to upper case in place, with
semantics that exactly match g_ascii_toupper().
</return>
</function>

<function name="g_key_file_get_value">
<description>
Return value: a newly allocated string or %NULL if the specified 

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string or %NULL if the specified 
key cannot be found.

Since: 2.6
</return>
</function>

<function name="g_markup_parse_context_end_parse">
<description>
Signals to the #GMarkupParseContext that all data has been
fed into the parse context with g_markup_parse_context_parse().
This function reports an error if the document isn&apos;t complete,
for example if elements are still open.


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMarkupParseContext
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError
</parameter_description>
</parameter>
</parameters>
<return> %TRUE on success, %FALSE if an error was set
</return>
</function>

<function name="g_thread_pool_get_max_threads">
<description>
Return value: the maximal number of threads

</description>
<parameters>
<parameter name="pool">
<parameter_description> a #GThreadPool
</parameter_description>
</parameter>
</parameters>
<return> the maximal number of threads
</return>
</function>

<function name="g_ascii_digit_value">
<description>
Determines the numeric value of a character as a decimal
digit. Differs from g_unichar_digit_value() because it takes
a char, so there&apos;s no worry about sign extension if characters
are signed.


</description>
<parameters>
<parameter name="c">
<parameter_description> an ASCII character.
</parameter_description>
</parameter>
</parameters>
<return> If @c is a decimal digit (according to
g_ascii_isdigit()), its numeric value. Otherwise, -1.
</return>
</function>

<function name="g_main_context_set_poll_func">
<description>
Sets the function to use to handle polling of file descriptors. It
will be used instead of the poll() system call 
(or GLib&apos;s replacement function, which is used where 
poll() isn&apos;t available).

This function could possibly be used to integrate the GLib event
loop with an external event loop.

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> the function to call to poll all file descriptors
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_regex_new">
<description>
Compiles the regular expression to an internal form, and does 
the initial setup of the #GRegex structure.  


</description>
<parameters>
<parameter name="pattern">
<parameter_description> the regular expression
</parameter_description>
</parameter>
<parameter name="compile_options">
<parameter_description> compile options for the regular expression
</parameter_description>
</parameter>
<parameter name="match_options">
<parameter_description> match options for the regular expression
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError
</parameter_description>
</parameter>
</parameters>
<return> a #GRegex structure. Call g_regex_unref() when you 
are done with it

Since: 2.14
</return>
</function>

<function name="g_queue_pop_tail">
<description>
Removes the last element of the queue.


</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue.
</parameter_description>
</parameter>
</parameters>
<return> the data of the last element in the queue, or %NULL if the queue
is empty.
</return>
</function>

<function name="g_timeout_add_full">
<description>
Sets a function to be called at regular intervals, with the given
priority.  The function is called repeatedly until it returns
%FALSE, at which point the timeout is automatically destroyed and
the function will not be called again.  The @notify function is
called when the timeout is destroyed.  The first call to the
function will be at the end of the first @interval.

Note that timeout functions may be delayed, due to the processing of other
event sources. Thus they should not be relied on for precise timing.
After each call to the timeout function, the time of the next
timeout is recalculated based on the current time and the given interval
(it does not try to &apos;catch up&apos; time lost in delays).


</description>
<parameters>
<parameter name="priority">
<parameter_description> the priority of the timeout source. Typically this will be in
the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
</parameter_description>
</parameter>
<parameter name="interval">
<parameter_description> the time between calls to the function, in milliseconds
(1/1000ths of a second)
</parameter_description>
</parameter>
<parameter name="function">
<parameter_description> function to call
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description>     data to pass to @function
</parameter_description>
</parameter>
<parameter name="notify">
<parameter_description>   function to call when the timeout is removed, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> the ID (greater than 0) of the event source.
</return>
</function>

<function name="g_source_is_destroyed">
<description>
Return value: %TRUE if the source has been destroyed

</description>
<parameters>
<parameter name="source">
<parameter_description> a #GSource
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the source has been destroyed

Since: 2.12
</return>
</function>

<function name="g_date_set_time_val">
<description>
Sets the value of a date from a #GTimeVal value.  Note that the
@tv_usec member is ignored, because #GDate can&apos;t make use of the
additional precision.

Since: 2.10

</description>
<parameters>
<parameter name="date">
<parameter_description> a #GDate 
</parameter_description>
</parameter>
<parameter name="timeval">
<parameter_description> #GTimeVal value to set
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_unichar_iszerowidth">
<description>
Determines if a given character typically takes zero width when rendered.
The return value is %TRUE for all non-spacing and enclosing marks
(e.g., combining accents), format characters, zero-width
space, but not U+00AD SOFT HYPHEN.

A typical use of this function is with one of g_unichar_iswide() or
g_unichar_iswide_cjk() to determine the number of cells a string occupies
when displayed on a grid display (terminals).  However, note that not all
terminals support zero-width rendering of zero-width marks.


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the character has zero width

Since: 2.14
</return>
</function>

<function name="g_utf8_strncpy">
<description>
Like the standard C strncpy() function, but 
copies a given number of characters instead of a given number of 
bytes. The @src string must be valid UTF-8 encoded text. 
(Use g_utf8_validate() on all text before trying to use UTF-8 
utility functions with it.)


</description>
<parameters>
<parameter name="dest">
<parameter_description> buffer to fill with characters from @src
</parameter_description>
</parameter>
<parameter name="src">
<parameter_description> UTF-8 encoded string
</parameter_description>
</parameter>
<parameter name="n">
<parameter_description> character count
</parameter_description>
</parameter>
</parameters>
<return> @dest
</return>
</function>

<function name="g_regex_check_replacement">
<description>
Checks whether @replacement is a valid replacement string 
(see g_regex_replace()), i.e. that all escape sequences in 
it are valid.

If @has_references is not %NULL then @replacement is checked 
for pattern references. For instance, replacement text &apos;foo\n&apos;
does not contain references and may be evaluated without information
about actual match, but &apos;\0\1&apos; (whole match followed by first 
subpattern) requires valid #GMatchInfo object.


</description>
<parameters>
<parameter name="replacement">
<parameter_description> the replacement string
</parameter_description>
</parameter>
<parameter name="has_references">
<parameter_description> location to store information about
references in @replacement or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store error
</parameter_description>
</parameter>
</parameters>
<return> whether @replacement is a valid replacement string

Since: 2.14
</return>
</function>

<function name="g_base64_decode">
<description>
Decode a sequence of Base-64 encoded text into binary data


</description>
<parameters>
<parameter name="text">
<parameter_description> zero-terminated string with base64 text to decode
</parameter_description>
</parameter>
<parameter name="out_len">
<parameter_description> The length of the decoded data is written here
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated buffer containing the binary data
that @text represents

Since: 2.12
</return>
</function>

<function name="g_file_test">
<description>
Return value: whether a test was %TRUE

</description>
<parameters>
<parameter name="filename">
<parameter_description> a filename to test in the GLib file name encoding
</parameter_description>
</parameter>
<parameter name="test">
<parameter_description> bitfield of #GFileTest flags
</parameter_description>
</parameter>
</parameters>
<return> whether a test was %TRUE
</return>
</function>

<function name="g_strstr_len">
<description>
Searches the string @haystack for the first occurrence
of the string @needle, limiting the length of the search
to @haystack_len. 


</description>
<parameters>
<parameter name="haystack">
<parameter_description> a string.
</parameter_description>
</parameter>
<parameter name="haystack_len">
<parameter_description> the maximum length of @haystack.
</parameter_description>
</parameter>
<parameter name="needle">
<parameter_description> the string to search for.
</parameter_description>
</parameter>
</parameters>
<return> a pointer to the found occurrence, or
%NULL if not found.
</return>
</function>

<function name="g_ascii_formatd">
<description>
Converts a #gdouble to a string, using the &apos;.&apos; as
decimal point. To format the number you pass in
a printf()-style format string. Allowed conversion
specifiers are &apos;e&apos;, &apos;E&apos;, &apos;f&apos;, &apos;F&apos;, &apos;g&apos; and &apos;G&apos;. 

If you just want to want to serialize the value into a
string, use g_ascii_dtostr().


</description>
<parameters>
<parameter name="buffer">
<parameter_description> A buffer to place the resulting string in
</parameter_description>
</parameter>
<parameter name="buf_len">
<parameter_description> The length of the buffer.
</parameter_description>
</parameter>
<parameter name="format">
<parameter_description> The printf()-style format to use for the
code to use for converting. 
</parameter_description>
</parameter>
<parameter name="d">
<parameter_description> The #gdouble to convert
</parameter_description>
</parameter>
</parameters>
<return> The pointer to the buffer with the converted string.
</return>
</function>

<function name="g_bookmark_file_set_title">
<description>
Sets @title as the title of the bookmark for @uri inside the
bookmark file @bookmark.

If @uri is %NULL, the title of @bookmark is set.

If a bookmark for @uri cannot be found then it is created.

Since: 2.12

</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI or %NULL
</parameter_description>
</parameter>
<parameter name="title">
<parameter_description> a UTF-8 encoded string
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_thread_pool_set_max_threads">
<description>
Sets the maximal allowed number of threads for @pool. A value of -1
means, that the maximal number of threads is unlimited.

Setting @max_threads to 0 means stopping all work for @pool. It is
effectively frozen until @max_threads is set to a non-zero value
again.

A thread is never terminated while calling @func, as supplied by
g_thread_pool_new (). Instead the maximal number of threads only
has effect for the allocation of new threads in g_thread_pool_push(). 
A new thread is allocated, whenever the number of currently
running threads in @pool is smaller than the maximal number.

@error can be %NULL to ignore errors, or non-%NULL to report
errors. An error can only occur when a new thread couldn&apos;t be
created. 

</description>
<parameters>
<parameter name="pool">
<parameter_description> a #GThreadPool
</parameter_description>
</parameter>
<parameter name="max_threads">
<parameter_description> a new maximal number of threads for @pool
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for error
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_utf8_find_next_char">
<description>
Finds the start of the next UTF-8 character in the string after @p.

@p does not have to be at the beginning of a UTF-8 character. No check
is made to see if the character found is actually valid other than
it starts with an appropriate byte.


</description>
<parameters>
<parameter name="p">
<parameter_description> a pointer to a position within a UTF-8 encoded string
</parameter_description>
</parameter>
<parameter name="end">
<parameter_description> a pointer to the end of the string, or %NULL to indicate
that the string is nul-terminated, in which case
the returned value will be 
</parameter_description>
</parameter>
</parameters>
<return> a pointer to the found character or %NULL
</return>
</function>

<function name="g_unichar_isspace">
<description>
Determines whether a character is a space, tab, or line separator
(newline, carriage return, etc.).  Given some UTF-8 text, obtain a
character value with g_utf8_get_char().

(Note: don&apos;t use this to do word breaking; you have to use
Pango or equivalent to get word breaking right, the algorithm
is fairly complex.)


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @c is a space character
</return>
</function>

<function name="g_utf8_to_ucs4">
<description>
Convert a string from UTF-8 to a 32-bit fixed width
representation as UCS-4. A trailing 0 will be added to the
string after the converted text.


</description>
<parameters>
<parameter name="str">
<parameter_description> a UTF-8 encoded string
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> the maximum length of @str to use. If @len &amp;lt; 0, then
the string is nul-terminated.
</parameter_description>
</parameter>
<parameter name="items_read">
<parameter_description> location to store number of bytes read, or %NULL.
If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
returned in case @str contains a trailing partial
character. If an error occurs then the index of the
invalid input is stored here.
</parameter_description>
</parameter>
<parameter name="items_written">
<parameter_description> location to store number of characters written or %NULL.
The value here stored does not include the trailing 0
character. 
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store the error occuring, or %NULL to ignore
errors. Any of the errors in #GConvertError other than
%G_CONVERT_ERROR_NO_CONVERSION may occur.
</parameter_description>
</parameter>
</parameters>
<return> a pointer to a newly allocated UCS-4 string.
This value must be freed with g_free(). If an
error occurs, %NULL will be returned and
@error set.
</return>
</function>

<function name="g_tree_search">
<description>
Searches a #GTree using @search_func.

The @search_func is called with a pointer to the key of a key/value pair in 
the tree, and the passed in @user_data. If @search_func returns 0 for a 
key/value pair, then g_tree_search_func() will return the value of that 
pair. If @search_func returns -1,  searching will proceed among the 
key/value pairs that have a smaller key; if @search_func returns 1, 
searching will proceed among the key/value pairs that have a larger key.


</description>
<parameters>
<parameter name="tree">
<parameter_description> a #GTree.
</parameter_description>
</parameter>
<parameter name="search_func">
<parameter_description> a function used to search the #GTree. 
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> the data passed as the second argument to the @search_func 
function.
</parameter_description>
</parameter>
</parameters>
<return> the value corresponding to the found key, or %NULL if the key 
was not found.
</return>
</function>

<function name="g_get_prgname">
<description>
Gets the name of the program. This name should &amp;lt;emphasis&amp;gt;not&amp;lt;/emphasis&amp;gt; 
be localized, contrast with g_get_application_name().
(If you are using GDK or GTK+ the program name is set in gdk_init(), 
which is called by gtk_init(). The program name is found by taking 
the last component of &amp;lt;literal&amp;gt;argv[0]&amp;lt;/literal&amp;gt;.)


</description>
<parameters>
</parameters>
<return> the name of the program. The returned string belongs 
to GLib and must not be modified or freed.
</return>
</function>

<function name="g_string_insert_len">
<description>
Inserts @len bytes of @val into @string at @pos.  
Because @len is provided, @val may contain embedded 
nuls and need not be nul-terminated. If @pos is -1, 
bytes are inserted at the end of the string.

Since this function does not stop at nul bytes, it is 
the caller&apos;s responsibility to ensure that @val has at 
least @len addressable bytes.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="pos">
<parameter_description> position in @string where insertion should 
happen, or -1 for at the end
</parameter_description>
</parameter>
<parameter name="val">
<parameter_description> bytes to insert
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description> number of bytes of @val to insert
</parameter_description>
</parameter>
</parameters>
<return> @string
</return>
</function>

<function name="g_tree_replace">
<description>
Inserts a new key and value into a #GTree similar to g_tree_insert(). 
The difference is that if the key already exists in the #GTree, it gets 
replaced by the new key. If you supplied a @value_destroy_func when 
creating the #GTree, the old value is freed using that function. If you 
supplied a @key_destroy_func when creating the #GTree, the old key is 
freed using that function. 

The tree is automatically &apos;balanced&apos; as new key/value pairs are added,
so that the distance from the root to every leaf is as small as possible.

</description>
<parameters>
<parameter name="tree">
<parameter_description> a #GTree.
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> the key to insert.
</parameter_description>
</parameter>
<parameter name="value">
<parameter_description> the value corresponding to the key.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_thread_pool_new">
<description>
This function creates a new thread pool.

Whenever you call g_thread_pool_push(), either a new thread is
created or an unused one is reused. At most @max_threads threads
are running concurrently for this thread pool. @max_threads = -1
allows unlimited threads to be created for this thread pool. The
newly created or reused thread now executes the function @func with
the two arguments. The first one is the parameter to
g_thread_pool_push() and the second one is @user_data.

The parameter @exclusive determines, whether the thread pool owns
all threads exclusive or whether the threads are shared
globally. If @exclusive is %TRUE, @max_threads threads are started
immediately and they will run exclusively for this thread pool until
it is destroyed by g_thread_pool_free(). If @exclusive is %FALSE,
threads are created, when needed and shared between all
non-exclusive thread pools. This implies that @max_threads may not
be -1 for exclusive thread pools.

@error can be %NULL to ignore errors, or non-%NULL to report
errors. An error can only occur when @exclusive is set to %TRUE and
not all @max_threads threads could be created.


</description>
<parameters>
<parameter name="func">
<parameter_description> a function to execute in the threads of the new thread pool
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data that is handed over to @func every time it 
is called
</parameter_description>
</parameter>
<parameter name="max_threads">
<parameter_description> the maximal number of threads to execute concurrently in 
the new thread pool, -1 means no limit
</parameter_description>
</parameter>
<parameter name="exclusive">
<parameter_description> should this thread pool be exclusive?
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for error
</parameter_description>
</parameter>
</parameters>
<return> the new #GThreadPool
</return>
</function>

<function name="g_source_attach">
<description>
Adds a #GSource to a @context so that it will be executed within
that context.


</description>
<parameters>
<parameter name="source">
<parameter_description> a #GSource
</parameter_description>
</parameter>
<parameter name="context">
<parameter_description> a #GMainContext (if %NULL, the default context will be used)
</parameter_description>
</parameter>
</parameters>
<return> the ID (greater than 0) for the source within the 
#GMainContext. 
</return>
</function>

<function name="g_vfprintf">
<description>
An implementation of the standard fprintf() function which supports 
positional parameters, as specified in the Single Unix Specification.


</description>
<parameters>
<parameter name="file">
<parameter_description> the stream to write to.
</parameter_description>
</parameter>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice 
&amp;lt;link linkend=&quot;string-precision&quot;&amp;gt;string precision pitfalls&amp;lt;/link&amp;gt;.
</parameter_description>
</parameter>
<parameter name="args">
<parameter_description> the list of arguments to insert in the output.
</parameter_description>
</parameter>
</parameters>
<return> the number of characters printed.

Since: 2.2
</return>
</function>

<function name="g_key_file_set_locale_string_list">
<description>
Associates a list of string values for @key and @locale under
@group_name.  If the translation for @key cannot be found then
it is created. 

Since: 2.6

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="locale">
<parameter_description> a locale
</parameter_description>
</parameter>
<parameter name="list">
<parameter_description> a %NULL-terminated array of locale string values
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> the length of @list
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_error_new">
<description>
Creates a new #GError with the given @domain and @code,
and a message formatted with @format.


</description>
<parameters>
<parameter name="domain">
<parameter_description> error domain 
</parameter_description>
</parameter>
<parameter name="code">
<parameter_description> error code
</parameter_description>
</parameter>
<parameter name="format">
<parameter_description> printf()-style format for error message
</parameter_description>
</parameter>
<parameter name="Varargs">
<parameter_description> parameters for message format
</parameter_description>
</parameter>
</parameters>
<return> a new #GError
</return>
</function>

<function name="g_tree_remove">
<description>
Removes a key/value pair from a #GTree.

If the #GTree was created using g_tree_new_full(), the key and value 
are freed using the supplied destroy functions, otherwise you have to 
make sure that any dynamically allocated values are freed yourself.
If the key does not exist in the #GTree, the function does nothing.


</description>
<parameters>
<parameter name="tree">
<parameter_description> a #GTree.
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> the key to remove.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the key was found (prior to 2.8, this function returned 
nothing)
</return>
</function>

<function name="g_rmdir">
<description>
A wrapper for the POSIX rmdir() function. The rmdir() function
deletes a directory from the filesystem.

See your C library manual for more details about how rmdir() works
on your system.


</description>
<parameters>
<parameter name="filename">
<parameter_description> a pathname in the GLib file name encoding (UTF-8 on Windows)
</parameter_description>
</parameter>
</parameters>
<return> 0 if the directory was successfully removed, -1 if an error 
occurred

Since: 2.6
</return>
</function>

<function name="g_async_queue_new">
<description>
Creates a new asynchronous queue with the initial reference count of 1.


</description>
<parameters>
</parameters>
<return> the new #GAsyncQueue.
</return>
</function>

<function name="g_atexit">
<description>
Specifies a function to be called at normal program termination.

Since GLib 2.8.2, on Windows g_atexit() actually is a preprocessor
macro that maps to a call to the atexit() function in the C
library. This means that in case the code that calls g_atexit(),
i.e. atexit(), is in a DLL, the function will be called when the
DLL is detached from the program. This typically makes more sense
than that the function is called when the GLib DLL is detached,
which happened earlier when g_atexit() was a function in the GLib
DLL.

The behaviour of atexit() in the context of dynamically loaded
modules is not formally specified and varies wildly.

On POSIX systems, calling g_atexit() (or atexit()) in a dynamically
loaded module which is unloaded before the program terminates might
well cause a crash at program exit.

Some POSIX systems implement atexit() like Windows, and have each
dynamically loaded module maintain an own atexit chain that is
called when the module is unloaded.

On other POSIX systems, before a dynamically loaded module is
unloaded, the registered atexit functions (if any) residing in that
module are called, regardless where the code that registered them
resided. This is presumably the most robust approach.

As can be seen from the above, for portability it&apos;s best to avoid
calling g_atexit() (or atexit()) except in the main executable of a
program.

</description>
<parameters>
<parameter name="func">
<parameter_description> the function to call on normal program termination.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_utf8_collate">
<description>
Compares two strings for ordering using the linguistically
correct rules for the &amp;lt;link linkend=&quot;setlocale&quot;&amp;gt;current locale&amp;lt;/link&amp;gt;. 
When sorting a large number of strings, it will be significantly 
faster to obtain collation keys with g_utf8_collate_key() and 
compare the keys with strcmp() when sorting instead of sorting 
the original strings.


</description>
<parameters>
<parameter name="str1">
<parameter_description> a UTF-8 encoded string
</parameter_description>
</parameter>
<parameter name="str2">
<parameter_description> a UTF-8 encoded string
</parameter_description>
</parameter>
</parameters>
<return> &amp;lt; 0 if @str1 compares before @str2, 
0 if they compare equal, &amp;gt; 0 if @str1 compares after @str2.
</return>
</function>

<function name="g_spawn_async">
<description>
See g_spawn_async_with_pipes() for a full description; this function
simply calls the g_spawn_async_with_pipes() without any pipes.

&amp;lt;note&amp;gt;&amp;lt;para&amp;gt;
If you are writing a GTK+ application, and the program you 
are spawning is a graphical application, too, then you may
want to use gdk_spawn_on_screen() instead to ensure that 
the spawned program opens its windows on the right screen.
&amp;lt;/para&amp;gt;&amp;lt;/note&amp;gt;


</description>
<parameters>
<parameter name="working_directory">
<parameter_description> child&apos;s current working directory, or %NULL to inherit parent&apos;s
</parameter_description>
</parameter>
<parameter name="argv">
<parameter_description> child&apos;s argument vector
</parameter_description>
</parameter>
<parameter name="envp">
<parameter_description> child&apos;s environment, or %NULL to inherit parent&apos;s
</parameter_description>
</parameter>
<parameter name="flags">
<parameter_description> flags from #GSpawnFlags
</parameter_description>
</parameter>
<parameter name="child_setup">
<parameter_description> function to run in the child just before exec()
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data for @child_setup
</parameter_description>
</parameter>
<parameter name="child_pid">
<parameter_description> return location for child process ID, or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for error
</parameter_description>
</parameter>
</parameters>
<return> %TRUE on success, %FALSE if error is set
</return>
</function>

<function name="g_async_queue_timed_pop">
<description>
Pops data from the @queue. If no data is received before @end_time,
%NULL is returned.

To easily calculate @end_time a combination of g_get_current_time()
and g_time_val_add() can be used.


</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue.
</parameter_description>
</parameter>
<parameter name="end_time">
<parameter_description> a #GTimeVal, determining the final time.
</parameter_description>
</parameter>
</parameters>
<return> data from the queue or %NULL, when no data is
received before @end_time.
</return>
</function>

<function name="g_uri_list_extract_uris">
<description>
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.


</description>
<parameters>
<parameter name="uri_list">
<parameter_description> an URI list 
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated %NULL-terminated list of
strings holding the individual URIs. The array should
be freed with g_strfreev().

Since: 2.6
</return>
</function>

<function name="g_hash_table_insert">
<description>
Inserts a new key and value into a #GHashTable.

If the key already exists in the #GHashTable its current value is replaced
with the new value. If you supplied a @value_destroy_func when creating the 
#GHashTable, the old value is freed using that function. If you supplied
a @key_destroy_func when creating the #GHashTable, the passed key is freed 
using that function.

</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a #GHashTable.
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key to insert.
</parameter_description>
</parameter>
<parameter name="value">
<parameter_description> the value to associate with the key.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_source_remove_by_user_data">
<description>
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.


</description>
<parameters>
<parameter name="user_data">
<parameter_description> the user_data for the callback.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if a source was found and removed. 
</return>
</function>

<function name="g_tree_steal">
<description>
Removes a key and its associated value from a #GTree without calling 
the key and value destroy functions.

If the key does not exist in the #GTree, the function does nothing.


</description>
<parameters>
<parameter name="tree">
<parameter_description> a #GTree.
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> the key to remove.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the key was found (prior to 2.8, this function returned 
nothing)
</return>
</function>

<function name="g_tree_foreach">
<description>
Calls the given function for each of the key/value pairs in the #GTree.
The function is passed the key and value of each pair, and the given
@data parameter. The tree is traversed in sorted order.

The tree may not be modified while iterating over it (you can&apos;t 
add/remove items). To remove all items matching a predicate, you need 
to add each item to a list in your #GTraverseFunc as you walk over 
the tree, then walk the list and remove each item.

</description>
<parameters>
<parameter name="tree">
<parameter_description> a #GTree.
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> the function to call for each node visited. If this function
returns %TRUE, the traversal is stopped.
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data to pass to the function.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_main_context_pending">
<description>
Checks if any sources have pending events for the given context.


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext (if %NULL, the default context will be used)
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if events are pending.
</return>
</function>

<function name="g_timeout_source_new">
<description>
Creates a new timeout source.

The source will not initially be associated with any #GMainContext
and must be added to one with g_source_attach() before it will be
executed.


</description>
<parameters>
<parameter name="interval">
<parameter_description> the timeout interval in milliseconds.
</parameter_description>
</parameter>
</parameters>
<return> the newly-created timeout source
</return>
</function>

<function name="g_tree_new_full">
<description>
Creates a new #GTree like g_tree_new() and allows to specify functions 
to free the memory allocated for the key and value that get called when 
removing the entry from the #GTree.


</description>
<parameters>
<parameter name="key_compare_func">
<parameter_description> qsort()-style comparison function.
</parameter_description>
</parameter>
<parameter name="key_compare_data">
<parameter_description> data to pass to comparison function.
</parameter_description>
</parameter>
<parameter name="key_destroy_func">
<parameter_description> a function to free the memory allocated for the key 
used when removing the entry from the #GTree or %NULL if you don&apos;t
want to supply such a function.
</parameter_description>
</parameter>
<parameter name="value_destroy_func">
<parameter_description> a function to free the memory allocated for the 
value used when removing the entry from the #GTree or %NULL if you 
don&apos;t want to supply such a function.
</parameter_description>
</parameter>
</parameters>
<return> a new #GTree.
</return>
</function>

<function name="g_main_context_get_poll_func">
<description>
Gets the poll function set by g_main_context_set_poll_func().


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext
</parameter_description>
</parameter>
</parameters>
<return> the poll function
</return>
</function>

<function name="g_string_chunk_insert_const">
<description>
Adds a copy of @string to the #GStringChunk, unless the same 
string has already been added to the #GStringChunk with 
g_string_chunk_insert_const().

This function is useful if you need to copy a large number 
of strings but do not want to waste space storing duplicates. 
But you must remember that there may be several pointers to 
the same string, and so any changes made to the strings 
should be done very carefully.

Note that g_string_chunk_insert_const() will not return a 
pointer to a string added with g_string_chunk_insert(), even 
if they do match.


</description>
<parameters>
<parameter name="chunk">
<parameter_description> a #GStringChunk
</parameter_description>
</parameter>
<parameter name="string">
<parameter_description> the string to add
</parameter_description>
</parameter>
</parameters>
<return> a pointer to the new or existing copy of @string 
within the #GStringChunk
</return>
</function>

<function name="g_string_free">
<description>
Frees the memory allocated for the #GString.
If @free_segment is %TRUE it also frees the character data.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="free_segment">
<parameter_description> if %TRUE the actual character data is freed as well
</parameter_description>
</parameter>
</parameters>
<return> the character data of @string 
(i.e. %NULL if @free_segment is %TRUE)
</return>
</function>

<function name="g_unichar_toupper">
<description>
Converts a character to uppercase.


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> the result of converting @c to uppercase.
If @c is not an lowercase or titlecase character,
or has no upper case equivalent @c is returned unchanged.
</return>
</function>

<function name="g_sequence_remove_range">
<description>
Removes all items in the (@begin, @end) range.

If the sequence has a data destroy function associated with it, this
function is called on the data for the removed items.

Since: 2.14

</description>
<parameters>
<parameter name="begin">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
<parameter name="end">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_io_channel_set_line_term">
<description>
This sets the string that #GIOChannel uses to determine
where in the file a line break occurs.

</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
<parameter name="line_term">
<parameter_description> The line termination string. Use %NULL for auto detect.
Auto detection breaks on &quot;\n&quot;, &quot;\r\n&quot;, &quot;\r&quot;, &quot;\0&quot;, and
the Unicode paragraph separator. Auto detection should
not be used for anything other than file-based channels.
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> The length of the termination string. If -1 is passed, the
string is assumed to be nul-terminated. This option allows
termination strings with embeded nuls.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_sprintf">
<description>
An implementation of the standard sprintf() function which supports 
positional parameters, as specified in the Single Unix Specification.


</description>
<parameters>
<parameter name="string">
<parameter_description> A pointer to a memory buffer to contain the resulting string. It 
is up to the caller to ensure that the allocated buffer is large 
enough to hold the formatted result
</parameter_description>
</parameter>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice 
&amp;lt;link linkend=&quot;string-precision&quot;&amp;gt;string precision pitfalls&amp;lt;/link&amp;gt;.
</parameter_description>
</parameter>
<parameter name="Varargs">
<parameter_description> the arguments to insert in the output.
</parameter_description>
</parameter>
</parameters>
<return> the number of characters printed.

Since: 2.2
</return>
</function>

<function name="g_strncasecmp">
<description>
A case-insensitive string comparison, corresponding to the standard
strncasecmp() function on platforms which support it.
It is similar to g_strcasecmp() except it only compares the first @n 
characters of the strings.


</description>
<parameters>
<parameter name="s1">
<parameter_description> a string.
</parameter_description>
</parameter>
<parameter name="s2">
<parameter_description> a string to compare with @s1.
</parameter_description>
</parameter>
<parameter name="n">
<parameter_description> the maximum number of characters to compare.
</parameter_description>
</parameter>
</parameters>
<return> 0 if the strings match, a negative value if @s1 &amp;lt; @s2, 
or a positive value if @s1 &amp;gt; @s2.

Deprecated:2.2: The problem with g_strncasecmp() is that it does the 
comparison by calling toupper()/tolower(). These functions are
locale-specific and operate on single bytes. However, it is impossible
to handle things correctly from an I18N standpoint by operating on
bytes, since characters may be multibyte. Thus g_strncasecmp() is
broken if your string is guaranteed to be ASCII, since it&apos;s
locale-sensitive, and it&apos;s broken if your string is localized, since
it doesn&apos;t work on many encodings at all, including UTF-8, EUC-JP,
etc.

There are therefore two replacement functions: g_ascii_strncasecmp(),
which only works on ASCII and is not locale-sensitive, and
g_utf8_casefold(), which is good for case-insensitive sorting of UTF-8.
</return>
</function>

<function name="g_unicode_canonical_decomposition">
<description>
Computes the canonical decomposition of a Unicode character.  


</description>
<parameters>
<parameter name="ch">
<parameter_description> a Unicode character.
</parameter_description>
</parameter>
<parameter name="result_len">
<parameter_description> location to store the length of the return value.
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string of Unicode characters.
@result_len is set to the resulting length of the string.
</return>
</function>

<function name="g_sequence_get_begin_iter">
<description>
Return value: the begin iterator for @seq.

</description>
<parameters>
<parameter name="seq">
<parameter_description> a #GSequence
</parameter_description>
</parameter>
</parameters>
<return> the begin iterator for @seq.

Since: 2.14
</return>
</function>

<function name="iconv_cache_bucket_expire">
<description>
Expires a single cache bucket @bucket. This should only ever be
called on a bucket that currently has no used iconv descriptors
open.

@node is not a required argument. If @node is not supplied, we
search for it ourselves.

</description>
<parameters>
<parameter name="node">
<parameter_description> cache bucket&apos;s node
</parameter_description>
</parameter>
<parameter name="bucket">
<parameter_description> cache bucket
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_tree_new_with_data">
<description>
Creates a new #GTree with a comparison function that accepts user data.
See g_tree_new() for more details.


</description>
<parameters>
<parameter name="key_compare_func">
<parameter_description> qsort()-style comparison function.
</parameter_description>
</parameter>
<parameter name="key_compare_data">
<parameter_description> data to pass to comparison function.
</parameter_description>
</parameter>
</parameters>
<return> a new #GTree.
</return>
</function>

<function name="g_key_file_remove_group">
<description>
Removes the specified group, @group_name, 
from the key file. 

Since: 2.6

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError or %NULL
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_rand_int">
<description>
Return value: A random number.

</description>
<parameters>
<parameter name="rand_">
<parameter_description> a #GRand.
</parameter_description>
</parameter>
</parameters>
<return> A random number.
</return>
</function>

<function name="g_unichar_iswide_cjk">
<description>
Determines if a character is typically rendered in a double-width
cell under legacy East Asian locales.  If a character is wide according to
g_unichar_iswide(), then it is also reported wide with this function, but
the converse is not necessarily true.  See the
&amp;lt;ulink url=&quot;http://www.unicode.org/reports/tr11/&quot;&amp;gt;Unicode Standard
Annex #11&amp;lt;/ulink&amp;gt; for details.


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the character is wide in legacy East Asian locales

Since: 2.12
</return>
</function>

<function name="g_option_context_set_translate_func">
<description>
Sets the function which is used to translate the contexts 
user-visible strings, for &amp;lt;option&amp;gt;--help&amp;lt;/option&amp;gt; output. 
If @func is %NULL, strings are not translated.

Note that option groups have their own translation functions, 
this function only affects the @parameter_string (see g_option_context_new()), 
the summary (see g_option_context_set_summary()) and the description 
(see g_option_context_set_description()).

If you are using gettext(), you only need to set the translation
domain, see g_context_group_set_translation_domain().

Since: 2.12

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GOptionContext
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> the #GTranslateFunc, or %NULL 
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description> user data to pass to @func, or %NULL
</parameter_description>
</parameter>
<parameter name="destroy_notify">
<parameter_description> a function which gets called to free @data, or %NULL
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_io_channel_get_buffer_condition">
<description>
This function returns a #GIOCondition depending on whether there
is data to be read/space to write data in the
internal buffers in the #GIOChannel. Only the flags %G_IO_IN and
%G_IO_OUT may be set.


</description>
<parameters>
<parameter name="channel">
<parameter_description> A #GIOChannel
</parameter_description>
</parameter>
</parameters>
<return> A #GIOCondition
</return>
</function>

<function name="g_hash_table_foreach">
<description>
Calls the given function for each of the key/value pairs in the
#GHashTable.  The function is passed the key and value of each
pair, and the given @user_data parameter.  The hash table may not
be modified while iterating over it (you can&apos;t add/remove
items). To remove all items matching a predicate, use
g_hash_table_foreach_remove().

See g_hash_table_find() for performance caveats for linear
order searches in contrast to g_hash_table_lookup().

</description>
<parameters>
<parameter name="hash_table">
<parameter_description> a #GHashTable.
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> the function to call for each key/value pair.
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data to pass to the function.
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_key_file_get_locale_string_list">
<description>
Return value: a newly allocated %NULL-terminated string array

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="locale">
<parameter_description> a locale
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> return location for the number of returned strings or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated %NULL-terminated string array
or %NULL if the key isn&apos;t found. The string array should be freed
with g_strfreev().

Since: 2.6
</return>
</function>

<function name="g_async_queue_sort_unlocked">
<description>
Sorts @queue using @func. 

This function is called while holding the @queue&apos;s lock.

Since: 2.10

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue
</parameter_description>
</parameter>
<parameter name="func">
<parameter_description> the #GCompareDataFunc is used to sort @queue. This
function is passed two elements of the @queue. The function
should return 0 if they are equal, a negative value if the
first element should be higher in the @queue or a positive
value if the first element should be lower in the @queue than
the second element. 
</parameter_description>
</parameter>
<parameter name="user_data">
<parameter_description> user data passed to @func
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_io_channel_read_line">
<description>
Reads a line, including the terminating character(s),
from a #GIOChannel into a newly-allocated string.
@str_return will contain allocated memory if the return
is %G_IO_STATUS_NORMAL.


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
<parameter name="str_return">
<parameter_description> The line read from the #GIOChannel, including the
line terminator. This data should be freed with g_free()
when no longer needed. This is a nul-terminated string. 
If a @length of zero is returned, this will be %NULL instead.
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> location to store length of the read data, or %NULL
</parameter_description>
</parameter>
<parameter name="terminator_pos">
<parameter_description> location to store position of line terminator, or %NULL
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> A location to return an error of type #GConvertError
or #GIOChannelError
</parameter_description>
</parameter>
</parameters>
<return> the status of the operation.
</return>
</function>

<function name="g_sequence_iter_move">
<description>
Return value: a #GSequenceIter which is @delta positions away from @iter.

</description>
<parameters>
<parameter name="iter">
<parameter_description> a #GSequenceIter
</parameter_description>
</parameter>
<parameter name="delta">
<parameter_description> A positive or negative number indicating how many positions away
from @iter the returned #GSequenceIter will be.
</parameter_description>
</parameter>
</parameters>
<return> a #GSequenceIter which is @delta positions away from @iter.

Since: 2.14
</return>
</function>

<function name="g_key_file_set_locale_string">
<description>
Associates a string value for @key and @locale under
@group_name.  If the translation for @key cannot be found 
then it is created.

Since: 2.6

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="locale">
<parameter_description> a locale
</parameter_description>
</parameter>
<parameter name="string">
<parameter_description> a string
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_string_insert_unichar">
<description>
Converts a Unicode character into UTF-8, and insert it
into the string at the given position.


</description>
<parameters>
<parameter name="string">
<parameter_description> a #GString
</parameter_description>
</parameter>
<parameter name="pos">
<parameter_description> the position at which to insert character, or -1 to
append at the end of the string
</parameter_description>
</parameter>
<parameter name="wc">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> @string
</return>
</function>

<function name="g_bookmark_file_free">
<description>
Frees a #GBookmarkFile.

Since: 2.12

</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_regex_match_full">
<description>
Scans for a match in string for the pattern in @regex. 
The @match_options are combined with the match options specified 
when the @regex structure was created, letting you have more 
flexibility in reusing #GRegex structures.

Setting @start_position differs from just passing over a shortened 
string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern 
that begins with any kind of lookbehind assertion, such as &quot;\b&quot;.

A #GMatchInfo structure, used to get information on the match, is 
stored in @match_info if not %NULL. Note that if @match_info is 
not %NULL then it is created even if the function returns %FALSE, 
i.e. you must free it regardless if regular expression actually 
matched.

@string is not copied and is used in #GMatchInfo internally. If 
you use any #GMatchInfo method (except g_match_info_free()) after 
freeing or modifying @string then the behaviour is undefined.

To retrieve all the non-overlapping matches of the pattern in 
string you can use g_match_info_next().

&amp;lt;informalexample&amp;gt;&amp;lt;programlisting&amp;gt;
static void
print_uppercase_words (const gchar *string)
{
/&amp;ast; Print all uppercase-only words. &amp;ast;/
GRegex *regex;
GMatchInfo *match_info;
GError *error = NULL;
&amp;nbsp;
regex = g_regex_new (&quot;[A-Z]+&quot;, 0, 0, NULL);
g_regex_match_full (regex, string, -1, 0, 0, &amp;amp;match_info, &amp;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;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-&amp;gt;message);
g_error_free (error);
}
}
&amp;lt;/programlisting&amp;gt;&amp;lt;/informalexample&amp;gt;


</description>
<parameters>
<parameter name="regex">
<parameter_description> a #GRegex structure from g_regex_new()
</parameter_description>
</parameter>
<parameter name="string">
<parameter_description> the string to scan for matches
</parameter_description>
</parameter>
<parameter name="string_len">
<parameter_description> the length of @string, or -1 if @string is nul-terminated
</parameter_description>
</parameter>
<parameter name="start_position">
<parameter_description> starting index of the string to match
</parameter_description>
</parameter>
<parameter name="match_options">
<parameter_description> match options
</parameter_description>
</parameter>
<parameter name="match_info">
<parameter_description> pointer to location where to store the #GMatchInfo, 
or %NULL if you do not need it
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> location to store the error occuring, or %NULL to ignore errors
</parameter_description>
</parameter>
</parameters>
<return> %TRUE is the string matched, %FALSE otherwise

Since: 2.14
</return>
</function>

<function name="g_get_charset">
<description>
Obtains the character set for the &amp;lt;link linkend=&quot;setlocale&quot;&amp;gt;current 
locale&amp;lt;/link&amp;gt;; you might use this character set as an argument to 
g_convert(), to convert from the current locale&apos;s encoding to some 
other encoding. (Frequently g_locale_to_utf8() and g_locale_from_utf8()
are nice shortcuts, though.)

The return value is %TRUE if the locale&apos;s encoding is UTF-8, in that
case you can perhaps avoid calling g_convert().

The string returned in @charset is not allocated, and should not be
freed.


</description>
<parameters>
<parameter name="charset">
<parameter_description> return location for character set name
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the returned charset is UTF-8
</return>
</function>

<function name="g_key_file_set_string_list">
<description>
Associates a list of string values for @key under @group_name.
If @key cannot be found then it is created.  If @group_name 
cannot be found then it is created.

Since: 2.6

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile
</parameter_description>
</parameter>
<parameter name="group_name">
<parameter_description> a group name
</parameter_description>
</parameter>
<parameter name="key">
<parameter_description> a key
</parameter_description>
</parameter>
<parameter name="list">
<parameter_description> an array of locale string values
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> number of locale string values in @list
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_markup_escape_text">
<description>
Escapes text so that the markup parser will parse it verbatim.
Less than, greater than, ampersand, etc. are replaced with the
corresponding entities. This function would typically be used
when writing out a file to be parsed with the markup parser.

Note that this function doesn&apos;t protect whitespace and line endings
from being processed according to the XML rules for normalization
of line endings and attribute values.


</description>
<parameters>
<parameter name="text">
<parameter_description> some valid UTF-8 text
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> length of @text in bytes, or -1 if the text is nul-terminated
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string with the escaped text
</return>
</function>

<function name="g_option_context_parse">
<description>
Parses the command line arguments, recognizing options
which have been added to @context. A side-effect of 
calling this function is that g_set_prgname() will be
called.

If the parsing is successful, any parsed arguments are
removed from the array and @argc and @argv are updated 
accordingly. A &apos;--&apos; option is stripped from @argv
unless there are unparsed options before and after it, 
or some of the options after it start with &apos;-&apos;. In case 
of an error, @argc and @argv are left unmodified. 

If automatic &amp;lt;option&amp;gt;--help&amp;lt;/option&amp;gt; support is enabled
(see g_option_context_set_help_enabled()), and the 
@argv array contains one of the recognized help options,
this function will produce help output to stdout and
call &amp;lt;literal&amp;gt;exit (0)&amp;lt;/literal&amp;gt;.

Note that function depends on the 
&amp;lt;link linkend=&quot;setlocale&quot;&amp;gt;current locale&amp;lt;/link&amp;gt; for 
automatic character set conversion of string and filename
arguments.


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GOptionContext
</parameter_description>
</parameter>
<parameter name="argc">
<parameter_description> a pointer to the number of command line arguments
</parameter_description>
</parameter>
<parameter name="argv">
<parameter_description> a pointer to the array of command line arguments
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> a return location for errors 
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the parsing was successful, 
%FALSE if an error occurred

Since: 2.6
</return>
</function>

<function name="g_intern_static_string">
<description>
Returns: a canonical representation for the string

</description>
<parameters>
<parameter name="string">
<parameter_description> a static string
</parameter_description>
</parameter>
</parameters>
<return> a canonical representation for the string

Since: 2.10
</return>
</function>

<function name="g_strsplit">
<description>
Splits a string into a maximum of @max_tokens pieces, using the given
@delimiter. If @max_tokens is reached, the remainder of @string is appended
to the last token. 

As 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 a empty vector is typically
more useful than consistent handling of empty elements. If you do need
to represent empty elements, you&apos;ll need to check for the empty string
before calling g_strsplit().


</description>
<parameters>
<parameter name="string">
<parameter_description> a string to split.
</parameter_description>
</parameter>
<parameter name="delimiter">
<parameter_description> a string which specifies the places at which to split the string.
The delimiter is not included in any of the resulting strings, unless
@max_tokens is reached.
</parameter_description>
</parameter>
<parameter name="max_tokens">
<parameter_description> the maximum number of pieces to split @string into. If this is
less than 1, the string is split completely.
</parameter_description>
</parameter>
</parameters>
<return> a newly-allocated %NULL-terminated array of strings. Use 
g_strfreev() to free it.
</return>
</function>

<function name="g_queue_is_empty">
<description>
Returns: %TRUE if the queue is empty.

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue.
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the queue is empty.
</return>
</function>

<function name="g_hash_table_new_full">
<description>
Creates a new #GHashTable like g_hash_table_new() with a reference count
of 1 and allows to specify functions to free the memory allocated for the
key and value that get called when removing the entry from the #GHashTable.


</description>
<parameters>
<parameter name="hash_func">
<parameter_description> a function to create a hash value from a key.
</parameter_description>
</parameter>
<parameter name="key_equal_func">
<parameter_description> a function to check two keys for equality.
</parameter_description>
</parameter>
<parameter name="key_destroy_func">
<parameter_description> a function to free the memory allocated for the key 
used when removing the entry from the #GHashTable or %NULL if you 
don&apos;t want to supply such a function.
</parameter_description>
</parameter>
<parameter name="value_destroy_func">
<parameter_description> a function to free the memory allocated for the 
value used when removing the entry from the #GHashTable or %NULL if 
you don&apos;t want to supply such a function.
</parameter_description>
</parameter>
</parameters>
<return> a new #GHashTable.
</return>
</function>

<function name="g_remove">
<description>
A wrapper for the POSIX remove() function. The remove() function
deletes a name from the filesystem.

See your C library manual for more details about how remove() works
on your system. On Unix, remove() removes also directories, as it
calls unlink() for files and rmdir() for directories. On Windows,
although remove() in the C library only works for files, this
function tries first remove() and then if that fails rmdir(), and
thus works for both files and directories. Note however, that on
Windows, it is in general not possible to remove a file that is
open to some process, or mapped into memory.

If this function fails on Windows you can&apos;t infer too much from the
errno value. rmdir() is tried regardless of what caused remove() to
fail. Any errno value set by remove() will be overwritten by that
set by rmdir().


</description>
<parameters>
<parameter name="filename">
<parameter_description> a pathname in the GLib file name encoding (UTF-8 on Windows)
</parameter_description>
</parameter>
</parameters>
<return> 0 if the file was successfully removed, -1 if an error 
occurred

Since: 2.6
</return>
</function>

<function name="g_regex_get_string_number">
<description>
Retrieves the number of the subexpression named @name.


</description>
<parameters>
<parameter name="regex">
<parameter_description> #GRegex structure
</parameter_description>
</parameter>
<parameter name="name">
<parameter_description> name of the subexpression
</parameter_description>
</parameter>
</parameters>
<return> The number of the subexpression or -1 if @name 
does not exists

Since: 2.14
</return>
</function>

<function name="g_main_context_check">
<description>
Passes the results of polling back to the main loop.


</description>
<parameters>
<parameter name="context">
<parameter_description> a #GMainContext
</parameter_description>
</parameter>
<parameter name="max_priority">
<parameter_description> the maximum numerical priority of sources to check
</parameter_description>
</parameter>
<parameter name="fds">
<parameter_description> array of #GPollFD&apos;s that was passed to the last call to
g_main_context_query()
</parameter_description>
</parameter>
<parameter name="n_fds">
<parameter_description> return value of g_main_context_query()
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if some sources are ready to be dispatched.
</return>
</function>

<function name="g_spawn_command_line_sync">
<description>
A simple version of g_spawn_sync() with little-used parameters
removed, taking a command line instead of an argument vector.  See
g_spawn_sync() for full details. @command_line will be parsed by
g_shell_parse_argv(). Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag
is enabled. Note that %G_SPAWN_SEARCH_PATH can have security
implications, so consider using g_spawn_sync() directly if
appropriate. Possible errors are those from g_spawn_sync() and those
from g_shell_parse_argv().

If @exit_status is non-%NULL, the exit status of the child is stored there as
it would be returned by waitpid(); standard UNIX macros such as WIFEXITED()
and WEXITSTATUS() must be used to evaluate the exit status.

On Windows, please note the implications of g_shell_parse_argv()
parsing @command_line. Parsing is done according to Unix shell rules, not 
Windows command interpreter rules.
Space is a separator, and backslashes are
special. Thus you cannot simply pass a @command_line containing
canonical Windows paths, like &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;&apos;c:\\program files\\app\\app.exe&apos; &apos;e:\\folder\\argument.txt&apos;&quot;.


</description>
<parameters>
<parameter name="command_line">
<parameter_description> a command line 
</parameter_description>
</parameter>
<parameter name="standard_output">
<parameter_description> return location for child output
</parameter_description>
</parameter>
<parameter name="standard_error">
<parameter_description> return location for child errors
</parameter_description>
</parameter>
<parameter name="exit_status">
<parameter_description> return location for child exit status, as returned by waitpid()
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for errors
</parameter_description>
</parameter>
</parameters>
<return> %TRUE on success, %FALSE if an error was set
</return>
</function>

<function name="g_sequence_sort">
<description>
Sorts @seq using @cmp_func.

Since: 2.14

</description>
<parameters>
<parameter name="seq">
<parameter_description> a #GSequence
</parameter_description>
</parameter>
<parameter name="cmp_func">
<parameter_description> the #GCompareDataFunc used to sort @seq. This function is
passed two items of @seq and should return 0 if they are equal,
a negative value fi the first comes before the second, and a
positive value if the second comes before the first.
</parameter_description>
</parameter>
<parameter name="cmp_data">
<parameter_description> user data passed to @cmp_func
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_option_context_set_summary">
<description>
Adds a string to be displayed in &amp;lt;option&amp;gt;--help&amp;lt;/option&amp;gt; output
before the list of options. This is typically a summary of the
program functionality. 

Note that the summary is translated (see 
g_option_context_set_translate_func(), g_option_context_set_translation_domain()).

Since: 2.12

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GOptionContext
</parameter_description>
</parameter>
<parameter name="summary">
<parameter_description> a string to be shown in &amp;lt;option&amp;gt;--help&amp;lt;/option&amp;gt; output 
before the list of options, or %NULL
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_build_filenamev">
<description>
Behaves exactly like g_build_filename(), but takes the path elements 
as a string array, instead of varargs. This function is mainly
meant for language bindings.


</description>
<parameters>
<parameter name="args">
<parameter_description> %NULL-terminated array of strings containing the path elements.
</parameter_description>
</parameter>
</parameters>
<return> a newly-allocated string that must be freed with g_free().

Since: 2.8
</return>
</function>

<function name="g_io_channel_write_chars">
<description>
Replacement for g_io_channel_write() with the new API.

On seekable channels with encodings other than %NULL or UTF-8, generic
mixing of reading and writing is not allowed. A call to g_io_channel_write_chars ()
may only be made on a channel from which data has been read in the
cases described in the documentation for g_io_channel_set_encoding ().


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
<parameter name="buf">
<parameter_description> a buffer to write data from
</parameter_description>
</parameter>
<parameter name="count">
<parameter_description> the size of the buffer. If -1, the buffer
is taken to be a nul-terminated string.
</parameter_description>
</parameter>
<parameter name="bytes_written">
<parameter_description> The number of bytes written. This can be nonzero
even if the return value is not %G_IO_STATUS_NORMAL.
If the return value is %G_IO_STATUS_NORMAL and the
channel is blocking, this will always be equal
to @count if @count &amp;gt;= 0.
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> A location to return an error of type #GConvertError
or #GIOChannelError
</parameter_description>
</parameter>
</parameters>
<return> the status of the operation.
</return>
</function>

<function name="g_io_channel_get_flags">
<description>
Gets the current flags for a #GIOChannel, including read-only
flags such as %G_IO_FLAG_IS_READABLE.

The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITEABLE
are cached for internal use by the channel when it is created.
If they should change at some later point (e.g. partial shutdown
of a socket with the UNIX shutdown() function), the user
should immediately call g_io_channel_get_flags () to update
the internal values of these flags.


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
</parameters>
<return> the flags which are set on the channel
</return>
</function>

<function name="g_locale_from_utf8">
<description>
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 &amp;lt;link linkend=&quot;setlocale&quot;&amp;gt;current locale&amp;lt;/link&amp;gt;.


</description>
<parameters>
<parameter name="utf8string">
<parameter_description>    a UTF-8 encoded string 
</parameter_description>
</parameter>
<parameter name="len">
<parameter_description>           the length of the string, or -1 if the string is
nul-terminated&amp;lt;footnoteref linkend=&quot;nul-unsafe&quot;/&amp;gt;. 
</parameter_description>
</parameter>
<parameter name="bytes_read">
<parameter_description>    location to store the number of bytes in the
input string that were successfully converted, or %NULL.
Even if the conversion was successful, this may be 
less than @len if there were partial characters
at the end of the input. If the error
#G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
stored will the byte offset after the last valid
input sequence.
</parameter_description>
</parameter>
<parameter name="bytes_written">
<parameter_description> the number of bytes stored in the output buffer (not 
including the terminating nul).
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description>         location to store the error occuring, or %NULL to ignore
errors. Any of the errors in #GConvertError may occur.
</parameter_description>
</parameter>
</parameters>
<return> The converted string, or %NULL on an error.
</return>
</function>

<function name="g_key_file_set_list_separator">
<description>
Sets the character which is used to separate
values in lists. Typically &apos;;&apos; or &apos;,&apos; are used
as separators. The default list separator is &apos;;&apos;.

Since: 2.6

</description>
<parameters>
<parameter name="key_file">
<parameter_description> a #GKeyFile 
</parameter_description>
</parameter>
<parameter name="separator">
<parameter_description> the separator
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_tree_new">
<description>
Creates a new #GTree.


</description>
<parameters>
<parameter name="key_compare_func">
<parameter_description> the function used to order the nodes in the #GTree.
It should return values similar to the standard strcmp() function -
0 if the two arguments are equal, a negative value if the first argument 
comes before the second, or a positive value if the first argument comes 
after the second.
</parameter_description>
</parameter>
</parameters>
<return> a new #GTree.
</return>
</function>

<function name="g_timeout_add">
<description>
Sets a function to be called at regular intervals, with the default
priority, #G_PRIORITY_DEFAULT.  The function is called repeatedly
until it returns %FALSE, at which point the timeout is automatically
destroyed and the function will not be called again.  The first call
to the function will be at the end of the first @interval.

Note that timeout functions may be delayed, due to the processing of other
event sources. Thus they should not be relied on for precise timing.
After each call to the timeout function, the time of the next
timeout is recalculated based on the current time and the given interval
(it does not try to &apos;catch up&apos; time lost in delays).

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
g_timeout_add_seconds() function; this function allows for more
optimizations and more efficient system power usage.


</description>
<parameters>
<parameter name="interval">
<parameter_description> the time between calls to the function, in milliseconds
(1/1000ths of a second)
</parameter_description>
</parameter>
<parameter name="function">
<parameter_description> function to call
</parameter_description>
</parameter>
<parameter name="data">
<parameter_description>     data to pass to @function
</parameter_description>
</parameter>
</parameters>
<return> the ID (greater than 0) of the event source.
</return>
</function>

<function name="g_mapped_file_get_length">
<description>
Returns: the length of the contents of @file.

</description>
<parameters>
<parameter name="file">
<parameter_description> a #GMappedFile
</parameter_description>
</parameter>
</parameters>
<return> the length of the contents of @file.

Since: 2.8
</return>
</function>

<function name="g_key_file_load_from_file">
<description>
Loads a key file into an empty #GKeyFile structure.
If the file could not be loaded then %error is set to 
either a #GFileError or #GKeyFileError.


</description>
<parameters>
<parameter name="key_file">
<parameter_description> an empty #GKeyFile struct
</parameter_description>
</parameter>
<parameter name="file">
<parameter_description> the path of a filename to load, in the GLib file name encoding
</parameter_description>
</parameter>
<parameter name="flags">
<parameter_description> flags from #GKeyFileFlags
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if a key file could be loaded, %FALSE othewise
Since: 2.6
</return>
</function>

<function name="g_queue_init">
<description>
A statically-allocated #GQueue must be initialized with this function
before it can be used. Alternatively you can initialize it with
#G_QUEUE_INIT. It is not necessary to initialize queues created with
g_queue_new().

Since: 2.14

</description>
<parameters>
<parameter name="queue">
<parameter_description> an uninitialized #GQueue
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_queue_delete_link">
<description>
Removes @link_ from @queue and frees it.

@link_ must be part of @queue.

Since: 2.4

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="link_">
<parameter_description> a #GList link that &amp;lt;emphasis&amp;gt;must&amp;lt;/emphasis&amp;gt; be part of @queue
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_queue_reverse">
<description>
Reverses the order of the items in @queue.

Since: 2.4

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_async_queue_length">
<description>
Return value: the length of the @queue.

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GAsyncQueue.
</parameter_description>
</parameter>
</parameters>
<return> the length of the @queue.
</return>
</function>

<function name="g_ascii_strtoll">
<description>
Converts a string to a #gint64 value.
This function behaves like the standard strtoll() function
does in the C locale. It does this without actually
changing the current locale, since that would not be
thread-safe.

This function is typically used when reading configuration
files or other non-user input that should be locale independent.
To handle input from the user you should normally use the
locale-sensitive system strtoll() function.

If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64
is returned, and %ERANGE is stored in %errno.  If the base is
outside the valid range, zero is returned, and %EINVAL is stored
in %errno.  If the string conversion fails, zero is returned, and
@endptr returns @nptr (if @endptr is non-%NULL).


</description>
<parameters>
<parameter name="nptr">
<parameter_description>    the string to convert to a numeric value.
</parameter_description>
</parameter>
<parameter name="endptr">
<parameter_description>  if non-%NULL, it returns the character after
the last character used in the conversion.
</parameter_description>
</parameter>
<parameter name="base">
<parameter_description>    to be used for the conversion, 2..36 or 0
</parameter_description>
</parameter>
</parameters>
<return> the #gint64 value or zero on error.

Since: 2.12
</return>
</function>

<function name="g_regex_escape_string">
<description>
Escapes the special characters used for regular expressions 
in @string, for instance &quot;a.b*c&quot; becomes &quot;a\.b\*c&quot;. This 
function is useful to dynamically generate regular expressions.

@string can contain nul characters that are replaced with &quot;\0&quot;, 
in this case remember to specify the correct length of @string 
in @length.


</description>
<parameters>
<parameter name="string">
<parameter_description> the string to escape
</parameter_description>
</parameter>
<parameter name="length">
<parameter_description> the length of @string, or -1 if @string is nul-terminated
</parameter_description>
</parameter>
</parameters>
<return> a newly-allocated escaped string

Since: 2.14
</return>
</function>

<function name="g_io_channel_read_unichar">
<description>
This function cannot be called on a channel with %NULL encoding.


</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
<parameter name="thechar">
<parameter_description> a location to return a character
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> A location to return an error of type #GConvertError
or #GIOChannelError
</parameter_description>
</parameter>
</parameters>
<return> a #GIOStatus
</return>
</function>

<function name="g_mkdir">
<description>
A wrapper for the POSIX mkdir() function. The mkdir() function 
attempts to create a directory with the given name and permissions.
The mode argument is ignored on Windows.

See the C library manual for more details about mkdir().


</description>
<parameters>
<parameter name="filename">
<parameter_description> a pathname in the GLib file name encoding (UTF-8 on Windows)
</parameter_description>
</parameter>
<parameter name="mode">
<parameter_description> permissions to use for the newly created directory
</parameter_description>
</parameter>
</parameters>
<return> 0 if the directory was successfully created, -1 if an error 
occurred

Since: 2.6
</return>
</function>

<function name="g_option_context_get_summary">
<description>
Returns: the summary

</description>
<parameters>
<parameter name="context">
<parameter_description> a #GOptionContext
</parameter_description>
</parameter>
</parameters>
<return> the summary

Since: 2.12
</return>
</function>

<function name="g_time_val_to_iso8601">
<description>
Converts @time_ into a ISO 8601 encoded string, relative to the
Coordinated Universal Time (UTC).


</description>
<parameters>
<parameter name="time_">
<parameter_description> a #GTimeVal
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string containing a ISO 8601 date

Since: 2.12
</return>
</function>

<function name="g_get_user_special_dir">
<description>
Return value: the path to the specified special directory, or %NULL

</description>
<parameters>
<parameter name="directory">
<parameter_description> the logical id of special directory
</parameter_description>
</parameter>
</parameters>
<return> the path to the specified special directory, or %NULL
if the logical id was not found. The returned string is owned by
GLib and should not be modified or freed.

Since: 2.14
</return>
</function>

<function name="g_source_set_funcs">
<description>
Sets the source functions (can be used to override 
default implementations) of an unattached source.

Since: 2.12

</description>
<parameters>
<parameter name="source">
<parameter_description> a #GSource
</parameter_description>
</parameter>
<parameter name="funcs">
<parameter_description> the new #GSourceFuncs
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_regex_match_all">
<description>
Using the standard algorithm for regular expression matching only 
the longest match in the string is retrieved. This function uses 
a different algorithm so it can retrieve all the possible matches.
For more documentation see g_regex_match_all_full().

A #GMatchInfo structure, used to get information on the match, is 
stored in @match_info if not %NULL. Note that if @match_info is 
not %NULL then it is created even if the function returns %FALSE, 
i.e. you must free it regardless if regular expression actually 
matched.


</description>
<parameters>
<parameter name="regex">
<parameter_description> a #GRegex structure from g_regex_new()
</parameter_description>
</parameter>
<parameter name="string">
<parameter_description> the string to scan for matches
</parameter_description>
</parameter>
<parameter name="match_options">
<parameter_description> match options
</parameter_description>
</parameter>
<parameter name="match_info">
<parameter_description> pointer to location where to store the #GMatchInfo, 
or %NULL if you do not need it
</parameter_description>
</parameter>
</parameters>
<return> %TRUE is the string matched, %FALSE otherwise

Since: 2.14
</return>
</function>

<function name="g_direct_hash">
<description>
Converts a gpointer to a hash value.
It can be passed to g_hash_table_new() as the @hash_func parameter, 
when using pointers as keys in a #GHashTable.


</description>
<parameters>
<parameter name="v">
<parameter_description> a #gpointer key
</parameter_description>
</parameter>
</parameters>
<return> a hash value corresponding to the key.
</return>
</function>

<function name="g_unichar_isalpha">
<description>
Determines whether a character is alphabetic (i.e. a letter).
Given some UTF-8 text, obtain a character value with
g_utf8_get_char().


</description>
<parameters>
<parameter name="c">
<parameter_description> a Unicode character
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if @c is an alphabetic character
</return>
</function>

<function name="g_queue_unlink">
<description>
Unlinks @link_ so that it will no longer be part of @queue. The link is
not freed.

@link_ must be part of @queue,

Since: 2.4

</description>
<parameters>
<parameter name="queue">
<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="link_">
<parameter_description> a #GList link that &amp;lt;emphasis&amp;gt;must&amp;lt;/emphasis&amp;gt; be part of @queue
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_bookmark_file_get_visited">
<description>
Gets the time the bookmark for @uri was last visited.

In the event the URI cannot be found, -1 is returned and
@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.


</description>
<parameters>
<parameter name="bookmark">
<parameter_description> a #GBookmarkFile
</parameter_description>
</parameter>
<parameter name="uri">
<parameter_description> a valid URI
</parameter_description>
</parameter>
<parameter name="error">
<parameter_description> return location for a #GError, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> a timestamp.

Since: 2.12
</return>
</function>

<function name="g_io_channel_set_buffered">
<description>
The buffering state can only be set if the channel&apos;s encoding
is %NULL. For any other encoding, the channel must be buffered.

A buffered channel can only be set unbuffered if the channel&apos;s
internal buffers have been flushed. Newly created channels or
channels which have returned %G_IO_STATUS_EOF
not require such a flush. For write-only channels, a call to
g_io_channel_flush () is sufficient. For all other channels,
the buffers may be flushed by a call to g_io_channel_seek_position ().
This includes the possibility of seeking with seek type %G_SEEK_CUR
and an offset of zero. Note that this means that socket-based
channels cannot be set unbuffered once they have had data
read from them.

On unbuffered channels, it is safe to mix read and write
calls from the new and old APIs, if this is necessary for
maintaining old code.

The default state of the channel is buffered.

</description>
<parameters>
<parameter name="channel">
<parameter_description> a #GIOChannel
</parameter_description>
</parameter>
<parameter name="buffered">
<parameter_description> whether to set the channel buffered or unbuffered
</parameter_description>
</parameter>
</parameters>
<return></return>
</function>

<function name="g_key_file_new">
<description>
Creates a new empty #GKeyFile object. Use
g_key_file_load_from_file(), g_key_file_load_from_data(),
g_key_file_load_from_dirs() or g_key_file_load_from_data_dirs() to
read an existing key file.


</description>
<parameters>
</parameters>
<return> an empty #GKeyFile.

Since: 2.6
</return>
</function>

</root>