+Thu Sep 7 12:35:35 2000 Owen Taylor <otaylor@redhat.com>
+
+ * Some further makefile improvement.
+
+ * Restore all the docs that mysteriously vanished earlier.
+
Wed Sep 6 10:59:45 2000 Owen Taylor <otaylor@redhat.com>
* gobject/Makefile.am glib/Makefile.am: Improve
# The directory containing the source code
DOC_SOURCE_DIR=$(top_srcdir)
+# Extra options to supply to gtkdoc-fixref
+FIXXREF_OPTIONS=
+
# Headers to ignore
IGNORE_HFILES= \
gobject \
test -d $(srcdir)/html || mkdir $(srcdir)/html
-cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
@echo '-- Fixing Crossreferences'
- gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR)
+ gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIOJNS)
clean-local:
rm -f *~ *.bak *.signals *-unused.txt
G_STRUCT_MEMBER
G_STRUCT_MEMBER_P
G_STRUCT_OFFSET
+
+<SUBSECTION Private>
+glib_major_version
+glib_micro_version
+glib_minor_version
+glib_interface_age
+glib_binary_age
</SECTION>
<SECTION>
glib_dummy_decl
GSystemThread
g_thread_error_quark
+g_thread_use_default_impl
+g_threads_got_initialized
+g_thread_functions_for_glib_use
</SECTION>
<SECTION>
Memory Allocators
<!-- ##### SECTION Short_Description ##### -->
-
+allocates chunks of memory for #GList, #GSList and #GNode.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GAllocator is used as an efficient way to allocate small pieces of
+memory for use with the #GList, #GSList and #GNode data structures.
+It uses a #GMemChunk so elements are allocated in groups, rather than
+individually.
+</para>
+<para>
+The #GList, #GSList and #GNode implementations create default #GAllocator
+objects, which are probably sufficient for most purposes. These default
+allocators use blocks of 128 elements.
+</para>
+<para>
+To use your own #GAllocator, create it with g_allocator_new(). Then
+use g_list_push_allocator(), g_slist_push_allocator() or
+g_node_push_allocator() before any code which allocates new #GList, #GSList
+or #GNode elements respectively. After allocating the new elements, you must
+use g_list_pop_allocator(), g_slist_pop_allocator() or g_node_pop_allocator()
+to restore the previous allocators.
+</para>
+<para>
+Note that you cannot use the same allocator for #GList, #GSList and #GNode
+elements. Each must use separate allocators.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GAllocator ##### -->
<para>
-
+The #GAllocator struct contains private data. and should only be accessed
+using the following functions.
</para>
<!-- ##### FUNCTION g_allocator_new ##### -->
<para>
-
+Creates a new #GAllocator.
</para>
-@name:
-@n_preallocs:
-@Returns:
+@name: the name of the #GAllocator. This name is used to set the name of the
+#GMemChunk used by the #GAllocator, and is only used for debugging.
+@n_preallocs: the number of elements in each block of memory allocated.
+Larger blocks mean less calls to g_malloc(), but some memory may be wasted.
+(GLib uses 128 elements per block by default.) The value must be between 1
+and 65535.
+@Returns: a new #GAllocator.
<!-- ##### FUNCTION g_allocator_free ##### -->
<para>
-
+Frees all of the memory allocated by the #GAllocator.
</para>
-@allocator:
+@allocator: a #GAllocator.
Arrays
<!-- ##### SECTION Short_Description ##### -->
-
+arrays of arbitrary elements which grow automatically as elements are added.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+Arrays are similar to standard C arrays, except that they grow automatically
+as elements are added.
+</para>
+<para>
+Array elements can be of any size (though all elements of one array are the
+same size), and the array can be automatically cleared to '0's and
+zero-terminated.
+</para>
+<para>
+To create a new array use g_array_new().
+</para>
+<para>
+To add elements to an array, use g_array_append_val(), g_array_append_vals(),
+g_array_prepend_val(), and g_array_prepend_vals().
+</para>
+<para>
+To access an element of an array, use g_array_index().
+</para>
+<para>
+To set the size of an array, use g_array_set_size().
</para>
+<para>
+To free an array, use g_array_free().
+</para>
+<example>
+<title>Using a GArray to store gint values.</title>
+<programlisting>
+ GArray *garray;
+ gint i;
+
+ /* We create a new array to store gint values.
+ We don't want it zero-terminated or cleared to 0's. */
+ garray = g_array_new (FALSE, FALSE, sizeof (gint));
+ for (i = 0; i < 10000; i++)
+ g_array_append_val (garray, i);
+
+ for (i = 0; i < 10000; i++)
+ if (g_array_index (garray, gint, i) != i)
+ g_print ("ERROR: got %d instead of %d\n",
+ g_array_index (garray, gint, i), i);
+
+ g_array_free (garray, TRUE);
+</programlisting></example>
<!-- ##### SECTION See_Also ##### -->
<para>
<!-- ##### STRUCT GArray ##### -->
<para>
-
+Contains the public fields of an <link linkend="glib-arrays">Array</link>.
</para>
-@data:
-@len:
+@data: a pointer to the element data. The data may be moved as elements are
+added to the #GArray.
+@len: the number of elements in the #GArray.
<!-- ##### FUNCTION g_array_new ##### -->
<para>
-
+Creates a new #GArray.
</para>
-@zero_terminated:
-@clear:
-@element_size:
-@Returns:
+@zero_terminated: TRUE if the array should have an extra element at the end
+which is set to '0'.
+@clear: TRUE if #GArray elements should be automatically cleared to '0'
+when they are allocated.
+@element_size: the size of each element in bytes.
+@Returns: the new #GArray.
<!-- ##### FUNCTION g_array_sized_new ##### -->
<!-- ##### MACRO g_array_append_val ##### -->
<para>
-
+Adds the value on to the end of the array.
+The array will grow in size automatically if necessary.
</para>
+<note>
+<para>
+g_array_append_val() is a macro which uses a reference to the value
+parameter @v. This means that you cannot use it with literal values
+such as "27". You must use variables.
+</para>
+</note>
-@a:
-@v:
+@a: a #GArray.
+@v: the value to append to the #GArray.
+@Returns: the #GArray.
<!-- ##### FUNCTION g_array_append_vals ##### -->
<para>
-
+Adds @len elements onto the end of the array.
</para>
-@array:
-@data:
-@len:
-@Returns:
+@array: a #GArray.
+@data: a pointer to the elements to append to the end of the array.
+@len: the number of elements to append.
+@Returns: the #GArray.
<!-- ##### MACRO g_array_prepend_val ##### -->
<para>
-
+Adds the value on to the start of the array.
+The array will grow in size automatically if necessary.
+</para>
+<para>
+This operation is slower than g_array_append_val() since the existing elements
+in the array have to be moved to make space for the new element.
+</para>
+<note>
+<para>
+g_array_prepend_val() is a macro which uses a reference to the value
+parameter @v. This means that you cannot use it with literal values
+such as "27". You must use variables.
</para>
+</note>
-@a:
-@v:
+@a: a #GArray.
+@v: the value to prepend to the #GArray.
+@Returns: the #GArray.
<!-- ##### FUNCTION g_array_prepend_vals ##### -->
<para>
-
+Adds @len elements onto the start of the array.
+</para>
+<para>
+This operation is slower than g_array_append_vals() since the existing elements
+in the array have to be moved to make space for the new elements.
</para>
-@array:
-@data:
-@len:
-@Returns:
+@array: a #GArray.
+@data: a pointer to the elements to prepend to the start of the array.
+@len: the number of elements to prepend.
+@Returns: the #GArray.
<!-- ##### MACRO g_array_insert_val ##### -->
<para>
-
+Inserts an element into an array at the given index.
</para>
+<note>
+<para>
+g_array_insert_val() is a macro which uses a reference to the value
+parameter @v. This means that you cannot use it with literal values
+such as "27". You must use variables.
+</para>
+</note>
-@a:
-@i:
-@v:
+@a: a #GArray.
+@i: the index to place the element at.
+@v: the value to insert into the array.
+@Returns: the #GArray.
<!-- ##### FUNCTION g_array_insert_vals ##### -->
<para>
-
+Inserts @len elements into a #GArray at the given index.
</para>
-@array:
-@index:
-@data:
-@len:
-@Returns:
+@array: a #GArray.
+@index: the index to place the elements at.
+@data: a pointer to the elements to insert.
+@len: the number of elements to insert.
+@Returns: the #GArray.
<!-- ##### FUNCTION g_array_remove_index ##### -->
<para>
-
+Removes the element at the given index from a #GArray.
+The following elements are moved down one place.
</para>
-@array:
-@index:
-@Returns:
+@array: a #GArray.
+@index: the index of the element to remove.
+@Returns: the #GArray.
<!-- ##### FUNCTION g_array_remove_index_fast ##### -->
<para>
-
+Removes the element at the given index from a #GArray.
+The last element in the array is used to fill in the space, so this function
+does not preserve the order of the #GArray. But it is faster than
+g_array_remove_index().
</para>
-@array:
-@index:
-@Returns:
+@array: a @GArray.
+@index: the index of the element to remove.
+@Returns: the #GArray.
<!-- ##### MACRO g_array_index ##### -->
<para>
-
+Returns the element of a #GArray at the given index.
+The return value is cast to the given type.
+
+<example>
+<title>Getting a pointer to an element in a GArray.</title>
+<programlisting>
+ EDayViewEvent *event;
+
+ /* This gets a pointer to the 3rd element in the array of EDayViewEvent
+ structs. */
+ event = &g_array_index (events, EDayViewEvent, 3);
+</programlisting>
+</example>
</para>
-@a:
-@t:
-@i:
+@a: a #GArray.
+@t: the type of the elements.
+@i: the index of the element to return.
+@Returns: the element of the #GArray at the index given by @i.
<!-- ##### FUNCTION g_array_set_size ##### -->
<para>
-
+Sets the size of the array, expanding it if necessary.
+If the array was created with clear set to TRUE, the new elements are set to 0.
</para>
-@array:
-@length:
-@Returns:
+@array: a #GArray.
+@length: the new size of the #GArray.
+@Returns: the #GArray.
<!-- ##### FUNCTION g_array_free ##### -->
<para>
-
+Frees the memory allocated for the #GArray.
+If free_segment is TRUE it frees the actual element data as well.
</para>
-@array:
-@free_segment:
+@array: a #GArray.
+@free_segment: if TRUE the actual element data is freed as well.
@Returns:
Byte Arrays
<!-- ##### SECTION Short_Description ##### -->
-
+arrays of bytes, which grow automatically as elements are added.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+GByteArray is based on #GArray, to provide arrays of bytes which grow
+automatically as elements are added.
+</para>
+<para>
+To create a new #GByteArray use g_byte_array_new().
+</para>
+<para>
+To add elements to a #GByteArray, use g_byte_array_append(), and
+g_byte_array_prepend().
+</para>
+<para>
+To set the size of a GByteArray, use g_byte_array_set_size().
+</para>
+<para>
+To free a GByteArray, use g_byte_array_free().
</para>
+<example>
+<title>Using a GByteArray.</title>
+<programlisting>
+ GByteArray *gbarray;
+ gint i;
+
+ gbarray = g_byte_array_new ();
+ for (i = 0; i < 10000; i++)
+ g_byte_array_append (gbarray, (guint8*) "abcd", 4);
+
+ for (i = 0; i < 10000; i++)
+ {
+ g_assert (gbarray->data[4*i] == 'a');
+ g_assert (gbarray->data[4*i+1] == 'b');
+ g_assert (gbarray->data[4*i+2] == 'c');
+ g_assert (gbarray->data[4*i+3] == 'd');
+ }
+
+ g_byte_array_free (gbarray, TRUE);
+</programlisting></example>
+
<!-- ##### SECTION See_Also ##### -->
<para>
<!-- ##### STRUCT GByteArray ##### -->
<para>
-
+The #GByteArray struct allows access to the public fields of a #GByteArray.
</para>
-@data:
-@len:
+@data: a pointer to the element data. The data may be moved as elements are
+added to the #GByteArray.
+@len: the number of elements in the #GByteArray.
<!-- ##### FUNCTION g_byte_array_new ##### -->
<para>
-
+Creates a new #GByteArray.
</para>
-@Returns:
+@Returns: the new #GByteArray.
<!-- ##### FUNCTION g_byte_array_sized_new ##### -->
<!-- ##### FUNCTION g_byte_array_append ##### -->
<para>
-
+Adds the given bytes to the end of the #GByteArray.
+The array will grow in size automatically if necessary.
</para>
-@array:
-@data:
-@len:
-@Returns:
+@array: a #GByteArray.
+@data: the byte data to be added.
+@len: the number of bytes to add.
+@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_prepend ##### -->
<para>
-
+Adds the given data to the start of the #GByteArray.
+The array will grow in size automatically if necessary.
</para>
-@array:
-@data:
-@len:
-@Returns:
+@array: a #GByteArray.
+@data: the byte data to be added.
+@len: the number of bytes to add.
+@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_remove_index ##### -->
<para>
-
+Removes the byte at the given index from a #GByteArray.
+The following bytes are moved down one place.
</para>
-@array:
-@index:
-@Returns:
+@array: a #GByteArray.
+@index: the index of the byte to remove.
+@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_remove_index_fast ##### -->
<para>
-
+Removes the byte at the given index from a #GByteArray.
+The last element in the array is used to fill in the space, so this function
+does not preserve the order of the #GByteArray. But it is faster than
+g_byte_array_remove_index().
</para>
-@array:
-@index:
-@Returns:
+@array: a #GByteArray.
+@index: the index of the byte to remove.
+@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_set_size ##### -->
<para>
-
+Sets the size of the #GByteArray, expanding it if necessary.
</para>
-@array:
-@length:
-@Returns:
+@array: a #GByteArray.
+@length: the new size of the #GByteArray.
+@Returns: the #GByteArray.
<!-- ##### FUNCTION g_byte_array_free ##### -->
<para>
-
+Frees the memory allocated by the #GByteArray.
+If free_segment is TRUE it frees the actual byte data.
</para>
-@array:
-@free_segment:
+@array: a #GByteArray.
+@free_segment: if TRUE the actual byte data is freed as well.
@Returns:
Pointer Arrays
<!-- ##### SECTION Short_Description ##### -->
-
+arrays of pointers to any type of data, which grow automatically as new
+elements are added.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+Pointer Arrays are similar to Arrays but are used only for storing pointers.
+</para>
+<note>
+<para>
+If you remove elements from the array, elements at the end of the array
+are moved into the space previously occupied by the removed element.
+This means that you should not rely on the index of particular elements
+remaining the same. You should also be careful when deleting elements while
+iterating over the array.
+</para>
+</note>
+<para>
+To create a pointer array, use g_ptr_array_new().
+</para>
+<para>
+To add elements to a pointer array, use g_ptr_array_add().
+</para>
+<para>
+To remove elements from a pointer array, use g_ptr_array_remove(),
+g_ptr_array_remove_index() or g_ptr_array_remove_index_fast().
</para>
+<para>
+To access an element of a pointer array, use g_ptr_array_index().
+</para>
+<para>
+To set the size of a pointer array, use g_ptr_array_set_size().
+</para>
+<para>
+To free a pointer array, use g_ptr_array_free().
+</para>
+<example>
+<title>Using a GPtrArray.</title>
+<programlisting>
+ GPtrArray *gparray;
+ gchar *string1 = "one", *string2 = "two", *string3 = "three";
+
+ gparray = g_ptr_array_new ();
+ g_ptr_array_add (gparray, (gpointer) string1);
+ g_ptr_array_add (gparray, (gpointer) string2);
+ g_ptr_array_add (gparray, (gpointer) string3);
+
+ if (g_ptr_array_index (gparray, 0) != (gpointer) string1)
+ g_print ("ERROR: got %p instead of %p\n",
+ g_ptr_array_index (gparray, 0), string1);
+
+ g_ptr_array_free (gparray, TRUE);
+</programlisting></example>
<!-- ##### SECTION See_Also ##### -->
<para>
<!-- ##### STRUCT GPtrArray ##### -->
<para>
-
+Contains the public fields of a pointer array.
+The <structfield>pdata</structfield> field points to the array of pointers,
+which may as when the array grows.
+The <structfield>len</structfield> field is the number of pointers in the
+array.
</para>
@pdata:
<!-- ##### FUNCTION g_ptr_array_new ##### -->
<para>
-
+Creates a new #GPtrArray.
</para>
-@Returns:
+@Returns: the new #GPtrArray.
<!-- ##### FUNCTION g_ptr_array_sized_new ##### -->
<!-- ##### FUNCTION g_ptr_array_add ##### -->
<para>
-
+Adds a pointer to the end of the pointer array.
+The array will grow in size automatically if necessary.
</para>
-@array:
-@data:
+@array: a #GPtrArray.
+@data: the pointer to add.
<!-- ##### FUNCTION g_ptr_array_remove ##### -->
<para>
-
+Removes the first occurrence of the given pointer from the pointer array.
+The following elements are moved down one place.
+</para>
+<para>
+It returns TRUE if the pointer was removed, or FALSE if the pointer
+was not found.
</para>
-@array:
-@data:
-@Returns:
+@array: a #GPtrArray.
+@data: the pointer to remove.
+@Returns: TRUE if the pointer is removed. FALSE if the pointer is not found
+in the array.
<!-- ##### FUNCTION g_ptr_array_remove_index ##### -->
<para>
-
+Removes the pointer at the given index from the pointer array.
+The following elements are moved down one place.
</para>
-@array:
-@index:
-@Returns:
+@array: a #GPtrArray.
+@index: the index of the pointer to remove.
+@Returns: the pointer which was removed.
<!-- ##### FUNCTION g_ptr_array_remove_fast ##### -->
<para>
-
+Removes the first occurrence of the given pointer from the pointer array.
+The last element in the array is used to fill in the space, so this function
+does not preserve the order of the array. But it is faster than
+g_ptr_array_remove().
+</para>
+<para>
+It returns TRUE if the pointer was removed, or FALSE if the pointer
+was not found.
</para>
-@array:
-@data:
-@Returns:
+@array: a #GPtrArray.
+@data: the pointer to remove.
+@Returns: TRUE if the pointer was found in the array.
<!-- ##### FUNCTION g_ptr_array_remove_index_fast ##### -->
<para>
-
+Removes the pointer at the given index from the pointer array.
+The last element in the array is used to fill in the space, so this function
+does not preserve the order of the array. But it is faster than
+g_ptr_array_remove_index().
</para>
-@array:
-@index:
-@Returns:
+@array: a #GPtrArray.
+@index: the index of the pointer to remove.
+@Returns: the pointer which was removed.
<!-- ##### FUNCTION g_ptr_array_set_size ##### -->
<para>
-
+Sets the size of the array, expanding it if necessary.
+New elements are set to NULL.
</para>
-@array:
-@length:
+@array: a #GPtrArray.
+@length: the new length of the pointer array.
<!-- ##### MACRO g_ptr_array_index ##### -->
<para>
-
+Returns the pointer at the given index of the pointer array.
</para>
-@array:
-@index:
+@array: a #GPtrArray.
+@index: the index of the pointer to return.
+@Returns: the pointer at the given index.
<!-- ##### FUNCTION g_ptr_array_free ##### -->
<para>
-
+Frees all of the memory allocated for the pointer array.
</para>
-@array:
-@free_seg:
+@array: a #GPtrArray.
+@free_seg: if TRUE the actual element data is freed as well.
@Returns:
Byte Order Macros
<!-- ##### SECTION Short_Description ##### -->
-
+a portable way to convert between different byte orders.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+These macros provide a portable way to determine the host byte order
+and to convert values between different byte orders.
+</para>
+<para>
+The byte order is the order in which bytes are stored to create larger
+data types such as the #gint and #glong values.
+The host byte order is the byte order used on the current machine.
+</para>
+<para>
+Some processors store the most significant bytes (i.e. the bytes that
+hold the largest part of the value) first. These are known as big-endian
+processors.
+</para>
+<para>
+Other processors (notably the x86 family) store the most significant byte
+last. These are known as little-endian processors.
+</para>
+<para>
+Finally, to complicate matters, some other processors store the bytes in
+a rather curious order known as PDP-endian. For a 4-byte word, the 3rd
+most significant byte is stored first, then the 4th, then the 1st and finally
+the 2nd.
+</para>
+<para>
+Obviously there is a problem when these different processors communicate
+with each other, for example over networks or by using binary file formats.
+This is where these macros come in.
+They are typically used to convert values into a byte order
+which has been agreed on for use when communicating between different
+processors. The Internet uses what is known as 'network byte order'
+as the standard byte order (which is in fact the big-endian byte order).
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### MACRO G_BYTE_ORDER ##### -->
<para>
-
+The host byte order.
+This can be either #G_LITTLE_ENDIAN or #G_BIG_ENDIAN (support for
+#G_PDP_ENDIAN may be added in future.)
</para>
<!-- ##### MACRO G_LITTLE_ENDIAN ##### -->
<para>
-
+Specifies one of the possible types of byte order.
+See #G_BYTE_ORDER.
</para>
<!-- ##### MACRO G_BIG_ENDIAN ##### -->
<para>
-
+Specifies one of the possible types of byte order.
+See #G_BYTE_ORDER.
</para>
<!-- ##### MACRO G_PDP_ENDIAN ##### -->
<para>
-
+Specifies one of the possible types of byte order (currently unused).
+See #G_BYTE_ORDER.
</para>
<!-- ##### MACRO g_htonl ##### -->
<para>
-
+Converts a 32-bit integer value from host to network byte order.
</para>
-@val:
+@val: a 32-bit integer value in host byte order.
+@Returns: @val converted to network byte order.
<!-- ##### MACRO g_htons ##### -->
<para>
-
+Converts a 16-bit integer value from host to network byte order.
</para>
-@val:
+@val: a 16-bit integer value in host byte order.
+@Returns: @val converted to network byte order.
<!-- ##### MACRO g_ntohl ##### -->
<para>
-
+Converts a 32-bit integer value from network to host byte order.
</para>
-@val:
+@val: a 32-bit integer value in network byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO g_ntohs ##### -->
<para>
-
+Converts a 16-bit integer value from network to host byte order.
</para>
-@val:
+@val: a 16-bit integer value in network byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT_FROM_BE ##### -->
<para>
-
+Converts a #gint value from big-endian to host byte order.
</para>
-@val:
+@val: a #gint value in big-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT_FROM_LE ##### -->
<para>
-
+Converts a #gint value from little-endian to host byte order.
</para>
-@val:
+@val: a #gint value in little-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT_TO_BE ##### -->
<para>
-
+Converts a #gint value from host byte order to big-endian.
</para>
-@val:
+@val: a #gint value in host byte order.
+@Returns: @val converted to big-endian byte order.
<!-- ##### MACRO GINT_TO_LE ##### -->
<para>
-
+Converts a #gint value from host byte order to little-endian.
</para>
-@val:
+@val: a #gint value in host byte order.
+@Returns: @val converted to little-endian byte order.
<!-- ##### MACRO GUINT_FROM_BE ##### -->
<para>
-
+Converts a #guint value from big-endian to host byte order.
</para>
-@val:
+@val: a #guint value in big-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GUINT_FROM_LE ##### -->
<para>
-
+Converts a #guint value from little-endian to host byte order.
</para>
-@val:
+@val: a #guint value in little-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GUINT_TO_BE ##### -->
<para>
-
+Converts a #guint value from host byte order to big-endian.
</para>
-@val:
+@val: a #guint value in host byte order.
+@Returns: @val converted to big-endian byte order.
<!-- ##### MACRO GUINT_TO_LE ##### -->
<para>
-
+Converts a #guint value from host byte order to little-endian.
</para>
-@val:
+@val: a #guint value in host byte order.
+@Returns: @val converted to little-endian byte order.
<!-- ##### MACRO GLONG_FROM_BE ##### -->
<para>
-
+Converts a #glong value from big-endian to the host byte order.
</para>
-@val:
+@val: a #glong value in big-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GLONG_FROM_LE ##### -->
<para>
-
+Converts a #glong value from little-endian to host byte order.
</para>
-@val:
+@val: a #glong value in little-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GLONG_TO_BE ##### -->
<para>
-
+Converts a #glong value from host byte order to big-endian.
</para>
-@val:
+@val: a #glong value in host byte order.
+@Returns: @val converted to big-endian byte order.
<!-- ##### MACRO GLONG_TO_LE ##### -->
<para>
-
+Converts a #glong value from host byte order to little-endian.
</para>
-@val:
+@val: a #glong value in host byte order.
+@Returns: @val converted to little-endian.
<!-- ##### MACRO GULONG_FROM_BE ##### -->
<para>
-
+Converts a #gulong value from big-endian to host byte order.
</para>
-@val:
+@val: a #gulong value in big-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GULONG_FROM_LE ##### -->
<para>
-
+Converts a #gulong value from little-endian to host byte order.
</para>
-@val:
+@val: a #gulong value in little-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GULONG_TO_BE ##### -->
<para>
-
+Converts a #gulong value from host byte order to big-endian.
</para>
-@val:
+@val: a #gulong value in host byte order.
+@Returns: @val converted to big-endian.
<!-- ##### MACRO GULONG_TO_LE ##### -->
<para>
-
+Converts a #gulong value from host byte order to little-endian.
</para>
-@val:
+@val: a #gulong value in host byte order.
+@Returns: @val converted to little-endian.
<!-- ##### MACRO GINT16_FROM_BE ##### -->
<para>
-
+Converts a #gint16 value from big-endian to host byte order.
</para>
-@val:
+@val: a #gint16 value in big-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT16_FROM_LE ##### -->
<para>
-
+Converts a #gint16 value from little-endian to host byte order.
</para>
-@val:
+@val: a #gint16 value in little-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT16_TO_BE ##### -->
<para>
-
+Converts a #gint16 value from host byte order to big-endian.
</para>
-@val:
+@val: a #gint16 value in host byte order.
+@Returns: @val converted to big-endian.
<!-- ##### MACRO GINT16_TO_LE ##### -->
<para>
-
+Converts a #gint16 value from host byte order to little-endian.
</para>
-@val:
+@val: a #gint16 value in host byte order.
+@Returns: @val converted to little-endian.
<!-- ##### MACRO GUINT16_FROM_BE ##### -->
<para>
-
+Converts a #guint16 value from big-endian to host byte order.
</para>
-@val:
+@val: a #guint16 value in big-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GUINT16_FROM_LE ##### -->
<para>
-
+Converts a #guint16 value from little-endian to host byte order.
</para>
-@val:
+@val: a #guint16 value in little-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GUINT16_TO_BE ##### -->
<para>
-
+Converts a #guint16 value from host byte order to big-endian.
</para>
-@val:
+@val: a #guint16 value in host byte order.
+@Returns: @val converted to big-endian.
<!-- ##### MACRO GUINT16_TO_LE ##### -->
<para>
-
+Converts a #guint16 value from host byte order to little-endian.
</para>
-@val:
+@val: a #guint16 value in host byte order.
+@Returns: @val converted to little-endian.
<!-- ##### MACRO GINT32_FROM_BE ##### -->
<para>
-
+Converts a #gint32 value from big-endian to host byte order.
</para>
-@val:
+@val: a #gint32 value in big-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT32_FROM_LE ##### -->
<para>
-
+Converts a #gint32 value from little-endian to host byte order.
</para>
-@val:
+@val: a #gint32 value in little-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT32_TO_BE ##### -->
<para>
-
+Converts a #gint32 value from host byte order to big-endian.
</para>
-@val:
+@val: a #gint32 value in host byte order.
+@Returns: @val converted to big-endian.
<!-- ##### MACRO GINT32_TO_LE ##### -->
<para>
-
+Converts a #gint32 value from host byte order to little-endian.
</para>
-@val:
+@val: a #gint32 value in host byte order.
+@Returns: @val converted to little-endian.
<!-- ##### MACRO GUINT32_FROM_BE ##### -->
<para>
-
+Converts a #guint32 value from big-endian to host byte order.
</para>
-@val:
+@val: a #guint32 value in big-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GUINT32_FROM_LE ##### -->
<para>
-
+Converts a #guint32 value from little-endian to host byte order.
</para>
-@val:
+@val: a #guint32 value in little-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GUINT32_TO_BE ##### -->
<para>
-
+Converts a #guint32 value from host byte order to big-endian.
</para>
-@val:
+@val: a #guint32 value in host byte order.
+@Returns: @val converted to big-endian.
<!-- ##### MACRO GUINT32_TO_LE ##### -->
<para>
-
+Converts a #guint32 value from host byte order to little-endian.
</para>
-@val:
+@val: a #guint32 value in host byte order.
+@Returns: @val converted to little-endian.
<!-- ##### MACRO GINT64_FROM_BE ##### -->
<para>
-
+Converts a #gint64 value from big-endian to host byte order.
</para>
-@val:
+@val: a #gint64 value in big-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT64_FROM_LE ##### -->
<para>
-
+Converts a #gint64 value from little-endian to host byte order.
</para>
-@val:
+@val: a #gint64 value in little-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GINT64_TO_BE ##### -->
<para>
-
+Converts a #gint64 value from host byte order to big-endian.
</para>
-@val:
+@val: a #gint64 value in host byte order.
+@Returns: @val converted to big-endian.
<!-- ##### MACRO GINT64_TO_LE ##### -->
<para>
-
+Converts a #gint64 value from host byte order to little-endian.
</para>
-@val:
+@val: a #gint64 value in host byte order.
+@Returns: @val converted to little-endian.
<!-- ##### MACRO GUINT64_FROM_BE ##### -->
<para>
-
+Converts a #guint64 value from big-endian to host byte order.
</para>
-@val:
+@val: a #guint64 value in big-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GUINT64_FROM_LE ##### -->
<para>
-
+Converts a #guint64 value from little-endian to host byte order.
</para>
-@val:
+@val: a #guint64 value in little-endian byte order.
+@Returns: @val converted to host byte order.
<!-- ##### MACRO GUINT64_TO_BE ##### -->
<para>
-
+Converts a #guint64 value from host byte order to big-endian.
</para>
-@val:
+@val: a #guint64 value in host byte order.
+@Returns: @val converted to big-endian.
<!-- ##### MACRO GUINT64_TO_LE ##### -->
<para>
-
+Converts a #guint64 value from host byte order to little-endian.
</para>
-@val:
+@val: a #guint64 value in host byte order.
+@Returns: @val converted to little-endian.
<!-- ##### MACRO GUINT16_SWAP_BE_PDP ##### -->
<para>
-
+Converts a #guint16 value between big-endian and pdp-endian byte order.
+The conversion is symmetric so it can be used both ways.
</para>
-@val:
+@val: a #guint16 value in big-endian or pdp-endian byte order.
+@Returns: @val converted to the opposite byte order.
<!-- ##### MACRO GUINT16_SWAP_LE_BE ##### -->
<para>
-
+Converts a #guint16 value between little-endian and big-endian byte order.
+The conversion is symmetric so it can be used both ways.
</para>
-@val:
+@val: a #guint16 value in little-endian or big-endian byte order.
+@Returns: @val converted to the opposite byte order.
<!-- ##### MACRO GUINT16_SWAP_LE_PDP ##### -->
<para>
-
+Converts a #guint16 value between little-endian and pdp-endian byte order.
+The conversion is symmetric so it can be used both ways.
</para>
-@val:
+@val: a #guint16 value in little-endian or pdp-endian byte order.
+@Returns: @val converted to the opposite byte order.
<!-- ##### MACRO GUINT32_SWAP_BE_PDP ##### -->
<para>
-
+Converts a #guint32 value between big-endian and pdp-endian byte order.
+The conversion is symmetric so it can be used both ways.
</para>
-@val:
+@val: a #guint32 value in big-endian or pdp-endian byte order.
+@Returns: @val converted to the opposite byte order.
<!-- ##### MACRO GUINT32_SWAP_LE_BE ##### -->
<para>
-
+Converts a #guint32 value between little-endian and big-endian byte order.
+The conversion is symmetric so it can be used both ways.
</para>
-@val:
+@val: a #guint32 value in little-endian or big-endian byte order.
+@Returns: @val converted to the opposite byte order.
<!-- ##### MACRO GUINT32_SWAP_LE_PDP ##### -->
<para>
-
+Converts a #guint32 value between little-endian and pdp-endian byte order.
+The conversion is symmetric so it can be used both ways.
</para>
-@val:
+@val: a #guint32 value in little-endian or pdp-endian byte order.
+@Returns: @val converted to the opposite byte order.
<!-- ##### MACRO GUINT64_SWAP_LE_BE ##### -->
<para>
-
+Converts a #guint64 value between little-endian and big-endian byte order.
+The conversion is symmetric so it can be used both ways.
</para>
-@val:
+@val: a #guint64 value in little-endian or big-endian byte order.
+@Returns: @val converted to the opposite byte order.
Caches
<!-- ##### SECTION Short_Description ##### -->
-
+allows sharing of complex data structures to save resources.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+A #GCache allows sharing of complex data structures, in order to save
+system resources.
+</para>
+<para>
+GTK uses a #GCache for both GtkStyles and GdkGCs. These consume a lot of
+resouces, so a #GCache is used to see if a GtkStyle or GdkGC with the
+required properties already exists. If it does, then the existing
+GtkStyle or GdkGC is used instead of creating a new one.
+</para>
+<para>
+#GCache uses keys and values.
+A #GCache key describes the properties of a particular resource.
+A #GCache value is the actual resource.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GCache ##### -->
<para>
-
+The #GCache struct is an opaque data structure containing information about
+a #GCache. It should only be accesssed via the following functions.
</para>
<!-- ##### FUNCTION g_cache_new ##### -->
<para>
-
+Creates a new GCache.
</para>
-@value_new_func:
-@value_destroy_func:
-@key_dup_func:
-@key_destroy_func:
-@hash_key_func:
-@hash_value_func:
-@key_compare_func:
-@Returns:
+@value_new_func: a function to create a new object given a key.
+This is called by g_cache_insert() if an object with the given key
+does not already exist.
+@value_destroy_func: a function to destroy an object. It is
+called by g_cache_remove() when the object is no longer needed (i.e. its
+reference count drops to 0).
+@key_dup_func: a function to copy a key. It is called by
+g_cache_insert() if the key does not already exist in the GCache.
+@key_destroy_func: a function to destroy a key. It is
+called by g_cache_remove() when the object is no longer needed (i.e. its
+reference count drops to 0).
+@hash_key_func: a function to create a hash value from a key.
+@hash_value_func: a function to create a hash value from a value.
+@key_compare_func: a function to compare two keys. It should return TRUE if
+the two keys are equivalent.
+@Returns: a new #GCache.
<!-- ##### FUNCTION g_cache_insert ##### -->
<para>
-
+Gets the value corresponding to the given key, creating it if necessary.
+It first checks if the value already exists in the #GCache, by using
+the @key_compare_func function passed to g_cache_new().
+If it does already exist it is returned, and its reference count is increased
+by one.
+If the value does not currently exist, if is created by calling the
+@value_new_func. The key is duplicated by calling
+@key_dup_func and the duplicated key and value are inserted
+into the #GCache.
</para>
-@cache:
-@key:
-@Returns:
+@cache: a #GCache.
+@key: a key describing a #GCache object.
+@Returns: a pointer to a #GCache value.
<!-- ##### FUNCTION g_cache_remove ##### -->
<para>
-
+Decreases the reference count of the given value.
+If it drops to 0 then the value and its corresponding key are destroyed,
+using the @value_destroy_func and @key_destroy_func passed to g_cache_new().
</para>
-@cache:
-@value:
+@cache: a #GCache.
+@value: the value to remove.
<!-- ##### FUNCTION g_cache_destroy ##### -->
<para>
-
+Frees the memory allocated for the GCache.
+</para>
+<para>
+Note that it does not destroy the keys and values which were contained in the
+GCache.
</para>
@cache:
<!-- ##### FUNCTION g_cache_key_foreach ##### -->
<para>
-
+Calls the given function for each of the keys in the #GCache.
</para>
-@cache:
-@func:
-@user_data:
+@cache: a #GCache.
+@func: the function to call with each #GCache key.
+@user_data: user data to pass to the function.
<!-- ##### FUNCTION g_cache_value_foreach ##### -->
<para>
-
+Calls the given function for each of the values in the #GCache.
</para>
-@cache:
-@func:
-@user_data:
+@cache: a #GCache.
+@func: the function to call with each #GCache value.
+@user_data: user data to pass to the function.
<!-- ##### USER_FUNCTION GCacheDestroyFunc ##### -->
<para>
-
+Specifies the type of the @value_destroy_func and @key_destroy_func functions
+passed to g_cache_new().
+The functions are passed a pointer to the #GCache key or #GCache value and
+should free any memory and other resources associated with it.
</para>
-@value:
+@value: the #GCache value to destroy.
<!-- ##### USER_FUNCTION GCacheDupFunc ##### -->
<para>
-
+Specifies the type of the @key_dup_func function passed to g_cache_new().
+The function is passed a key (NOT a value as the prototype implies) and
+should return a duplicate of the key.
</para>
-@value:
-@Returns:
+@value: the #GCache key to destroy (NOT a #GCache value as it seems).
+@Returns: a copy of the #GCache key.
<!-- ##### USER_FUNCTION GCacheNewFunc ##### -->
<para>
-
+Specifies the type of the @value_new_func function passed to g_cache_new().
+It is passed a #GCache key and should create the value corresponding to the
+key.
</para>
-@key:
-@Returns:
+@key: a #GCache key.
+@Returns: a new #GCache value corresponding to the key.
Automatic String Completion
<!-- ##### SECTION Short_Description ##### -->
-
+support for automatic completion using a group of target strings.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+#GCompletion provides support for automatic completion of a string using
+any group of target strings. It is typically used for file name completion
+as is common in many Unix shells.
+</para>
+<para>
+A #GCompletion is created using g_completion_new().
+Target items are added and removed with
+g_completion_add_items(), g_completion_remove_items() and
+g_completion_clear_items().
+A completion attempt is requested with g_completion_complete().
+When no longer needed, the #GCompletion is freed with g_completion_free().
+</para>
+<para>
+Items in the completion can be simple strings (e.g. file names),
+or pointers to arbitrary data structures. If data structures are used
+you must provide a #GCompletionFunc in g_completion_new(),
+which retrieves the item's string from the data structure.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GCompletion ##### -->
<para>
-
+The data structure used for automatic completion.
+<structfield>items</structfield> is the list of target items (strings
+or data structures).
+<structfield>func</structfield> is the function called to get the string
+associated with a target item. It is NULL if the target items are strings.
+<structfield>prefix</structfield> is the last prefix passed to
+g_completion_complete().
+<structfield>cache</structfield> is the list of items which begin with
+<structfield>prefix</structfield>.
</para>
@items:
<!-- ##### FUNCTION g_completion_new ##### -->
<para>
-
+Creates a new #GCompletion.
</para>
-@func:
-@Returns:
+@func: the function to be called to return the string representing an item
+in the #GCompletion, or NULL if strings are going to be used as the
+#GCompletion items.
+@Returns: the new #GCompletion.
<!-- ##### USER_FUNCTION GCompletionFunc ##### -->
<para>
-
+Specifies the type of the function passed to g_completion_new().
+It should return the string corresponding to the given target item.
+This is used when you use data structures as #GCompletion items.
</para>
-@Param1:
-@Returns:
+@Param1: the completion item.
+@Returns: the string corresponding to the item.
<!-- ##### FUNCTION g_completion_add_items ##### -->
<para>
-
+Adds items to the #GCompletion.
</para>
-@cmp:
-@items:
+@cmp: the #GCompletion.
+@items: the list of items to add.
<!-- ##### FUNCTION g_completion_remove_items ##### -->
<para>
-
+Removes items from a #GCompletion.
</para>
-@cmp:
-@items:
+@cmp: the #GCompletion.
+@items: the items to remove.
<!-- ##### FUNCTION g_completion_clear_items ##### -->
<para>
-
+Removes all items from the #GCompletion.
</para>
-@cmp:
+@cmp: the #GCompletion.
<!-- ##### FUNCTION g_completion_complete ##### -->
<para>
-
+Attempts to complete the string @prefix using the #GCompletion target items.
</para>
-@cmp:
-@prefix:
-@new_prefix:
-@Returns:
+@cmp: the #GCompletion.
+@prefix: the prefix string, typically typed by the user, which is compared
+with each of the items.
+@new_prefix: 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.
+@Returns: the list of items whose strings begin with @prefix. This should
+not be changed.
<!-- ##### FUNCTION g_completion_free ##### -->
<para>
-
+Frees all memory used by the #GCompletion.
</para>
-@cmp:
+@cmp: the #GCompletion.
Keyed Data Lists
<!-- ##### SECTION Short_Description ##### -->
-
+lists of data elements which are accessible by a string or #GQuark identifier.
<!-- ##### SECTION Long_Description ##### -->
<para>
+Keyed data lists provide lists of arbitrary data elements which can be accessed
+either with a string or with a #GQuark corresponding to the string.
+</para>
+<para>
+The GQuark methods are quicker, since the strings have to be converted to
+GQuarks anyway.
+</para>
+<para>
+Data lists are used in GTK for associating arbitrary data with
+GtkObjects, using gtk_object_set_data() and related functions.
+</para>
+<para>
+To create a datalist, use g_datalist_init().
+</para>
+<para>
+To add data elements to a datalist use g_datalist_id_set_data(),
+g_datalist_id_set_data_full(), g_datalist_set_data()
+and g_datalist_set_data_full().
+</para>
+<para>
+To get data elements from a datalist use g_datalist_id_get_data() and
+g_datalist_get_data().
+</para>
+<para>
+To iterate over all data elements in a datalist use g_datalist_foreach().
+</para>
+<para>
+To remove data elements from a datalist use g_datalist_id_remove_data() and
+g_datalist_remove_data().
+</para>
+<para>
+To remove all data elements from a datalist, use g_datalist_clear().
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GData ##### -->
<para>
-
+The #GData struct is an opaque data structure to represent a
+<link linkend="glib-Keyed-Data-Lists">Keyed Data List</link>.
+It should only be accessed via the following functions.
</para>
<!-- ##### FUNCTION g_datalist_init ##### -->
<para>
-
+Resets the datalist to NULL.
+It does not free any memory or call any destroy functions.
</para>
-@datalist:
+@datalist: a pointer to a pointer to a datalist.
<!-- ##### MACRO g_datalist_id_set_data ##### -->
<para>
-
+Sets the data corresponding to the given #GQuark id.
+Any previous data with the same key is removed, and its
+destroy function is called.
</para>
-@dl:
-@q:
-@d:
+@dl: a datalist.
+@q: the #GQuark to identify the data element.
+@d: the data element.
<!-- ##### FUNCTION g_datalist_id_set_data_full ##### -->
<para>
-
+Sets the data corresponding to the given #GQuark id, and the function to
+be called when the element is removed from the datalist.
+Any previous data with the same key is removed, and its
+destroy function is called.
</para>
-@datalist:
-@key_id:
-@data:
-@destroy_func:
+@datalist: a datalist.
+@key_id: the #GQuark to identify the data element.
+@data: the data element.
+@destroy_func: the function to call when the data element is removed. This
+function will be called with the data element and can be used to free any
+memory allocated for it.
<!-- ##### FUNCTION g_datalist_id_get_data ##### -->
<para>
-
+Gets a data element.
</para>
-@datalist:
-@key_id:
-@Returns:
+@datalist: a datalist.
+@key_id: the #GQuark identifying a data element.
+@Returns: the data element, or NULL if it is not found.
<!-- ##### MACRO g_datalist_id_remove_data ##### -->
<para>
-
+Removes an element, using its #GQuark identifier.
</para>
-@dl:
-@q:
+@dl: a datalist.
+@q: the #GQuark identifying the data element.
<!-- ##### FUNCTION g_datalist_id_remove_no_notify ##### -->
<!-- ##### MACRO g_datalist_set_data ##### -->
<para>
-
+Sets the data element corresponding to the given string identifier.
</para>
-@dl:
-@k:
-@d:
+@dl: a datalist.
+@k: the string to identify the data element.
+@d: the data element.
<!-- ##### MACRO g_datalist_set_data_full ##### -->
<para>
-
+Sets the data element corresponding to the given string identifier, and the
+function to be called when the data element is removed.
</para>
-@dl:
-@k:
-@d:
-@f:
+@dl: a datalist.
+@k: the string to identify the data element.
+@d: the data element.
+@f: the function to call when the data element is removed. This
+function will be called with the data element and can be used to free any
+memory allocated for it.
<!-- ##### MACRO g_datalist_get_data ##### -->
<para>
-
+Gets a data element, using its string identifer.
+This is slower than g_datalist_id_get_data() because the string is first
+converted to a #GQuark.
</para>
-@dl:
-@k:
+@dl: a datalist.
+@k: the string identifying a data element.
+@Returns: the data element, or NULL if it is not found.
<!-- ##### MACRO g_datalist_remove_data ##### -->
<para>
-
+Removes an element using its string identifier.
+The data element's destroy function is called if it has been set.
</para>
-@dl:
-@k:
+@dl: a datalist.
+@k: the string identifying the data element.
<!-- ##### MACRO g_datalist_remove_no_notify ##### -->
<!-- ##### FUNCTION g_datalist_foreach ##### -->
<para>
-
+Calls the given function for each data element of the datalist.
+The function is called with each data element's #GQuark id and data,
+together with the given @user_data parameter.
</para>
-@datalist:
-@func:
-@user_data:
+@datalist: a datalist.
+@func: the function to call for each data element.
+@user_data: user data to pass to the function.
<!-- ##### FUNCTION g_datalist_clear ##### -->
<para>
-
+Frees all the data elements of the datalist.
+The data elements' destroy functions are called if they have been set.
</para>
-@datalist:
+@datalist: a datalist.
Datasets
<!-- ##### SECTION Short_Description ##### -->
-
+associate groups of data elements with particular memory locations.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+Datasets associate groups of data elements with particular memory locations.
+These are useful if you need to associate data with a structure returned
+from an external library. Since you cannot modify the structure, you use
+its location in memory as the key into a dataset, where you can associate
+any number of data elements with it.
+</para>
+<para>
+There are two forms of most of the dataset functions.
+The first form uses strings to identify the data elements associated with
+a location. The second form uses #GQuark identifiers, which are created
+with a call to g_quark_from_string() or g_quark_from_static_string().
+The second form is quicker, since it does not require looking up the string
+in the hash table of #GQuark identifiers.
+</para>
+<para>
+There is no function to create a dataset. It is automatically created as
+soon as you add elements to it.
+</para>
+<para>
+To add data elements to a dataset use g_dataset_id_set_data(),
+g_dataset_id_set_data_full(), g_dataset_set_data()
+and g_dataset_set_data_full().
+</para>
+<para>
+To get data elements from a dataset use g_dataset_id_get_data() and
+g_dataset_get_data().
+</para>
+<para>
+To iterate over all data elements in a dataset use g_dataset_foreach().
+</para>
+<para>
+To remove data elements from a dataset use g_dataset_id_remove_data() and
+g_dataset_remove_data().
+</para>
+<para>
+To destroy a dataset, use g_dataset_destroy().
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### MACRO g_dataset_id_set_data ##### -->
<para>
-
+Sets the data element associated with the given #GQuark id.
+Any previous data with the same key is removed, and its destroy function
+is called.
</para>
-@l:
-@k:
-@d:
+@l: the location identifying the dataset.
+@k: the #GQuark id to identify the data element.
+@d: the data element.
<!-- ##### FUNCTION g_dataset_id_set_data_full ##### -->
<para>
-
+Sets the data element associated with the given #GQuark id, and also the
+function to call when the data element is destroyed.
+Any previous data with the same key is removed, and its
+destroy function is called.
</para>
-@dataset_location:
-@key_id:
-@data:
-@destroy_func:
+@dataset_location: the location identifying the dataset.
+@key_id: the #GQuark id to identify the data element.
+@data: the data element.
+@destroy_func: the function to call when the data element is removed. This
+function will be called with the data element and can be used to free any
+memory allocated for it.
<!-- ##### USER_FUNCTION GDestroyNotify ##### -->
<para>
-
+Specifies the type of function which is called when a data element is
+destroyed. It is passed the pointer to the data element and should free
+any memory and resources allocated for it.
</para>
-@data:
+@data: the data element.
<!-- ##### FUNCTION g_dataset_id_get_data ##### -->
<para>
-
+Gets the data element corresponding to a #GQuark.
</para>
-@dataset_location:
-@key_id:
-@Returns:
+@dataset_location: the location identifying the dataset.
+@key_id: the #GQuark id to identify the data element.
+@Returns: the data element corresponding to the #GQuark, or NULL if it is
+not found.
<!-- ##### MACRO g_dataset_id_remove_data ##### -->
<para>
-
+Removes a data element from a dataset.
+The data element's destroy function is called if it has been set.
</para>
-@l:
-@k:
+@l: the location identifying the dataset.
+@k: the #GQuark id identifying the data element.
<!-- ##### FUNCTION g_dataset_id_remove_no_notify ##### -->
<!-- ##### MACRO g_dataset_set_data ##### -->
<para>
-
+Sets the data corresponding to the given string identifier.
</para>
-@l:
-@k:
-@d:
+@l: the location identifying the dataset.
+@k: the string to identify the data element.
+@d: the data element.
<!-- ##### MACRO g_dataset_set_data_full ##### -->
<para>
-
+Sets the data corresponding to the given string identifier, and the function
+to call when the data element is destroyed.
</para>
-@l:
-@k:
-@d:
-@f:
+@l: the location identifying the dataset.
+@k: the string to identify the data element.
+@d: the data element.
+@f: the function to call when the data element is removed. This
+function will be called with the data element and can be used to free any
+memory allocated for it.
<!-- ##### MACRO g_dataset_get_data ##### -->
<para>
-
+Gets the data element corresponding to a string.
</para>
-@l:
-@k:
+@l: the location identifying the dataset.
+@k: the string identifying the data element.
+@Returns: the data element corresponding to the string, or NULL if it is not
+found.
<!-- ##### MACRO g_dataset_remove_data ##### -->
<para>
-
+Removes a data element corresponding to a string.
+Its destroy function is called if it has been set.
</para>
-@l:
-@k:
+@l: the location identifying the dataset.
+@k: the string identifying the data element.
<!-- ##### MACRO g_dataset_remove_no_notify ##### -->
<!-- ##### FUNCTION g_dataset_foreach ##### -->
<para>
-
+Calls the given function for each data element which is associated with the
+given location.
</para>
-@dataset_location:
-@func:
-@user_data:
+@dataset_location: the location identifying the dataset.
+@func: the function to call for each data element.
+@user_data: user data to pass to the function.
<!-- ##### USER_FUNCTION GDataForeachFunc ##### -->
<para>
-
+Specifies the type of function passed to g_dataset_foreach().
+It is called with each #GQuark id and associated data element,
+together with the @user_data parameter supplied to g_dataset_foreach().
</para>
-@key_id:
-@data:
-@user_data:
+@key_id: the #GQuark id to identifying the data element.
+@data: the data element.
+@user_data: user data passed to g_dataset_foreach().
<!-- ##### FUNCTION g_dataset_destroy ##### -->
<para>
-
+Destroys the dataset, freeing all memory allocated, and calling any
+destroy functions set for data elements.
</para>
-@dataset_location:
+@dataset_location: the location identifying the dataset.
Date and Time Functions
<!-- ##### SECTION Short_Description ##### -->
-
+calendrical calculations and miscellaneous time stuff.
<!-- ##### SECTION Long_Description ##### -->
-<para>
-
+<para>\r
+The #GDate data structure represents a day between January 1, Year 1,\r
+and sometime a few thousand years in the future (right now it will go\r
+to the year 65535 or so, but g_date_set_parse() only parses up to the\r
+year 8000 or so - just count on "a few thousand"). #GDate is meant to\r
+represent everyday dates, not astronomical dates or historical dates\r
+or ISO timestamps or the like. It extrapolates the current Gregorian\r
+calendar forward and backward in time; there is no attempt to change\r
+the calendar to match time periods or locations. #GDate does not store\r
+time information; it represents a <emphasis>day</emphasis>.\r
+</para>\r
+\r
+<para>\r
+The #GDate implementation has several nice features; it is only a\r
+64-bit struct, so storing large numbers of dates is very efficient. It\r
+can keep both a Julian and Day-Month-Year representation of the date,\r
+since some calculations are much easier with one representation or the\r
+other. A Julian representation is simply a count of days since some\r
+fixed day in the past; for #GDate the fixed day is January 1, 1 AD.\r
+("Julian" dates in the #GDate API aren't really Julian dates in the\r
+technical sense; technically, Julian dates count from the start of the\r
+Julian period, Jan 1, 4713 BC).\r
+</para>\r
+\r
+<para>\r
+#GDate is simple to use. First you need a "blank" date; you can get a\r
+dynamically allocated date from g_date_new(), or you can declare an\r
+automatic variable or array and initialize it to a sane state by\r
+calling g_date_clear(). A cleared date is sane; it's safe to call\r
+g_date_set_dmy() and the other mutator functions to initialize the\r
+value of a cleared date. However, a cleared date is initially\r
+<emphasis>invalid</emphasis>, meaning that it doesn't represent a day\r
+that exists. It is undefined to call any of the date calculation\r
+routines on an invalid date. If you obtain a date from a user or other\r
+unpredictable source, you should check its validity with the\r
+g_date_valid() predicate. g_date_valid() is also used to check for\r
+errors with g_date_set_parse() and other functions that can\r
+fail. Dates can be invalidated by calling g_date_clear() again.\r
+</para>\r
+\r
+<para>\r
+<emphasis>It is very important to use the API to access the #GDate\r
+struct.</emphasis> Often only the DMY or only the Julian\r
+representation is valid. Sometimes neither is valid. Use the API.\r
+</para>\r
+\r
+<para>\r
+glib doesn't contain any time-manipulation functions; however, there\r
+is a #GTime typedef which is equivalent to time_t, and a #GTimeVal\r
+struct which represents a more precise time (with microseconds). You\r
+can request the current time as a #GTimeVal with g_get_current_time().\r
</para>
<!-- ##### SECTION See_Also ##### -->
-<para>
-
+<para>\r
+\r
</para>
<!-- ##### MACRO G_USEC_PER_SEC ##### -->
<!-- ##### STRUCT GTimeVal ##### -->
-<para>
-
+<para>\r
+Represents a precise time, with seconds and microseconds. Same as the\r
+<structname>struct timeval</structname> returned by the\r
+<function>gettimeofday()</function> UNIX call.\r
</para>
@tv_sec:
@tv_usec:
<!-- ##### FUNCTION g_get_current_time ##### -->
-<para>
-
+<para>\r
+Equivalent to <function>gettimeofday()</function>, but also works on\r
+Win32. Returns the current time.\r
</para>
@result:
<!-- ##### STRUCT GDate ##### -->
-<para>
-
+<para>\r
+Represents a day between January 1, Year 1 and a few thousand years in\r
+the future. None of its members should be accessed directly. If the\r
+<structname>GDate</structname> is obtained from g_date_new(), it will\r
+be safe to mutate but invalid and thus not safe for calendrical computations.\r
+If it's declared on the stack, it will contain garbage so must be\r
+initialized with g_date_clear(). g_date_clear() makes the date invalid\r
+but sane. An invalid date doesn't represent a day, it's "empty." A\r
+date becomes valid after you set it to a Julian day or you set a day,\r
+month, and year.\r
</para>
@julian_days:
@year:
<!-- ##### TYPEDEF GTime ##### -->
-<para>
-
+<para>\r
+Simply a replacement for time_t. Unrelated to GTimer.\r
</para>
<!-- ##### ENUM GDateDMY ##### -->
-<para>
-
+<para>\r
+This enumeration isn't used in the API, but may be useful if you need\r
+to mark a number as a day, month, or year.\r
</para>
@G_DATE_DAY:
@G_DATE_YEAR:
<!-- ##### TYPEDEF GDateDay ##### -->
-<para>
-
+<para>\r
+Integer representing a day of the month; between 1 and\r
+31. #G_DATE_BAD_DAY represents an invalid day of the month.\r
</para>
<!-- ##### ENUM GDateMonth ##### -->
-<para>
-
+<para>\r
+Enumeration representing a month; values are #G_DATE_JANUARY,\r
+#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the "invalid" value.\r
</para>
@G_DATE_BAD_MONTH:
@G_DATE_DECEMBER:
<!-- ##### TYPEDEF GDateYear ##### -->
-<para>
-
+<para>\r
+Integer representing a year; #G_DATE_BAD_YEAR is the invalid\r
+value. The year must be 1 or higher; negative (BC) years are not\r
+allowed. The year is represented with four digits.\r
</para>
<!-- ##### ENUM GDateWeekday ##### -->
-<para>
-
+<para>\r
+Enumeration representing a day of the week; #G_DATE_MONDAY,\r
+#G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday.\r
</para>
@G_DATE_BAD_WEEKDAY:
@G_DATE_SUNDAY:
<!-- ##### MACRO G_DATE_BAD_DAY ##### -->
-<para>
-
+<para>\r
+Represents an invalid #GDateDay.\r
</para>
<!-- ##### MACRO G_DATE_BAD_JULIAN ##### -->
-<para>
-
+<para>\r
+Represents an invalid Julian day number.\r
</para>
<!-- ##### MACRO G_DATE_BAD_YEAR ##### -->
-<para>
-
+<para>\r
+Represents an invalid year.\r
</para>
<!-- ##### FUNCTION g_date_new ##### -->
-<para>
-
+<para>\r
+Allocate a #GDate and initialize it to a sane state. The new date will\r
+be cleared (as if you'd called g_date_clear()) but invalid (it won't\r
+represent an existing day). Free the return value with g_date_free().\r
</para>
-@Returns:
+@Returns: The newly-allocated #GDate
<!-- ##### FUNCTION g_date_new_dmy ##### -->
-<para>
-
+<para>\r
+Like g_date_new(), but also sets the value of the date. Assuming the\r
+day/month/year triplet you pass in represents an existing day, the\r
+returned date will be valid.\r
</para>
-@day:
-@month:
-@year:
-@Returns:
+@day: Day of the month
+@month: Month of the year
+@year: Year
+@Returns: Allocated date initialized with @day, @month, and @year
<!-- ##### FUNCTION g_date_new_julian ##### -->
-<para>
-
+<para>\r
+Like g_date_new(), but also sets the value of the date. Assuming the\r
+Julian day number you pass in is valid (greater than 0, less than an\r
+unreasonably large number), the returned date will be valid.\r
</para>
-@julian_day:
-@Returns:
+@julian_day: Days since January 1, Year 1
+@Returns: Allocated date initialized with @julian_day
<!-- ##### FUNCTION g_date_clear ##### -->
-<para>
-
+<para>\r
+Initialize one or more #GDate structs to a sane but invalid\r
+state. The cleared dates will not represent an existing date, but will\r
+not contain garbage. Useful to init a date declared on the stack.\r
+Validity can be tested with g_date_valid().\r
</para>
-@date:
-@n_dates:
+@date: Pointer to one or more dates to clear
+@n_dates: Number of dates to clear
<!-- ##### FUNCTION g_date_free ##### -->
-<para>
-
+<para>\r
+Free a #GDate returned from g_date_new()\r
</para>
-@date:
+@date: Date to free
<!-- ##### FUNCTION g_date_set_day ##### -->
-<para>
-
+<para>\r
+Set the day of the month for a #GDate. If the resulting day-month-year\r
+triplet is invalid, the date will be invalid.\r
</para>
-@date:
-@day:
+@date: Date to set the day for
+@day: Day to set
<!-- ##### FUNCTION g_date_set_month ##### -->
-<para>
-
+<para>\r
+Set the month of the year for a #GDate. If the resulting\r
+ day-month-year triplet is invalid, the date will be invalid.\r
</para>
-@date:
-@month:
+@date: Date
+@month: Month to set
<!-- ##### FUNCTION g_date_set_year ##### -->
-<para>
-
+<para>\r
+Set the year for a #GDate. If the resulting day-month-year triplet is\r
+ invalid, the date will be invalid.\r
</para>
-@date:
-@year:
+@date: Date
+@year: Year to set
<!-- ##### FUNCTION g_date_set_dmy ##### -->
-<para>
-
+<para>\r
+Set the value of a #GDate from a day, month, and year. The DMY triplet\r
+must be valid; if you aren't sure it is, call g_date_valid_dmy() to\r
+check before you set it.\r
</para>
-@date:
-@day:
-@month:
-@y:
+@date: Date to set the value of
+@day: Day
+@month: Month
+@y: Year
<!-- ##### FUNCTION g_date_set_julian ##### -->
-<para>
-
+<para>\r
+Set the value of a #GDate from a Julian day number. \r
</para>
-@date:
-@julian_date:
+@date: Date to set
+@julian_date: Julian day number (days since January 1, Year 1)
<!-- ##### FUNCTION g_date_set_time ##### -->
-<para>
-
+<para>\r
+Set the value of a date from a #GTime (time_t) value. To set the value\r
+of a date to the current day, you could write:\r
+<informalexample><programlisting>\r
+ g_date_set_time(date, time(NULL));\r
+</programlisting></informalexample>\r
</para>
-@date:
-@time:
+@date: Date to update
+@time: #GTime value to set
<!-- ##### FUNCTION g_date_set_parse ##### -->
-<para>
-
-</para>
-
-@date:
-@str:
+<para>\r
+Parse a user-inputted string @str, and try to figure out what date it\r
+represents, taking the current locale into account. If the string is\r
+successfully parsed, the date will be valid after the call. Otherwise,\r
+it will be invalid. You should check using g_date_valid() to see\r
+whether the parsing succeeded.\r
+</para>\r
+\r
+<para>\r
+This function is not appropriate for file formats and the like; it\r
+isn't very precise, and its exact behavior varies with the\r
+locale. It's intended to be a heuristic routine that guesses what the\r
+user means by a given string (and it does work pretty well in that\r
+capacity).\r
+</para>
+
+@date: Date to fill in
+@str: String to parse
<!-- ##### FUNCTION g_date_add_days ##### -->
-<para>
-
+<para>\r
+Increment a date some number of days. To move forward by weeks, add\r
+weeks*7 days. The date must be valid.\r
</para>
-@date:
-@n_days:
+@date: The date to increment
+@n_days: Number of days to move the date forward
<!-- ##### FUNCTION g_date_subtract_days ##### -->
-<para>
-
+<para>\r
+Move a date some number of days into the past. To move by weeks, just\r
+move by weeks*7 days. Date must be valid.\r
</para>
-@date:
-@n_days:
+@date: Date to decrement
+@n_days: Number of days to move
<!-- ##### FUNCTION g_date_add_months ##### -->
-<para>
-
+<para>\r
+Increment a date by some number of months. If the day of the month is\r
+greater than 28, this routine may change the day of the month (because\r
+the destination month may not have the current day in it). The date\r
+must be valid.\r
</para>
-@date:
-@n_months:
+@date: Date to increment
+@n_months: Number of months to move forward
<!-- ##### FUNCTION g_date_subtract_months ##### -->
-<para>
-
+<para>\r
+Move a date some number of months into the past. If the current day of\r
+the month doesn't exist in the destination month, the day of the month\r
+may change. Date must be valid.\r
</para>
-@date:
-@n_months:
+@date: Date to decrement
+@n_months: Number of months to move
<!-- ##### FUNCTION g_date_add_years ##### -->
-<para>
-
+<para>\r
+Increment a date by some number of years. If the date is February 29,\r
+and the destination year is not a leap year, the date will be changed\r
+to February 28. The date must be valid.\r
</para>
-@date:
-@n_years:
+@date: Date to increment
+@n_years: Number of years to move forward
<!-- ##### FUNCTION g_date_subtract_years ##### -->
-<para>
-
+<para>\r
+Move a date some number of years into the past. If the current day\r
+doesn't exist in the destination year (i.e. it's February 29 and you\r
+move to a non-leap-year) then the day is changed to February 29. Date\r
+must be valid.\r
</para>
-@date:
-@n_years:
+@date: Date to decrement
+@n_years: Number of years to move
<!-- ##### FUNCTION g_date_compare ##### -->
-<para>
-
+<para>\r
+<function>qsort()</function>-style comparsion function for dates. Both\r
+dates must be valid.\r
</para>
-@lhs:
-@rhs:
-@Returns:
+@lhs: First date to compare
+@rhs: Second date to compare
+@Returns: 0 for equal, less than zero if @lhs is less than @rhs,\r
+greater than zero if @lhs is greater than @rhs
<!-- ##### FUNCTION g_date_day ##### -->
-<para>
-
+<para>\r
+Return the day of the month; the #GDate must be valid.\r
</para>
-@date:
-@Returns:
+@date: Date to extract the day of the month from
+@Returns: Day of the month
<!-- ##### FUNCTION g_date_month ##### -->
-<para>
-
+<para>\r
+Accessor for the month of the year. Date must be valid.\r
</para>
-@date:
-@Returns:
+@date: Date to get the month from
+@Returns: A #GDateMonth
<!-- ##### FUNCTION g_date_year ##### -->
-<para>
-
+<para>\r
+Accessor; returns the year of a #GDate. The date must be valid.\r
</para>
-@date:
-@Returns:
+@date: Date
+@Returns: Year in which the date falls
<!-- ##### FUNCTION g_date_julian ##### -->
-<para>
-
+<para>\r
+Accessor, returns the Julian day or "serial number" of the #GDate. The\r
+Julian day is simply the number of days since January 1, Year 1; i.e.,\r
+January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2,\r
+etc. Date must be valid.\r
</para>
-@date:
-@Returns:
+@date: Date to extract the Julian day from
+@Returns: Julian day
<!-- ##### FUNCTION g_date_weekday ##### -->
-<para>
-
+<para>\r
+Returns the day of the week for a #GDate. The date must be valid.\r
</para>
-@date:
-@Returns:
+@date: Date
+@Returns: Day of the week as a #GDateWeekday
<!-- ##### FUNCTION g_date_day_of_year ##### -->
-<para>
-
+<para>\r
+Return the day of the year, where Jan 1 is the first day of the\r
+year. Date must be valid.\r
</para>
-@date:
-@Returns:
+@date: Date to extract day of year from
+@Returns: Day of the year
<!-- ##### FUNCTION g_date_days_in_month ##### -->
-<para>
-
+<para>\r
+Return the number of days in a month, taking leap years into account.\r
</para>
-@month:
-@year:
-@Returns:
+@month: Month
+@year: Year
+@Returns: Number of days in @month during the year @year.
<!-- ##### FUNCTION g_date_is_first_of_month ##### -->
-<para>
-
+<para>\r
+Returns TRUE if the date is on the first of a month. Date must be valid.\r
</para>
-@date:
-@Returns:
+@date: Date to check
+@Returns: Boolean, if the date is the first of the month
<!-- ##### FUNCTION g_date_is_last_of_month ##### -->
-<para>
-
+<para>\r
+Returns TRUE if the date is the last day of the month. Date must be valid.\r
</para>
-@date:
-@Returns:
+@date: Date to check
+@Returns: Boolean, if the date is the last day of the month
<!-- ##### FUNCTION g_date_is_leap_year ##### -->
-<para>
-
+<para>\r
+Returns TRUE if the year is a leap year\r
</para>
-@year:
-@Returns:
+@year: Year to check
+@Returns: Boolean, if the year is a leap year
<!-- ##### FUNCTION g_date_monday_week_of_year ##### -->
-<para>
-
+<para>\r
+Return the week of the year, where weeks are understood to start on\r
+Monday. If the date is before the first Monday of the year, return\r
+0. Date must be valid.\r
</para>
-@date:
-@Returns:
+@date: Date to use
+@Returns: Week of the year
<!-- ##### FUNCTION g_date_monday_weeks_in_year ##### -->
-<para>
-
+<para>\r
+Return the number of weeks in the year, where weeks are taken to start\r
+on Monday. Will be 52 or 53. Date must be valid. (Years always have 52\r
+7-day periods, plus 1 or 2 extra days depending on whether it's a leap\r
+year. This function is basically telling you how many Mondays are in\r
+the year, i.e. there are 53 Mondays if one of the extra days happens\r
+to be a Monday.)\r
</para>
-@year:
-@Returns:
+@year: Year
+@Returns: Number of Mondays in the year
<!-- ##### FUNCTION g_date_sunday_week_of_year ##### -->
-<para>
-
+<para>\r
+Week of the year during which this date falls, if weeks are understood\r
+to being on Sunday. Date must be valid. Can return 0 if the day is\r
+before the first Sunday of the year.\r
</para>
-@date:
-@Returns:
+@date: Date
+@Returns: Week number
<!-- ##### FUNCTION g_date_sunday_weeks_in_year ##### -->
-<para>
-
+<para>\r
+Return the number of weeks in the year, where weeks are taken to start\r
+on Sunday. Will be 52 or 53. Date must be valid. (Years always have 52\r
+7-day periods, plus 1 or 2 extra days depending on whether it's a leap\r
+year. This function is basically telling you how many Sundays are in\r
+the year, i.e. there are 53 Sundays if one of the extra days happens\r
+to be a Sunday.)\r
</para>
-@year:
-@Returns:
+@year: Year to count weeks in
+@Returns: Number of weeks
<!-- ##### FUNCTION g_date_strftime ##### -->
-<para>
-
+<para>\r
+Generate a printed representation of the date, in a locale-specific\r
+way. Works just like the standard C <function>strftime()</function>\r
+function, but only accepts date-related formats; time-related formats\r
+give undefined results. Date must be valid.\r
</para>
-@s:
-@slen:
-@format:
-@date:
-@Returns:
+@s: Destination buffer
+@slen: Max buffer size
+@format: Format string
+@date: valid #GDate
+@Returns: number of characters written to the buffer, or 0 the buffer was too small
<!-- ##### FUNCTION g_date_to_struct_tm ##### -->
-<para>
-
+<para>\r
+Fills in the date-related bits of a <structname>struct tm</structname>\r
+using the @date value. Initializes the non-date parts with something\r
+sane but meaningless.\r
</para>
-@date:
-@tm:
+@date: Date to set the <structname>struct tm</structname> from
+@tm: <structname>struct tm</structname> to fill
<!-- ##### FUNCTION g_date_valid ##### -->
-<para>
-
+<para>\r
+Returns TRUE if the #GDate represents an existing day. #GDate must not\r
+contain garbage; it should have been initialized with g_date_clear()\r
+if it wasn't allocated by one of the g_date_new() variants.\r
</para>
-@date:
-@Returns:
+@date: Date to check
+@Returns: Whether the date is valid.
<!-- ##### FUNCTION g_date_valid_day ##### -->
-<para>
-
+<para>\r
+Returns TRUE if the day of the month is valid (a day is valid if it's\r
+between 1 and 31 inclusive).\r
</para>
-@day:
-@Returns:
+@day: Day to check.
+@Returns: Boolean, whether the day is valid.
<!-- ##### FUNCTION g_date_valid_month ##### -->
-<para>
-
+<para>\r
+Returns TRUE if the month value is valid. The 12 #GDateMonth\r
+enumeration values are the only valid months.\r
</para>
-@month:
-@Returns:
+@month: Month
+@Returns: Boolean, whether the month is valid
<!-- ##### FUNCTION g_date_valid_year ##### -->
-<para>
-
+<para>\r
+Returns TRUE if the year is valid. Any year greater than 0 is valid,\r
+though there is a 16-bit limit to what GDate will understand.\r
</para>
-@year:
-@Returns:
+@year: Year
+@Returns: Boolean, whether the year is valid.
<!-- ##### FUNCTION g_date_valid_dmy ##### -->
-<para>
-
+<para>\r
+Returns TRUE if the day/month/year triplet forms a valid, existing day\r
+in the range of days GDate understands (Year 1 or later, no more than\r
+a few thousand years in the future).\r
</para>
-@day:
-@month:
-@year:
-@Returns:
+@day: Day
+@month: Month
+@year: Year
+@Returns: Boolean, whether the date is a valid one
<!-- ##### FUNCTION g_date_valid_julian ##### -->
-<para>
-
+<para>\r
+Returns TRUE if the Julian day is valid. Anything greater than zero is basically a\r
+valid Julian, though there is a 32-bit limit.\r
</para>
-@julian_date:
-@Returns:
+@julian_date: Julian day to check
+@Returns: Boolean, whether the Julian day is valid.
<!-- ##### FUNCTION g_date_valid_weekday ##### -->
-<para>
-
+<para>\r
+Returns TRUE if the weekday is valid. The 7 #GDateWeekday enumeration\r
+values are the only valid weekdays.\r
</para>
-@weekday:
-@Returns:
+@weekday: Weekday
+@Returns: Boolean, whether the weekday is valid.
-<!-- ##### MACRO G_GLONG_FORMAT ##### -->
+<!-- ##### MACRO lseek ##### -->
<para>
</para>
-<!-- ##### MACRO G_GSHORT_FORMAT ##### -->
+<!-- ##### USER_FUNCTION GSearchFunc ##### -->
+<para>
+Specifies the type of function passed to g_tree_search().
+</para>
+
+@key: a key from a #GTree.
+@data: the data to compare with the key.
+@Returns: 0 if the desired key has been found, a negative number if the
+desired key comes before @key in the sort order of the #GTree, or a positive
+value if the desired key comes after @key.
+
+<!-- ##### MACRO write ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO pclose ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO g_string ##### -->
+<para>
+Turns the argument into a string literal by using the '#' stringizing operator.
+</para>
+
+@x: text to convert to a literal string.
+
+<!-- ##### MACRO popen ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO access ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO open ##### -->
<para>
</para>
-<!-- ##### MACRO G_GUSHORT_FORMAT ##### -->
+<!-- ##### MACRO getpid ##### -->
<para>
</para>
-<!-- ##### MACRO G_GINT_FORMAT ##### -->
+<!-- ##### MACRO fdopen ##### -->
<para>
</para>
-<!-- ##### MACRO G_GUINT_FORMAT ##### -->
+<!-- ##### MACRO close ##### -->
<para>
</para>
-<!-- ##### MACRO G_GULONG_FORMAT ##### -->
+<!-- ##### MACRO getcwd ##### -->
<para>
</para>
-<!-- ##### MACRO G_MICROSEC ##### -->
+<!-- ##### MACRO read ##### -->
<para>
</para>
Hash Tables
<!-- ##### SECTION Short_Description ##### -->
-
+associations between keys and values so that given a key the value
+can be found quickly.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+A #GHashTable provides associations between keys and values which
+is optimized so that given a key, the associated value can be found
+very quickly.
+</para>
+<para>
+Note that neither keys nor values are copied when inserted into the
+#GHashTable, so they must exist for the lifetime of the #GHashTable.
+This means that the use of static strings is OK, but temporary
+strings (i.e. those created in buffers and those returned by GTK widgets)
+should be copied with g_strdup() before being inserted.
+</para>
+<para>
+If keys or values are dynamically allocated, you must be careful to ensure
+that they are freed when they are removed from the #GHashTable, and also
+when they are overwritten by new insertions into the #GHashTable.
+It is also not advisable to mix static strings and dynamically-allocated
+strings in a #GHashTable, because it then becomes difficult to determine
+whether the string should be freed.
+</para>
+<para>
+To create a #GHashTable, use g_hash_table_new().
+</para>
+<para>
+To insert a key and value into a #GHashTable, use g_hash_table_insert().
+</para>
+<para>
+To lookup a value corresponding to a given key, use g_hash_table_lookup()
+and g_hash_table_lookup_extended().
+</para>
+<para>
+To remove a key and value, use g_hash_table_remove().
+</para>
+<para>
+To call a function for each key and value pair use g_hash_table_foreach().
+</para>
+<para>
+To destroy a #GHashTable use g_hash_table_destroy().
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GHashTable ##### -->
<para>
-
+The #GHashTable struct is an opaque data structure to represent a
+<link linkend="glib-Hash-Tables">Hash Table</link>.
+It should only be accessed via the following functions.
</para>
<!-- ##### FUNCTION g_hash_table_new ##### -->
<para>
-
+Creates a new #GHashTable.
</para>
-@hash_func:
-@key_compare_func:
-@Returns:
+@hash_func: 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.
+@key_compare_func: a function to compare two keys to see if they are equal.
+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 compare_func is NULL, keys are compared
+directly in a similar fashion to g_direct_equal(), but without the overhead
+of a function call.
+@Returns: a new #GHashTable.
<!-- ##### USER_FUNCTION GHashFunc ##### -->
<para>
-
+Specifies the type of the hash function which is passed to
+g_hash_table_new() when a #GHashTable is created.
+</para>
+<para>
+The function is passed a key and should return a guint hash value.
+The functions g_direct_hash(), g_int_hash() and g_str_hash() provide
+hash functions which can be used when the key is a #gpointer, #gint, and
+#gchar* respectively.
+</para>
+<para>
+FIXME: Need more here.
+The hash values should be evenly distributed over a fairly large range?
+The modulus is taken with the hash table size (a prime number)
+to find the 'bucket' to place each key into.
+The function should also be very fast, since it is called for each key
+lookup.
</para>
-@key:
-@Returns:
+@key: a key.
+@Returns: the hash value corresponding to the key.
<!-- ##### USER_FUNCTION GCompareFunc ##### -->
<para>
-
+Specifies the type of a comparison function used to compare two values.
+The value which should be returned depends on the context in which the
+#GCompareFunc is used.
+</para>
+<para>
+In g_hash_table_new(), g_cache_new(), and g_relation_index() the function
+should return TRUE if the two parameters are equal, or FALSE if they are not.
+</para>
+<para>
+In g_list_find_custom() and g_slist_find_custom() the function should return
+0 if the two parameters are equal.
+</para>
+<para>
+In g_list_insert_sorted(), g_list_sort(), g_slist_insert_sorted(),
+g_slist_sort() and g_tree_new() the function should return a negative integer
+if the first value comes before the second, 0 if they are equal, or a positive
+integer if the first value comes after the second.
</para>
-@a:
-@b:
-@Returns:
+@a: a value.
+@b: a value to compare with.
+@Returns: TRUE if the two values are equivalent.
<!-- ##### FUNCTION g_hash_table_insert ##### -->
<para>
-
+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.
</para>
+<note>
+<para>
+If the keys or values use dynamically allocated memory, then you should
+first check if the key already exists in the GHashTable. If it does,
+you should free the existing key and/or value before inserting the
+new key and value.
+</para>
+</note>
-@hash_table:
-@key:
-@value:
+@hash_table: a #GHashTable.
+@key: a key to insert.
+@value: the value to associate with the key.
<!-- ##### FUNCTION g_hash_table_size ##### -->
<para>
-
+Returns the number of key/value pairs in a #GHashTable.
</para>
-@hash_table:
-@Returns:
+@hash_table: a #GHashTable.
+@Returns: the number of key/value pairs in the #GHashTable.
<!-- ##### FUNCTION g_hash_table_lookup ##### -->
<para>
-
+Looks up a key in the #GHashTable, returning the associated value or NULL
+if the key is not found.
</para>
-@hash_table:
-@key:
-@Returns:
+@hash_table: a #GHashTable.
+@key: the key to look up.
+@Returns: the associated value, or NULL if the key is not found.
<!-- ##### FUNCTION g_hash_table_lookup_extended ##### -->
<para>
-
+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().
</para>
-@hash_table:
-@lookup_key:
-@orig_key:
-@value:
-@Returns:
+@hash_table: a #GHashTable.
+@lookup_key: the key to look up.
+@orig_key: returns the original key.
+@value: returns the value associated with the key.
+@Returns: TRUE if the key was found in the #GHashTable.
<!-- ##### FUNCTION g_hash_table_foreach ##### -->
<para>
-
+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.
</para>
-@hash_table:
-@func:
-@user_data:
+@hash_table: a #GHashTable.
+@func: the function to call for each key/value pair.
+@user_data: use data to pass to the function.
<!-- ##### USER_FUNCTION GHFunc ##### -->
<para>
-
+Specifies the type of the function passed to g_hash_table_foreach().
+It is called with each key/value pair, together with the @user_data parameter
+which is passed to g_hash_table_foreach().
</para>
-@key:
-@value:
-@user_data:
+@key: a key.
+@value: the value corresponding to the key.
+@user_data: user data passed to g_hash_table_foreach().
<!-- ##### FUNCTION g_hash_table_remove ##### -->
<para>
-
+Removes a key and its associated value from a #GHashTable.
</para>
+<note>
+<para>
+As with g_hash_table_insert(), you should make sure that any dynamically
+allocated values are freed yourself.
+</para>
+</note>
-@hash_table:
-@key:
+@hash_table: a #GHashTable.
+@key: the key to remove.
<!-- ##### FUNCTION g_hash_table_foreach_remove ##### -->
<para>
-
+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.
</para>
-@hash_table:
-@func:
-@user_data:
-@Returns:
+@hash_table: a #GHashTable.
+@func: the function to call for each key/value pair.
+@user_data: user data to pass to the function.
+@Returns: the number of key/value paris removed.
<!-- ##### USER_FUNCTION GHRFunc ##### -->
<para>
-
+Specifies the type of the function passed to g_hash_table_foreach_remove().
+It is called with each key/value pair, together with the @user_data parameter
+passed to g_hash_table_foreach_remove().
+It should return TRUE if the key/value pair should be removed from the
+#GHashTable.
</para>
-@key:
-@value:
-@user_data:
-@Returns:
+@key: a key.
+@value: the value associated with the key.
+@user_data: user data passed to g_hash_table_remove().
+@Returns: TRUE if the key/value pair should be removed from the #GHashTable.
<!-- ##### FUNCTION g_hash_table_freeze ##### -->
<para>
-
+Disable resizing of a #GHashTable.
+</para>
+<para>
+This should be used if you need to make a lot of changes to a #GHashTable
+at once, as it reduces the number of times that the #GHashTable is rebuilt.
+You should call g_hash_table_thaw() after updating the #GHashTable to
+enable resizing again.
</para>
-@hash_table:
+@hash_table: a #GHashTable.
<!-- ##### FUNCTION g_hash_table_thaw ##### -->
<para>
-
+Enables resizing of a #GHashTable.
</para>
-@hash_table:
+@hash_table: a #GHashTable.
<!-- ##### FUNCTION g_hash_table_destroy ##### -->
<para>
-
+Destroys the #GHashTable.
+</para>
+<note>
+<para>
+If keys and/or values are dynamically allocated, you should free them
+first.
</para>
+</note>
-@hash_table:
+@hash_table: a #GHashTable.
<!-- ##### FUNCTION g_direct_equal ##### -->
<para>
-
+Compares two #gpointer arguments and returns TRUE if they are equal.
+It can be passed to g_hash_table_new() as the @key_compare_func
+parameter, when using pointers as keys in a #GHashTable.
</para>
-@v:
-@v2:
-@Returns:
+@v: a key.
+@v2: a key to compare with @v.
+@Returns: TRUE if the two keys match.
<!-- ##### FUNCTION g_direct_hash ##### -->
<para>
-
+Converts a gpointer to a hash value.
+It can be passed to g_hash_table_new() as the @hash_func parameter, when
+using gpointer values as keys in a #GHashTable.
</para>
-@v:
-@Returns:
+@v: a gpointer key.
+@Returns: a hash value corresponding to the key.
<!-- ##### FUNCTION g_int_equal ##### -->
<para>
-
+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_compare_func
+parameter, when using pointers to integers as keys in a #GHashTable.
</para>
-@v:
-@v2:
-@Returns:
+@v: a pointer to a #gint key.
+@v2: a pointer to a #gint key to compare with @v.
+@Returns: TRUE if the two keys match.
<!-- ##### FUNCTION g_int_hash ##### -->
<para>
-
+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 gint values as keys in a #GHashTable.
</para>
-@v:
-@Returns:
+@v: a pointer to a #gint key.
+@Returns: a hash value corresponding to the key.
<!-- ##### FUNCTION g_str_equal ##### -->
<para>
-
+Compares two strings and returns TRUE if they are equal.
+It can be passed to g_hash_table_new() as the @key_compare_func
+parameter, when using strings as keys in a #GHashTable.
</para>
-@v:
-@v2:
-@Returns:
+@v: a key.
+@v2: a key to compare with @v.
+@Returns: TRUE if the two keys match.
<!-- ##### FUNCTION g_str_hash ##### -->
<para>
-
+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.
</para>
-@v:
-@Returns:
+@v: a string key.
+@Returns: a hash value corresponding to the key.
Hook Functions
<!-- ##### SECTION Short_Description ##### -->
-
+support for manipulating lists of hook functions.
<!-- ##### SECTION Long_Description ##### -->
<para>
+The #GHookList, #GHook and their related functions provide support for
+lists of hook functions. Functions can be added and removed from the lists,
+and the list of hook functions can be invoked.
</para>
<!-- ##### STRUCT GHookList ##### -->
<para>
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>#guint seq_id;</entry>
+<entry>the next free #GHook id.</entry>
+</row>
+
+<row>
+<entry>#guint hook_size;</entry>
+<entry>the size of the #GHookList elements, in bytes.</entry>
+</row>
+
+<row>
+<entry>#guint is_setup : 1;</entry>
+<entry>1 if the #GHookList has been initialized.</entry>
+</row>
+
+<row>
+<entry>#GHook *hooks;</entry>
+<entry>the first #GHook element in the list.</entry>
+</row>
+
+<row>
+<entry>#GMemChunk *hook_memchunk;</entry>
+<entry>the #GMemChunk used for allocating the #GHook elements.</entry>
+</row>
+
+<row>
+<entry>#GHookFreeFunc hook_free;</entry>
+<entry>the function to call to free a #GHook element.</entry>
+</row>
+
+<row>
+<entry>#GHookFreeFunc hook_destroy;</entry>
+<entry>the function to call to destory a #GHook element.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+
</para>
@seq_id:
<!-- ##### STRUCT GHook ##### -->
<para>
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>#gpointer data;</entry>
+<entry>.</entry>
+</row>
+
+<row>
+<entry>#GHook *next;</entry>
+<entry>.</entry>
+</row>
+
+<row>
+<entry>#GHook *prev;</entry>
+<entry>.</entry>
+</row>
+
+<row>
+<entry>#guint ref_count;</entry>
+<entry>.</entry>
+</row>
+
+<row>
+<entry>#guint hook_id;</entry>
+<entry>.</entry>
+</row>
+
+<row>
+<entry>#guint flags;</entry>
+<entry>.</entry>
+</row>
+
+<row>
+<entry>#gpointer data;</entry>
+<entry>.</entry>
+</row>
+
+<row>
+<entry>#GDestroyNotify destroy;</entry>
+<entry>.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
</para>
@data:
<!-- ##### FUNCTION g_hook_list_init ##### -->
<para>
-
+Initializes a #GHookList.
+This must be called before the #GHookList is used.
</para>
-@hook_list:
-@hook_size:
+@hook_list: a #GHookList.
+@hook_size: the size of each element in the #GHookList, typically
+sizeof (GHook).
<!-- ##### FUNCTION g_hook_list_invoke ##### -->
<para>
-
+Calls all of the #GHook functions in a #GHookList.
</para>
-@hook_list:
-@may_recurse:
+@hook_list: a #GHookList.
+@may_recurse: TRUE if functions which are already running (e.g. in another
+thread) can be called. If set to FALSE, these are skipped.
<!-- ##### FUNCTION g_hook_list_invoke_check ##### -->
<para>
-
+Calls all of the #GHook functions in a #GHookList.
+Any function which returns TRUE is removed from the #GHookList.
</para>
-@hook_list:
-@may_recurse:
+@hook_list: a #GHookList.
+@may_recurse: TRUE if functions which are already running (e.g. in another
+thread) can be called. If set to FALSE, these are skipped.
<!-- ##### FUNCTION g_hook_list_marshal ##### -->
</para>
-@hook_list:
+@hook_list: a #GHookList.
@may_recurse:
@marshaller:
@data:
</para>
-@hook_list:
+@hook_list: a #GHookList.
@may_recurse:
@marshaller:
@data:
<!-- ##### FUNCTION g_hook_list_clear ##### -->
<para>
-
+Removes all the #GHook elements from a #GHookList.
</para>
-@hook_list:
+@hook_list: a #GHookList.
<!-- ##### FUNCTION g_hook_alloc ##### -->
<para>
-
+Allocates space for a #GHook and initializes it.
</para>
-@hook_list:
-@Returns:
+@hook_list: a #GHookList.
+@Returns: a new #GHook.
<!-- ##### MACRO g_hook_append ##### -->
<para>
-
+Appends a #GHook onto the end of a #GHookList.
</para>
-@hook_list:
-@hook:
+@hook_list: a #GHookList.
+@hook: the #GHook to add to the end of @hook_list.
<!-- ##### FUNCTION g_hook_prepend ##### -->
<para>
-
+Prepends a #GHook on the start of a #GHookList.
</para>
-@hook_list:
-@hook:
+@hook_list: a #GHookList.
+@hook: the #GHook to add to the start of @hook_list.
<!-- ##### FUNCTION g_hook_insert_before ##### -->
<para>
-
+Inserts a #GHook into a #GHookList, before a given #GHook.
</para>
-@hook_list:
-@sibling:
-@hook:
+@hook_list: a #GHookList.
+@sibling: the #GHook to insert the new #GHook before.
+@hook: the #GHook to insert.
<!-- ##### FUNCTION g_hook_insert_sorted ##### -->
<para>
-
+Inserts a #GHook into a #GHookList, sorted by the given function.
</para>
-@hook_list:
-@hook:
-@func:
+@hook_list: a #GHookList.
+@hook: the #GHook to insert.
+@func: the comparison function used to sort the #GHook elements.
<!-- ##### USER_FUNCTION GHookCompareFunc ##### -->
<para>
-
+Defines the type of function used to compare #GHook elements in
+g_hook_insert_sorted().
</para>
-@new_hook:
-@sibling:
-@Returns:
+@new_hook: the #GHook being inserted.
+@sibling: the #GHook to compare with @new_hook.
+@Returns: a value <= 0 if @new_hook should be before @sibling.
<!-- ##### FUNCTION g_hook_compare_ids ##### -->
<para>
-
+Compares the ids of two #GHook elements, returning a negative value
+if the second id is greater than the first.
</para>
-@new_hook:
-@sibling:
-@Returns:
+@new_hook: a #GHook.
+@sibling: a #GHook to compare with @new_hook.
+@Returns: a value <= 0 if the id of @sibling is >= the id of @new_hook.
<!-- ##### FUNCTION g_hook_get ##### -->
<para>
-
+Returns the #GHook with the given id, or NULL if it is not found.
</para>
-@hook_list:
-@hook_id:
-@Returns:
+@hook_list: a #GHookList.
+@hook_id: a hook id.
+@Returns: the #GHook with the given id, or NULL if it is not found.
<!-- ##### FUNCTION g_hook_find ##### -->
<para>
-
+Finds a #GHook in a #GHookList using the given function to test for a match.
</para>
-@hook_list:
-@need_valids:
-@func:
-@data:
-@Returns:
+@hook_list: a #GHookList.
+@need_valids: TRUE if #GHook elements which have been destroyed should be
+skipped.
+@func: the function to call for each #GHook, which should return TRUE when
+the #GHook has been found.
+@data: the data passed to @func.
+@Returns: the found #GHook or NULL if no matching #GHook is found.
<!-- ##### FUNCTION g_hook_find_data ##### -->
<para>
-
+Finds a #GHook in a #GHookList with the given data.
</para>
-@hook_list:
-@need_valids:
-@data:
-@Returns:
+@hook_list: a #GHookList.
+@need_valids: TRUE if #GHook elements which have been destroyed should be
+skipped.
+@data: the data to find.
+@Returns: the #GHook with the given @data or NULL if no matching
+#GHook is found.
<!-- ##### FUNCTION g_hook_find_func ##### -->
<para>
-
+Finds a #GHook in a #GHookList with the given function.
</para>
-@hook_list:
-@need_valids:
-@func:
-@Returns:
+@hook_list: a #GHookList.
+@need_valids: TRUE if #GHook elements which have been destroyed should be
+skipped.
+@func: the function to find.
+@Returns: the #GHook with the given @func or NULL if no matching
+#GHook is found.
<!-- ##### USER_FUNCTION GHookFindFunc ##### -->
<para>
-
+Defines the type of the function passed to g_hooK_find_func().
</para>
-@hook:
-@data:
-@Returns:
+@hook: a #GHook.
+@data: user data passed to g_hook_find_func().
+@Returns: TRUE if the required #GHook has been found.
<!-- ##### FUNCTION g_hook_find_func_data ##### -->
<para>
-
+Finds a #GHook in a #GHookList with the given function and data.
</para>
-@hook_list:
-@need_valids:
-@func:
-@data:
-@Returns:
+@hook_list: a #GHookList.
+@need_valids: TRUE if #GHook elements which have been destroyed should be
+skipped.
+@func: the function to find.
+@data: the data to find.
+@Returns: the #GHook with the given @func and @data or NULL if no matching
+#GHook is found.
<!-- ##### FUNCTION g_hook_first_valid ##### -->
<para>
-
+Returns the first #GHook in a #GHookList which has not been destroyed.
+The reference count for the #GHook is incremented, so you must call
+g_hook_unref() to restore it when no longer needed. (Or call
+g_hook_next_valid() if you are stepping through the #GHookList.)
</para>
-@hook_list:
-@may_be_in_call:
-@Returns:
+@hook_list: a #GHookList.
+@may_be_in_call: TRUE if hooks which are currently running (e.g. in another
+thread) are considered valid. If set to FALSE, these are skipped.
+@Returns: the first valid #GHook, or NULL if none are valid.
<!-- ##### FUNCTION g_hook_next_valid ##### -->
<para>
+Returns the next #GHook in a #GHookList which has not been destroyed.
+The reference count for the #GHook is incremented, so you must call
+g_hook_unref() to restore it when no longer needed. (Or continue to call
+g_hook_next_valid() until NULL is returned.)
</para>
-@hook_list:
-@hook:
-@may_be_in_call:
-@Returns:
+@hook_list: a #GHookList.
+@hook: the current #GHook.
+@may_be_in_call: TRUE if hooks which are currently running (e.g. in another
+thread) are considered valid. If set to FALSE, these are skipped.
+@Returns: the next valid #GHook, or NULL if none are valid.
<!-- ##### ENUM GHookFlagMask ##### -->
<!-- ##### MACRO G_HOOK_IS_VALID ##### -->
<para>
-
+Returns TRUE if the #GHook is valid, i.e. it is in a #GHookList, it is active
+and it has not been destroyed.
</para>
-@hook:
+@hook: a #GHook.
+@Returns: TRUE if the #GHook is valid.
<!-- ##### MACRO G_HOOK_ACTIVE ##### -->
<para>
-
+Returns TRUE if the #GHook is active, which is normally TRUE until the #GHook
+is destroyed.
</para>
-@hook:
+@hook: a #GHook.
+@Returns: TRUE if the #GHook is active.
<!-- ##### MACRO G_HOOK_IN_CALL ##### -->
<para>
-
+Returns TRUE if the #GHook function is currently executing.
</para>
-@hook:
+@hook: a #GHook.
+@Returns: TRUE if the #GHook function is currently executing.
<!-- ##### MACRO G_HOOK_IS_UNLINKED ##### -->
<para>
+Returns TRUE if the #GHook is not in a #GHookList.
</para>
-@hook:
+@hook: a #GHook.
+@Returns: TRUE if the #GHook is not in a #GHookList.
<!-- ##### FUNCTION g_hook_ref ##### -->
<para>
-
+Increments the reference count for a #GHook.
</para>
-@hook_list:
-@hook:
+@hook_list: a #GHookList.
+@hook: the #GHook to increment the reference count of.
<!-- ##### FUNCTION g_hook_unref ##### -->
<para>
-
+Decrements the reference count of a #GHook.
+If the reference count falls to 0, the #GHook is removed from the #GHookList
+and g_hook_free() is called to free it.
</para>
-@hook_list:
+@hook_list: a #GHookList.
@hook:
<!-- ##### FUNCTION g_hook_free ##### -->
<para>
-
+Calls the #GHookList @hook_free function if it exists, and frees the memory
+allocated for the #GHook.
</para>
-@hook_list:
-@hook:
+@hook_list: a #GHookList.
+@hook: the #GHook to free.
<!-- ##### FUNCTION g_hook_destroy ##### -->
<para>
-
+Destroys a #GHook, given its ID.
</para>
-@hook_list:
-@hook_id:
-@Returns:
+@hook_list: a #GHookList.
+@hook_id: a hook ID.
+@Returns: TRUE if the #GHook was found in the #GHookList and destroyed.
<!-- ##### FUNCTION g_hook_destroy_link ##### -->
<para>
-
+Removes one #GHook from a #GHookList, calling the @hook_destroy function in
+the #GHookList, and the @destroy function of the #GHook, if they exist.
</para>
-@hook_list:
-@hook:
+@hook_list: a #GHookList.
+@hook: the #GHook to remove.
IO Channels
<!-- ##### SECTION Short_Description ##### -->
-
+portable support for using files, pipes and sockets.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GIOChannel data type aims to provide a portable method for using file
+descriptors, pipes, and sockets, and integrating them into the
+<link linkend="glib-The-Main-Event-Loop">main event loop</link>.
+Currently full support is available on Unix platforms, though support for
+Windows is only partially complete.
+</para>
+<para>
+To create a new #GIOChannel on Unix systems use g_io_channel_unix_new().
+This works for plain file descriptors, pipes and sockets.
+</para>
+<para>
+Once a #GIOChannel has been created, it can be used in a generic manner
+with the functions g_io_channel_read(), g_io_channel_write(),
+g_io_channel_seek(), and g_io_channel_close().
+</para>
+<para>
+To add a #GIOChannel to the
+<link linkend="glib-The-Main-Event-Loop">main event loop</link>
+use g_io_add_watch() or g_io_add_watch_full(). Here you specify which events
+you are interested in on the #GIOChannel, and provide a function to be
+called whenever these events occur.
+</para>
+<para>
+#GIOChannel instances are created with an initial reference count of 1.
+g_io_channel_ref() and g_io_channel_unref() can be used to increment or
+decrement the reference count respectively. When the reference count falls
+to 0, the #GIOChannel is freed. (Though it isn't closed automatically.)
+Using g_io_add_watch() or g_io_add_watch_full() increments a channel's
+reference count.
+</para>
+<para>
+GTK+ contains the convenience function gtk_input_add_full()
+which creates a #GIOChannel from a file descriptor and adds it to the
+<link linkend="glib-The-Main-Event-Loop">main event loop</link>.
+The event source can later be removed with gtk_input_remove().
+Similar functions can also be found in GDK.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<variablelist>
+
+<varlistentry>
+<term>gtk_input_add_full(), gtk_input_remove(), gdk_input_add(),
+gdk_input_add_full(), gdk_input_remove()</term>
+<listitem><para>
+Convenience functions for creating #GIOChannel instances and adding them to the
+<link linkend="glib-The-Main-Event-Loop">main event loop</link>.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
</para>
<!-- ##### STRUCT GIOChannel ##### -->
<para>
-
+A data structure representing an IO Channel. The fields should be considered
+private and should only be accessed with the following functions.
</para>
@channel_flags:
<!-- ##### FUNCTION g_io_channel_unix_new ##### -->
<para>
-
+Creates a new #GIOChannel given a file descriptor.
+On Unix systems this works for plain files, pipes, and sockets.
+</para>
+<para>
+The returned #GIOChannel has a reference count of 1.
</para>
-@fd:
-@Returns:
+@fd: a file descriptor.
+@Returns: a new #GIOChannel.
<!-- ##### FUNCTION g_io_channel_unix_get_fd ##### -->
<para>
-
+Returns the file descriptor of the Unix #GIOChannel.
</para>
-@channel:
-@Returns:
+@channel: a #GIOChannel, created with g_io_channel_unix_new().
+@Returns: the file descriptor of the #GIOChannel.
<!-- ##### FUNCTION g_io_channel_init ##### -->
<para>
-
+Initializes a #GIOChannel struct. This is called by each of the above functions
+when creating a #GIOChannel, and so is not often needed by the application
+programmer (unless you are creating a new type of #GIOChannel).
</para>
-@channel:
+@channel: a #GIOChannel.
<!-- ##### FUNCTION g_io_channel_read ##### -->
<para>
-
+Reads data from a #GIOChannel.
</para>
-@channel:
-@buf:
-@count:
-@bytes_read:
-@Returns:
+@channel: a #GIOChannel.
+@buf: a buffer to read the data into (which should be at least count bytes
+long).
+@count: the number of bytes to read from the #GIOChannel.
+@bytes_read: returns the number of bytes actually read.
+@Returns: %G_IO_ERROR_NONE if the operation was successful.
<!-- ##### ENUM GIOError ##### -->
<!-- ##### FUNCTION g_io_channel_write ##### -->
<para>
-
+Writes data to a #GIOChannel.
</para>
-@channel:
-@buf:
-@count:
-@bytes_written:
-@Returns:
+@channel: a #GIOChannel.
+@buf: the buffer containing the data to write.
+@count: the number of bytes to write.
+@bytes_written: the number of bytes actually written.
+@Returns: %G_IO_ERROR_NONE if the operation was successful.
<!-- ##### FUNCTION g_io_channel_seek ##### -->
<para>
-
+Sets the current position in the #GIOChannel, similar to the standard system
+call <function>fseek()</function>.
</para>
-@channel:
-@offset:
-@type:
-@Returns:
+@channel: a #GIOChannel.
+@offset: an offset, in bytes, which is added to the position specified by
+@type.
+@type: 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).
+@Returns: %G_IO_ERROR_NONE if the operation was successful.
<!-- ##### ENUM GSeekType ##### -->
<para>
+An enumeration specifying the base position for a g_io_channel_seek()
+operation.
+
+<informaltable pgwide=1 frame="none" role="enum">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>G_SEEK_CUR</entry>
+<entry>the current position in the file.</entry>
+</row>
+
+<row>
+<entry>G_SEEK_SET</entry>
+<entry>the start of the file.</entry>
+</row>
+
+<row>
+<entry>G_SEEK_END</entry>
+<entry>the end of the file.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
</para>
<!-- ##### FUNCTION g_io_channel_close ##### -->
<para>
-
+Closes a #GIOChannel.
+The #GIOChannel will be freed when its reference count drops to 0.
</para>
-@channel:
+@channel: a #GIOChannel.
<!-- ##### FUNCTION g_io_channel_ref ##### -->
<para>
-
+Increments the reference count of a #GIOChannel.
</para>
-@channel:
+@channel: a #GIOChannel.
<!-- ##### FUNCTION g_io_channel_unref ##### -->
<para>
-
+Decrements the reference count of a #GIOChannel.
</para>
-@channel:
+@channel: a #GIOChannel.
<!-- ##### FUNCTION g_io_add_watch ##### -->
<para>
-
+Adds the #GIOChannel into the
+<link linkend="glib-The-Main-Event-Loop">main event loop</link>
+with the default priority.
</para>
-@channel:
-@condition:
-@func:
-@user_data:
-@Returns:
+@channel: a #GIOChannel.
+@condition: the condition to watch for.
+@func: the function to call when the condition is satisfied.
+@user_data: user data to pass to @func.
+@Returns: the event source id.
<!-- ##### FUNCTION g_io_add_watch_full ##### -->
<para>
-
+Adds the #GIOChannel into the
+<link linkend="glib-The-Main-Event-Loop">main event loop</link>
+with the given priority.
</para>
-@channel:
-@priority:
-@condition:
-@func:
-@user_data:
-@notify:
-@Returns:
+@channel: a #GIOChannel.
+@priority: the priority of the #GIOChannel source.
+@condition: the condition to watch for.
+@func: the function to call when the condition is satisfied.
+@user_data: user data to pass to @func.
+@notify: the function to call when the source is removed.
+@Returns: the event source id.
<!-- ##### ENUM GIOCondition ##### -->
<para>
+A bitwise combination representing a condition to watch for on an event
+source.
+
+<informaltable pgwide=1 frame="none" role="enum">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>G_IO_IN</entry>
+<entry>There is data to read.</entry>
+</row>
+
+<row>
+<entry>G_IO_OUT</entry>
+<entry>Data can be written (without blocking).</entry>
+</row>
+
+<row>
+<entry>G_IO_PRI</entry>
+<entry>There is urgent data to read.</entry>
+</row>
+
+<row>
+<entry>G_IO_ERR</entry>
+<entry>Error condition.</entry>
+</row>
+
+<row>
+<entry>G_IO_HUP</entry>
+<entry>Hung up (the connection has been broken, usually for pipes and
+sockets).</entry>
+</row>
+
+<row>
+<entry>G_IO_NVAL</entry>
+<entry>Invalid request. The file descriptor is not open.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
</para>
<!-- ##### USER_FUNCTION GIOFunc ##### -->
<para>
-
+Specifies the type of function passed to g_io_add_watch() or
+g_io_add_watch_full(), which is called when the requested condition on a
+#GIOChannel is satisfied.
</para>
-@source:
-@condition:
-@data:
-@Returns:
+@source: the #GIOChannel event source.
+@condition: the condition which has been satisfied.
+@data: user data set in g_io_add_watch() or g_io_add_watch_full().
+@Returns: the function should return FALSE if the event source should be
+removed.
<!-- ##### STRUCT GIOFuncs ##### -->
<para>
-
+A table of functions used to handle different types of #GIOChannel in a
+generic way.
</para>
@io_read:
Limits of Basic Types
<!-- ##### SECTION Short_Description ##### -->
-
+portable method of determining the limits of the standard types.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+These macros provide a portable method to determine the limits of some of
+the standard integer and floating point types.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### MACRO G_MININT ##### -->
<para>
-
+The minimum value which can be held in a #gint.
</para>
<!-- ##### MACRO G_MAXINT ##### -->
<para>
-
+The maximum value which can be held in a #gint.
</para>
<!-- ##### MACRO G_MINSHORT ##### -->
<para>
-
+The minimum value which can be held in a #gshort.
</para>
<!-- ##### MACRO G_MAXSHORT ##### -->
<para>
-
+The maximum value which can be held in a #gshort.
</para>
<!-- ##### MACRO G_MINLONG ##### -->
<para>
-
+The minimum value which can be held in a #glong.
</para>
<!-- ##### MACRO G_MAXLONG ##### -->
<para>
-
+The maximum value which can be held in a #glong.
</para>
<!-- ##### MACRO G_MINFLOAT ##### -->
<para>
-
+The minimum value which can be held in a #gfloat.
</para>
<!-- ##### MACRO G_MAXFLOAT ##### -->
<para>
-
+The maximum value which can be held in a #gfloat.
</para>
<!-- ##### MACRO G_MINDOUBLE ##### -->
<para>
-
+The minimum value which can be held in a #gdouble.
</para>
<!-- ##### MACRO G_MAXDOUBLE ##### -->
<para>
-
+The maximum value which can be held in a #gdouble.
</para>
Doubly-Linked Lists
<!-- ##### SECTION Short_Description ##### -->
-
+linked lists containing integer values or pointers to data, with the ability
+to iterate over the list in both directions.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GList structure and its associated functions provide a standard
+doubly-linked list data structure.
+</para>
+<para>
+Each element in the list contains a piece of data, together with pointers
+which link to the previous and next elements in the list.
+Using these pointers it is possible to move through the list in both
+directions (unlike the
+<link linkend="glib-Singly-Linked-lists">Singly-Linked Lists</link>
+which only allows movement through the list in the forward direction).
+</para>
+<para>
+The data contained in each element can be either integer values, by using one
+of the
+<link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>,
+or simply pointers to any type of data.
+</para>
+<para>
+List elements are allocated in blocks using a #GListAllocator, which is
+more efficient than allocating elements individually.
+</para>
+<para>
+Note that most of the #GList functions expect to be passed a pointer to
+the first element in the list. The functions which insert elements return
+the new start of the list, which may have changed.
+</para>
+<para>
+There is no function to create a #GList. NULL is considered to be the empty
+list so you simply set a #GList* to NULL.
+</para>
+<para>
+To add elements, use g_list_append(), g_list_prepend(), g_list_insert()
+and g_list_insert_sorted().
+</para>
+<para>
+To remove elements, use g_list_remove().
+</para>
+<para>
+To find elements in the list use g_list_first(), g_list_last(), g_list_next(),
+g_list_previous(), g_list_nth(), g_list_nth_data(), g_list_find() and
+g_list_find_custom().
+</para>
+<para>
+To find the index of an element use g_list_position() and g_list_index().
+</para>
+<para>
+To call a function for each element in the list use g_list_foreach().
+</para>
+<para>
+To free the entire list, use g_list_free().
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GList ##### -->
<para>
-
+The #GList struct is used for each element in a doubly-linked list.
+The <structfield>data</structfield> field holds the element's data, which can
+be a pointer to any kind of data, or any integer value using the
+<link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>.
+The <structfield>next</structfield> and <structfield>prev</structfield>
+pointers are the links to the next and previous elements in the list.
</para>
@data:
<!-- ##### FUNCTION g_list_append ##### -->
<para>
-
+Adds a new element on to the end of the list.
</para>
+<note>
+<para>
+The return value is the new start of the list, which may have changed, so
+make sure you store the new value.
+</para>
+</note>
+<informalexample><programlisting>
+ /* Notice that these are initialized to the empty list. */
+ GList *list = NULL, *number_list = NULL;
-@list:
-@data:
-@Returns:
+ /* This is a list of strings. */
+ list = g_list_append (list, "first");
+ list = g_list_append (list, "second");
+
+ /* This is a list of integers. */
+ number_list = g_list_append (number_list, GINT_TO_POINTER (27));
+ number_list = g_list_append (number_list, GINT_TO_POINTER (14));
+</programlisting></informalexample>
+
+@list: a pointer to a #GList.
+@data: the data for the new element.
+@Returns: the new start of the #GList.
<!-- ##### FUNCTION g_list_prepend ##### -->
<para>
-
+Adds a new element on to the start of the list.
+</para>
+<note>
+<para>
+The return value is the new start of the list, which may have changed, so
+make sure you store the new value.
</para>
+</note>
+<informalexample><programlisting>
+ /* Notice that it is initialized to the empty list. */
+ GList *list = NULL;
+ list = g_list_prepend (list, "last");
+ list = g_list_prepend (list, "first");
+</programlisting></informalexample>
-@list:
-@data:
-@Returns:
+@list: a pointer to a #GList.
+@data: the data for the new element.
+@Returns: the new start of the #GList.
<!-- ##### FUNCTION g_list_insert ##### -->
<para>
-
+Inserts a new element into the list at the given position.
</para>
-@list:
-@data:
-@position:
-@Returns:
+@list: a pointer to a #GList.
+@data: the data for the new element.
+@position: the position to insert the element. If this is negative, or is
+larger than the number of elements in the list, the new element is added on
+to the end of the list.
+@Returns: the new start of the #GList.
<!-- ##### FUNCTION g_list_insert_sorted ##### -->
<para>
-
+Inserts a new element into the list, using the given comparison function
+to determine its position.
</para>
-@list:
-@data:
-@func:
-@Returns:
+@list: a pointer to a #GList.
+@data: the data for the new element.
+@func: the function to compare elements in the list. It should return a
+number > 0 if the first parameter comes after the second parameter in
+the sort order.
+@Returns: the new start of the #GList.
<!-- ##### FUNCTION g_list_remove ##### -->
<para>
-
+Removes an element from a #GList.
+If two elements contain the same data, only the first is removed.
+If none of the elements contain the data, the #GList is unchanged.
</para>
-@list:
-@data:
-@Returns:
+@list: a #GList.
+@data: the data of the element to remove.
+@Returns: the new start of the #GList.
<!-- ##### FUNCTION g_list_remove_link ##### -->
<para>
-
+Removes an element from a #GList, without freeing the element.
+The removed element's prev and next links are set to NULL, so that it becomes a
+self-contained list with one element.
</para>
-@list:
-@llink:
-@Returns:
+@list: a #GList.
+@llink: an element in the #GList.
+@Returns: the new start of the #GList, without the element.
<!-- ##### FUNCTION g_list_delete_link ##### -->
<!-- ##### FUNCTION g_list_free ##### -->
<para>
-
+Frees all of the memory used by a #GList.
+The freed elements are added to the #GListAllocator free list.
+</para>
+<note>
+<para>
+If list elements contain dynamically-allocated memory, they should be freed
+first.
</para>
+</note>
@list:
<!-- ##### FUNCTION g_list_alloc ##### -->
<para>
-
+Allocates space for one #GList element.
+It is called by g_list_append(), g_list_prepend(), g_list_insert() and
+g_list_insert_sorted() and so is rarely used on its own.
</para>
-@Returns:
+@Returns: a pointer to the newly-allocated #GList element.
<!-- ##### FUNCTION g_list_free_1 ##### -->
<para>
-
+Frees one #GList element.
+It is usually used after g_list_remove_link().
</para>
-@list:
+@list: a #GList element.
<!-- ##### FUNCTION g_list_length ##### -->
<para>
-
+Gets the number of elements in a #GList.
</para>
-@list:
-@Returns:
+@list: a #GList.
+@Returns: the number of elements in the #GList.
<!-- ##### FUNCTION g_list_copy ##### -->
<para>
-
+Copies a #GList.
+</para>
+<para>
+Note that this is a "shallow" copy. If the list elements consist of pointers
+to data, the pointers are copied but the actual data isn't.
</para>
-@list:
-@Returns:
+@list: a #GList.
+@Returns: a copy of @list.
<!-- ##### FUNCTION g_list_reverse ##### -->
<para>
-
+Reverses a #GList.
+It simply switches the next and prev pointers of each element.
</para>
-@list:
-@Returns:
+@list: a #GList.
+@Returns: the start of the reversed #GList.
<!-- ##### FUNCTION g_list_sort ##### -->
<para>
-
+Sorts a #GList using the given comparison function.
</para>
-@list:
-@compare_func:
-@Returns:
+@list: a #GList.
+@compare_func: the comparison function used to sort the #GList. This function
+is passed 2 elements of the #GList and should return 0 if they are equal,
+a negative value if the first element comes before the second, or a positive
+value if the first element comes after the second.
+@Returns: the start of the sorted #GList.
<!-- ##### FUNCTION g_list_concat ##### -->
<para>
-
+Adds the second #GList onto the end of the first #GList.
+Note that the elements of the second #GList are not copied.
+They are used directly.
</para>
-@list1:
-@list2:
-@Returns:
+@list1: a #GList.
+@list2: the #GList to add to the end of the first #GList.
+@Returns: the start of the new #GList.
<!-- ##### FUNCTION g_list_foreach ##### -->
<para>
-
+Calls a function for each element of a #GList.
</para>
-@list:
-@func:
-@user_data:
+@list: a #GList.
+@func: the function to call with each element's data.
+@user_data: user data to pass to the function.
<!-- ##### USER_FUNCTION GFunc ##### -->
<para>
-
+Specifies the type of functions passed to g_list_foreach() and
+g_slist_foreach().
</para>
-@data:
-@user_data:
+@data: the element's data.
+@user_data: user data passed to g_list_foreach() or g_slist_foreach().
<!-- ##### FUNCTION g_list_first ##### -->
<para>
-
+Gets the first element in a #GList.
</para>
-@list:
-@Returns:
+@list: a #GList.
+@Returns: the first element in a #GList, or NULL if the #GList has no elements.
<!-- ##### FUNCTION g_list_last ##### -->
<para>
-
+Gets the last element in a #GList.
</para>
-@list:
-@Returns:
+@list: a #GList.
+@Returns: the last element in the #GList, or NULL if the #GList has no
+elements.
<!-- ##### MACRO g_list_previous ##### -->
<para>
-
+A convenience macro to gets the previous element in a #GList.
</para>
-@list:
+@list: an element in a #GList.
+@Returns: the previous element, or NULL if there are no previous elements.
<!-- ##### MACRO g_list_next ##### -->
<para>
-
+A convenience macro to gets the next element in a #GList.
</para>
-@list:
+@list: an element in a #GList.
+@Returns: the next element, or NULL if there are no more elements.
<!-- ##### FUNCTION g_list_nth ##### -->
<para>
-
+Gets the element at the given position in a #GList.
</para>
-@list:
-@n:
-@Returns:
+@list: a #GList.
+@n: the position of the element, counting from 0.
+@Returns: the element, or NULL if the position is off the end of the #GList.
<!-- ##### FUNCTION g_list_nth_data ##### -->
<para>
-
+Gets the data of the element at the given position.
</para>
-@list:
-@n:
-@Returns:
+@list: a #GList.
+@n: the position of the element.
+@Returns: the element's data, or NULL if the position is off the end of the
+#GList.
<!-- ##### FUNCTION g_list_find ##### -->
<para>
-
+Finds the element in a #GList which contains the given data.
</para>
-@list:
-@data:
-@Returns:
+@list: a #GList.
+@data: the element data to find.
+@Returns: the found #GList element, or NULL if it is not found.
<!-- ##### FUNCTION g_list_find_custom ##### -->
<para>
-
+Finds an element in a #GList, using a supplied function to find the desired
+element.
+It iterates over the list, calling the given function which should return 0
+when the desired element is found.
+The function takes two #gconstpointer arguments, the #GList element's data
+and the given user data.
</para>
-@list:
-@data:
-@func:
-@Returns:
+@list: a #GList.
+@data: user data passed to the function.
+@func: the function to call for each element. It should return 0 when the
+desired element is found.
+@Returns: the found #GList element, or NULL if it is not found.
<!-- ##### FUNCTION g_list_position ##### -->
<para>
-
+Gets the position of the given element in the #GList (starting from 0).
</para>
-@list:
-@llink:
-@Returns:
+@list: a #GList.
+@llink: an element in the #GList.
+@Returns: the position of the element in the #GList, or -1 if the element is
+not found.
<!-- ##### FUNCTION g_list_index ##### -->
<para>
-
+Gets the position of the element containing the given data (starting from 0).
</para>
-@list:
-@data:
-@Returns:
+@list: a #GList.
+@data: the data to find.
+@Returns: the index of the element containing the data, or -1 if the data
+is not found.
<!-- ##### FUNCTION g_list_push_allocator ##### -->
<para>
-
+Sets the allocator to use to allocate #GList elements.
+Use g_list_pop_allocator() to restore the previous allocator.
</para>
-@allocator:
+@allocator: the #GAllocator to use when allocating #GList elements.
<!-- ##### FUNCTION g_list_pop_allocator ##### -->
<para>
-
+Restores the previous #GAllocator, used when allocating #GList elements.
</para>
Singly-Linked Lists
<!-- ##### SECTION Short_Description ##### -->
-
+linked lists containing integer values or pointers to data, limited to
+iterating over the list in one direction.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GSList structure and its associated functions provide a standard
+singly-linked list data structure.
+</para>
+<para>
+Each element in the list contains a piece of data, together with a pointer
+which links to the next element in the list.
+Using this pointer it is possible to move through the list in one
+direction only (unlike the
+<link linkend="glib-Doubly-Linked-lists">Doubly-Linked Lists</link>
+which allow movement in both directions).
+</para>
+<para>
+The data contained in each element can be either integer values, by using one
+of the
+<link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>,
+or simply pointers to any type of data.
+</para>
+<para>
+List elements are allocated in blocks using a #GListAllocator, which is
+more efficient than allocating elements individually.
+</para>
+<para>
+Note that most of the #GSList functions expect to be passed a pointer to
+the first element in the list. The functions which insert elements return
+the new start of the list, which may have changed.
+</para>
+<para>
+There is no function to create a #GSList. NULL is considered to be the empty
+list so you simply set a #GSList* to NULL.
+</para>
+<para>
+To add elements, use g_slist_append(), g_slist_prepend(), g_slist_insert()
+and g_slist_insert_sorted().
+</para>
+<para>
+To remove elements, use g_slist_remove().
+</para>
+<para>
+To find elements in the list use g_slist_last(), g_slist_next(),
+g_slist_nth(), g_slist_nth_data(), g_slist_find() and
+g_slist_find_custom().
+</para>
+<para>
+To find the index of an element use g_slist_position() and g_slist_index().
+</para>
+<para>
+To call a function for each element in the list use g_slist_foreach().
+</para>
+<para>
+To free the entire list, use g_slist_free().
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GSList ##### -->
<para>
-
+The #GSList struct is used for each element in the singly-linked list.
+The <structfield>data</structfield> field holds the element's data, which can
+be a pointer to any kind of data, or any integer value using the
+<link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>.
+The <structfield>next</structfield> field contains the link to the next
+element in the list.
</para>
@data:
<!-- ##### FUNCTION g_slist_alloc ##### -->
<para>
-
+Allocates space for one #GSList element.
+It is called by the g_slist_append(), g_slist_prepend(), g_slist_insert() and
+g_slist_insert_sorted() functions and so is rarely used on its own.
</para>
-@Returns:
+@Returns: a pointer to the newly-allocated #GSList element.
<!-- ##### FUNCTION g_slist_append ##### -->
<para>
-
+Adds a new element on to the end of the list.
+</para>
+<note>
+<para>
+The return value is the new start of the list, which may have changed, so
+make sure you store the new value.
</para>
+</note>
+<informalexample><programlisting>
+ /* Notice that these are initialized to the empty list. */
+ GSList *list = NULL, *number_list = NULL;
-@list:
-@data:
-@Returns:
+ /* This is a list of strings. */
+ list = g_slist_append (list, "first");
+ list = g_slist_append (list, "second");
+
+ /* This is a list of integers. */
+ number_list = g_slist_append (number_list, GINT_TO_POINTER (27));
+ number_list = g_slist_append (number_list, GINT_TO_POINTER (14));
+</programlisting></informalexample>
+
+@list: a #GSList.
+@data: the data for the new element.
+@Returns: the new start of the #GSList.
<!-- ##### FUNCTION g_slist_prepend ##### -->
<para>
-
+Adds a new element on to the start of the list.
+</para>
+<note>
+<para>
+The return value is the new start of the list, which may have changed, so
+make sure you store the new value.
</para>
+</note>
+<informalexample><programlisting>
+ /* Notice that it is initialized to the empty list. */
+ GSList *list = NULL;
+ list = g_slist_prepend (list, "last");
+ list = g_slist_prepend (list, "first");
+</programlisting></informalexample>
-@list:
-@data:
-@Returns:
+@list: a #GSList.
+@data: the data for the new element.
+@Returns: the new start of the #GSList.
<!-- ##### FUNCTION g_slist_insert ##### -->
<para>
-
+Inserts a new element into the list at the given position.
</para>
-@list:
-@data:
-@position:
-@Returns:
+@list: a #GSList.
+@data: the data for the new element.
+@position: the position to insert the element. If this is negative, or is
+larger than the number of elements in the list, the new element is added on
+to the end of the list.
+@Returns: the new start of the #GSList.
<!-- ##### FUNCTION g_slist_insert_before ##### -->
<!-- ##### FUNCTION g_slist_insert_sorted ##### -->
<para>
-
+Inserts a new element into the list, using the given comparison function
+to determine its position.
</para>
-@list:
-@data:
-@func:
-@Returns:
+@list: a #GSList.
+@data: the data for the new element.
+@func: the function to compare elements in the list. It should return a
+number > 0 if the first parameter comes after the second parameter in
+the sort order.
+@Returns: the new start of the #GSList.
<!-- ##### FUNCTION g_slist_remove ##### -->
<para>
-
+Removes an element from a #GSList.
+If two elements contain the same data, only the first is removed.
+If none of the elements contain the data, the #GSList is unchanged.
</para>
-@list:
-@data:
-@Returns:
+@list: a #GSList.
+@data: the data of the element to remove.
+@Returns: the new start of the #GSList.
<!-- ##### FUNCTION g_slist_remove_link ##### -->
<para>
-
+Removes an element from a #GSList, without freeing the element.
+The removed element's next link is set to NULL, so that it becomes a
+self-contained list with one element.
</para>
-@list:
+@list: a #GSList.
@link:
-@Returns:
+@Returns: the new start of the #GSList, without the element.
+<!-- # Unused Parameters # -->
+@llink: an element in the #GSList.
<!-- ##### FUNCTION g_slist_delete_link ##### -->
<!-- ##### FUNCTION g_slist_free ##### -->
<para>
-
+Frees all of the memory used by a #GSList.
+The freed elements are added to the #GListAllocator free list.
</para>
-@list:
+@list: a #GSList.
<!-- ##### FUNCTION g_slist_free_1 ##### -->
<para>
-
+Frees one #GSList element.
+It is usually used after g_slist_remove_link().
</para>
-@list:
+@list: a #GSList element.
<!-- ##### FUNCTION g_slist_length ##### -->
<para>
-
+Gets the number of elements in a #GSList.
</para>
-@list:
-@Returns:
+@list: a #GSList.
+@Returns: the number of elements in the #GSList.
<!-- ##### FUNCTION g_slist_copy ##### -->
<para>
-
+Copies a #GSList.
+</para>
+<para>
+Note that this is a "shallow" copy. If the list elements consist of pointers
+to data, the pointers are copied but the actual data isn't.
</para>
-@list:
-@Returns:
+@list: a #GSList.
+@Returns: a copy of @list.
<!-- ##### FUNCTION g_slist_reverse ##### -->
<para>
-
+Reverses a #GSList.
</para>
-@list:
-@Returns:
+@list: a #GSList.
+@Returns: the start of the reversed #GSList.
<!-- ##### FUNCTION g_slist_sort ##### -->
<para>
-
+Sorts a #GSList using the given comparison function.
</para>
-@list:
-@compare_func:
-@Returns:
+@list: a #GSList.
+@compare_func: the comparison function used to sort the #GSList. This function
+is passed 2 elements of the #GSList and should return 0 if they are equal,
+a negative value if the first element comes before the second, or a positive
+value if the first element comes after the second.
+@Returns: the start of the sorted #GList.
<!-- ##### FUNCTION g_slist_concat ##### -->
<para>
-
+Adds the second #GSList onto the end of the first #GSList.
+Note that the elements of the second #GSList are not copied.
+They are used directly.
</para>
-@list1:
-@list2:
-@Returns:
+@list1: a #GSList.
+@list2: the #GSList to add to the end of the first #GSList.
+@Returns: the start of the new #GSList.
<!-- ##### FUNCTION g_slist_foreach ##### -->
<para>
-
+Calls a function for each element of a #GSList.
</para>
-@list:
-@func:
-@user_data:
+@list: a #GSList.
+@func: the function to call with each element's data.
+@user_data: user data to pass to the function.
<!-- ##### FUNCTION g_slist_last ##### -->
<para>
-
+Gets the last element in a #GSList.
</para>
-@list:
-@Returns:
+@list: a #GSList.
+@Returns: the last element in the #GSList, or NULL if the #GSList has no
+elements.
<!-- ##### MACRO g_slist_next ##### -->
<para>
-
+A convenience macro to gets the next element in a #GSList.
</para>
-@slist:
+@slist: an element in a #GSList.
+@Returns: the next element, or NULL if there are no more elements.
<!-- ##### FUNCTION g_slist_nth ##### -->
<para>
-
+Gets the element at the given position in a #GSList.
</para>
-@list:
-@n:
-@Returns:
+@list: a #GSList.
+@n: the position of the element, counting from 0.
+@Returns: the element, or NULL if the position is off the end of the #GSList.
<!-- ##### FUNCTION g_slist_nth_data ##### -->
<para>
-
+Gets the data of the element at the given position.
</para>
-@list:
-@n:
-@Returns:
+@list: a #GSList.
+@n: the position of the element.
+@Returns: the element's data, or NULL if the position is off the end of the
+#GSList.
<!-- ##### FUNCTION g_slist_find ##### -->
<para>
-
+Finds the element in a #GSList which contains the given data.
</para>
-@list:
-@data:
-@Returns:
+@list: a #GSList.
+@data: the element data to find.
+@Returns: the found #GSList element, or NULL if it is not found.
<!-- ##### FUNCTION g_slist_find_custom ##### -->
<para>
-
+Finds an element in a #GSList, using a supplied function to find the desired
+element.
+It iterates over the list, calling the given function which should return 0
+when the desired element is found.
+The function takes two #gconstpointer arguments, the #GSList element's data
+and the given user data.
</para>
-@list:
-@data:
-@func:
-@Returns:
+@list: a #GSList.
+@data: user data passed to the function.
+@func: the function to call for each element. It should return 0 when the
+desired element is found.
+@Returns: the found #GSList element, or NULL if it is not found.
<!-- ##### FUNCTION g_slist_position ##### -->
<para>
-
+Gets the position of the given element in the #GSList (starting from 0).
</para>
-@list:
-@llink:
-@Returns:
+@list: a #GSList.
+@llink: an element in the #GSList.
+@Returns: the position of the element in the #GSList, or -1 if the element
+is not found.
<!-- ##### FUNCTION g_slist_index ##### -->
<para>
-
+Gets the position of the element containing the given data (starting from 0).
</para>
-@list:
-@data:
-@Returns:
+@list: a #GSList.
+@data: the data to find.
+@Returns: the index of the element containing the data, or -1 if the data
+is not found.
<!-- ##### FUNCTION g_slist_push_allocator ##### -->
<para>
-
+Sets the allocator to use to allocate #GSList elements.
+Use g_slist_pop_allocator() to restore the previous allocator.
</para>
-@allocator:
+@allocator: the #GAllocator to use when allocating #GSList elements.
<!-- ##### FUNCTION g_slist_pop_allocator ##### -->
<para>
-
+Restores the previous #GAllocator, used when allocating #GSList elements.
</para>
Standard Macros
<!-- ##### SECTION Short_Description ##### -->
-
+commonly-used macros.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+These macros provide a few commonly-used features.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### MACRO GLIB_MAJOR_VERSION ##### -->
<para>
-
+The major version number of the GLib library.
</para>
<!-- ##### MACRO GLIB_MINOR_VERSION ##### -->
<para>
-
+The minor version number of the GLib library.
</para>
<!-- ##### MACRO GLIB_MICRO_VERSION ##### -->
<para>
-
+The micro version number of the GLib library.
</para>
<!-- ##### MACRO GLIB_CHECK_VERSION ##### -->
<para>
+Checks the version of the GLib library.
+It returns TRUE if the GLib library is the same or newer than the given
+version.
+<example>
+<title>Checking the version of the GLib library.</title>
+<programlisting>
+ if (!GLIB_CHECK_VERSION (1, 2, 0))
+ g_error ("GLib version 1.2.0 or above is needed");
+</programlisting>
+</example>
</para>
-@major:
-@minor:
-@micro:
+@major: the major version number.
+@minor: the minor version number.
+@micro: the micro version number.
<!-- ##### MACRO G_DIR_SEPARATOR ##### -->
<para>
-
+The directory separator character.
+This is '/' on Unix machines and '\' under Windows.
</para>
<!-- ##### MACRO G_DIR_SEPARATOR_S ##### -->
<para>
-
+The directory separator as a string.
+This is "/" on Unix machines and "\" under Windows.
</para>
<!-- ##### MACRO G_SEARCHPATH_SEPARATOR ##### -->
<para>
-
+The search path separator character.
+This is ':' on Unix machines and ';' under Windows.
</para>
<!-- ##### MACRO G_SEARCHPATH_SEPARATOR_S ##### -->
<para>
-
+The search path separator as a string.
+This is ":" on Unix machines and ";" under Windows.
</para>
<!-- ##### MACRO TRUE ##### -->
<para>
-
+Defines the TRUE value for the #gboolean type.
</para>
<!-- ##### MACRO FALSE ##### -->
<para>
-
+Defines the FALSE value for the #gboolean type.
</para>
<!-- ##### MACRO NULL ##### -->
<para>
-
+Defines the standard NULL pointer.
</para>
<!-- ##### MACRO MIN ##### -->
<para>
-
+Calculates the minimum of @a and @b.
</para>
-@a:
-@b:
+@a: a numeric value.
+@b: a numeric value.
+@Returns: the minimum of @a and @b.
<!-- ##### MACRO MAX ##### -->
<para>
-
+Calculates the maximum of @a and @b.
</para>
-@a:
-@b:
+@a: a numeric value.
+@b: a numeric value.
+@Returns: the maximum of @a and @b.
<!-- ##### MACRO ABS ##### -->
<para>
-
+Calculates the absolute value of @a.
+The absolute value is simply the number with any negative sign taken away.
+</para>
+<para>
+For example,
+<itemizedlist>
+<listitem><para>
+ABS(-10) is 10.
+</para></listitem>
+<listitem><para>
+ABS(10) is also 10.
+</para></listitem>
+</itemizedlist>
</para>
-@a:
+@a: a numeric value.
+@Returns: the absolute value of @a.
<!-- ##### MACRO CLAMP ##### -->
<para>
-
+Ensures that @x is between the limits set by @low and @high.
+</para>
+<para>
+For example,
+<itemizedlist>
+<listitem><para>
+CLAMP(5, 10, 15) is 10.
+</para></listitem>
+<listitem><para>
+CLAMP(15, 5, 10) is 10.
+</para></listitem>
+<listitem><para>
+CLAMP(20, 15, 25) is 20.
+</para></listitem>
+</itemizedlist>
</para>
-@x:
-@low:
-@high:
+@x: the value to clamp.
+@low: the minimum value allowed.
+@high: the maximum value allowed.
+@Returns: the value of @x clamped to the range between @low and @high.
<!-- ##### MACRO G_STRUCT_MEMBER ##### -->
<para>
-
+Returns a member of a structure at a given offset, using the given type.
</para>
-@member_type:
-@struct_p:
-@struct_offset:
+@member_type: the type of the struct field.
+@struct_p: a pointer to a struct.
+@struct_offset: the offset of the field from the start of the struct, in bytes.
+@Returns: the struct member.
<!-- ##### MACRO G_STRUCT_MEMBER_P ##### -->
<para>
-
+Returns an untyped pointer to a given offset of a struct.
</para>
-@struct_p:
-@struct_offset:
+@struct_p: a pointer to a struct.
+@struct_offset: the offset from the start of the struct, in bytes.
+@Returns: an untyped pointer to @struct_p plus @struct_offset bytes.
<!-- ##### MACRO G_STRUCT_OFFSET ##### -->
<para>
-
+Returns the offset, in bytes, of a member of a struct.
</para>
-@struct_type:
-@member:
+@struct_type: a structure type, e.g. <structname>GtkWidget</structname>.
+@member: a field in the structure, e.g. <structfield>window</structfield>.
+@Returns: the offset of @member from the start of @struct_type.
Miscellaneous Macros
<!-- ##### SECTION Short_Description ##### -->
-
+specialised macros which are not used often.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+These macros provide more specialized features which are not needed so often
+by application programmers.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### MACRO G_INLINE_FUNC ##### -->
<para>
-
+Used to declare inline functions. If inline functions are not supported on
+the particular platform, the macro evaluates to the empty string.
</para>
<!-- ##### MACRO G_STMT_START ##### -->
<para>
-
+Used within multi-statement macros so that they can be used in places where
+only one statement is expected by the compiler.
</para>
<!-- ##### MACRO G_STMT_END ##### -->
<para>
-
+Used within multi-statement macros so that they can be used in places where
+only one statement is expected by the compiler.
</para>
<!-- ##### MACRO G_VA_COPY ##### -->
<para>
-
+Portable way to copy <type>va_list</type> variables.
</para>
-@ap1:
-@ap2:
+@ap1: the <type>va_list</type> variable to place a copy of @ap2 in.
+@ap2: a <type>va_list</type>.
<!-- ##### MACRO G_STRINGIFY ##### -->
<!-- ##### MACRO G_GNUC_EXTENSION ##### -->
<para>
-
+Expands to "__extension__" when GNU C is used as the compiler.
+This simply tells GNU C not to warn about the following non-standard code
+when compiling with the -pedantic option.
</para>
<!-- ##### MACRO G_GNUC_CONST ##### -->
<para>
-
+Expands to the GNU C const function attribute if the compiler is GNU C.
+This enables optimization of the function.
+See the GNU C documentation for details.
</para>
<!-- ##### MACRO G_GNUC_NORETURN ##### -->
<para>
-
+Expands to the GNU C noreturn function attribute if the compiler is GNU C.
+It is used for declaring functions which never return.
+It enables optimization of the function, and avoids possible compiler
+warnings. See the GNU C documentation for details.
</para>
<!-- ##### MACRO G_GNUC_UNUSED ##### -->
<para>
-
+Expands to the GNU C unused function attribute if the compiler is GNU C.
+It is used for declaring functions which may never be used.
+It avoids possible compiler warnings. See the GNU C documentation for details.
</para>
<!-- ##### MACRO G_GNUC_PRINTF ##### -->
<para>
-
+Expands to the GNU C format function attribute if the compiler is GNU C.
+This is used for declaring functions which take a variable number of
+arguments, with the same syntax as <function>printf()</function>.
+It allows the compiler to type-check the arguments passed to the function.
+See the GNU C documentation for details.
</para>
-@format_idx:
-@arg_idx:
+@format_idx: the index of the argument corresponding to the format string.
+(The arguments are numbered from 1).
+@arg_idx: the index of the first of the format arguments.
<!-- ##### MACRO G_GNUC_SCANF ##### -->
<para>
-
+Expands to the GNU C format function attribute if the compiler is GNU C.
+This is used for declaring functions which take a variable number of
+arguments, with the same syntax as <function>scanf()</function>.
+It allows the compiler to type-check the arguments passed to the function.
+See the GNU C documentation for details.
</para>
-@format_idx:
-@arg_idx:
+@format_idx: the index of the argument corresponding to the format string.
+(The arguments are numbered from 1).
+@arg_idx: the index of the first of the format arguments.
<!-- ##### MACRO G_GNUC_FORMAT ##### -->
<para>
+Expands to the GNU C format_arg function attribute if the compiler is GNU C.
+This is used for declaring functions which take a variable number of
+parameters, like <function>printf()</function> and
+<function>scanf()</function>. See the GNU C documentation for details.
+FIXME: I can't find this in my GNU C documentation. Take out?
</para>
-@arg_idx:
+@arg_idx: the index of the argument.
<!-- ##### MACRO G_GNUC_FUNCTION ##### -->
<para>
-
+Expands to the GNU C __FUNCTION__ variable if the compiler is GNU C,
+or "" if it isn't.
+The GNU C __FUNCTION__ variable contains the name of the current function.
+See the GNU C documentation for details.
</para>
<!-- ##### MACRO G_GNUC_PRETTY_FUNCTION ##### -->
<para>
-
+Expands to the GNU C __PRETTY_FUNCTION__ variable if the compiler is GNU C,
+or "" if it isn't.
+The GNU C __PRETTY_FUNCTION__ variable contains the name of the current
+function. For a C program this is the same as the __FUNCTION__ variable
+but for C++ it also includes extra information such as the class
+and function prototype. See the GNU C documentation for details.
</para>
The Main Event Loop
<!-- ##### SECTION Short_Description ##### -->
-
+manages all available sources of events.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The main event loop manages all the available sources of events for GLib
+and GTK+ applications. These events can come from any number of different
+types of sources such as file descriptors (plain files, pipes or sockets)
+and timeouts.
+New types of event sources can also be added using g_source_add().
+</para>
+<para>
+Each event source is assigned a priority.
+The default priority, #G_PRIORITY_DEFAULT, is 0.
+Values less than 0 denote higher priorities.
+Values greater than 0 denote lower priorities.
+Events from high priority sources
+are always processed before events from lower priority sources.
+</para>
+<para>
+Idle functions can also be added, and assigned a priority. These will be
+run whenever no events with a higher priority are ready to be processed.
+</para>
+<para>
+The #GMainLoop data type represents a main event loop.
+A #GMainLoop is created with g_main_new(). After adding the initial event
+sources, g_main_run() is called. This continuously checks for new events
+from each of the event sources and dispatches them.
+Finally, the processing of an event from one of the sources leads to a call
+to g_main_quit() to exit the main loop, and g_main_run() returns.
+</para>
+<para>
+It is possible to create new instances of #GMainLoop recursively.
+This is often used in GTK+ applications when showing modal dialog boxes.
+However, all event sources are global; they are not tied to a particular
+#GMainLoop.
+</para>
+<para>
+GTK+ contains wrappers of many of these functions,
+e.g. gtk_main(), gtk_main_quit(), gtk_events_pending(), gtk_idle_add(),
+gtk_timeout_add() and gtk_input_add_full().
+In a GTK+ application, these wrapper functions should be used instead.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GMainLoop ##### -->
<para>
-
+The #GMainLoop struct is an opaque data type representing the main event loop
+of a GLib or GTK+ application.
</para>
<!-- ##### FUNCTION g_main_new ##### -->
<para>
-
+Creates a new #GMainLoop.
</para>
-@is_running:
-@Returns:
+@is_running: set to TRUE to indicate that the loop is running. This is not
+very important since calling g_main_run() will set this to TRUE anyway.
+@Returns: a new #GMainLoop.
<!-- ##### FUNCTION g_main_destroy ##### -->
<para>
-
+Frees the memory allocated for the #GMainLoop.
</para>
-@loop:
+@loop: a #GMainLoop.
<!-- ##### FUNCTION g_main_run ##### -->
<para>
-
+Runs a main loop until it stops running, which occurs when g_main_quit()
+is called.
</para>
-@loop:
+@loop: a #GMainLoop.
<!-- ##### FUNCTION g_main_is_running ##### -->
<para>
-
+Returns TRUE if the main loop is running.
</para>
-@loop:
-@Returns:
+@loop: a #GMainLoop.
+@Returns: TRUE if the main loop is running.
<!-- ##### FUNCTION g_main_pending ##### -->
<para>
-
+Returns TRUE if any events are pending (i.e. ready to be processed).
</para>
-@Returns:
+@Returns: TRUE if any events are pending.
<!-- ##### FUNCTION g_main_iteration ##### -->
<para>
-
+Runs a single iteration of the main loop.
+This will check which event sources are ready to be processed, and will
+process the highest priority event sources which are ready.
</para>
-@may_block:
-@Returns:
+@may_block: set to TRUE if it should block (i.e. wait) until an event source
+becomes ready. It will return after an event source has been processed.
+If set to FALSE it will return immediately if no event source is ready to be
+processed.
+@Returns: TRUE if more events are pending.
<!-- ##### FUNCTION g_main_quit ##### -->
<para>
-
+Stops the #GMainLoop. If g_main_run() was called to run the #GMainLoop,
+it will now return.
</para>
-@loop:
+@loop: a #GMainLoop.
<!-- ##### MACRO G_PRIORITY_HIGH ##### -->
<para>
-
+Use this for high priority event sources.
+It is not used within GLib or GTK+.
</para>
<!-- ##### MACRO G_PRIORITY_DEFAULT ##### -->
<para>
-
+Use this for default priority event sources.
+In GLib this priority is used when adding timeout functions with
+g_timeout_add().
+In GDK this priority is used for events from the X Windows server.
</para>
<!-- ##### MACRO G_PRIORITY_HIGH_IDLE ##### -->
<para>
-
+Use this for high priority idle functions.
+GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations, and
+#G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is done to
+ensure that any pending resizes are processed before any pending redraws,
+so that widgets are not redrawn twice unnecessarily.)
</para>
<!-- ##### MACRO G_PRIORITY_DEFAULT_IDLE ##### -->
<para>
-
+Use this for default priority idle functions.
+In GLib this priority is used when adding idle functions with g_idle_add().
</para>
<!-- ##### MACRO G_PRIORITY_LOW ##### -->
<para>
-
+Use this for very low priority background tasks.
+It is not used within GLib or GTK+.
</para>
<!-- ##### FUNCTION g_timeout_add ##### -->
<para>
-
+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.
+</para>
+<para>
+Note that timeout functions may be delayed, due to the processing of other
+event sources. Thus they should not be relied on for precise timing.
+After each call to the timeout function, the time of the next
+timeout is recalculated based on the current time and the given interval
+(it does not try to 'catch up' time lost in delays).
</para>
-@interval:
-@function:
-@data:
-@Returns:
+@interval: the time between calls to @function, in milliseconds (1/1000ths
+of a second.)
+@function: the function to call at each interval.
+@data: data to pass to @function.
+@Returns: the id of the event source.
<!-- ##### FUNCTION g_timeout_add_full ##### -->
<para>
-
+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.
+</para>
+<para>
+Note that timeout functions may be delayed, due to the processing of other
+event sources. Thus they should not be relied on for precise timing.
+After each call to the timeout function, the time of the next
+timeout is recalculated based on the current time and the given interval
+(it does not try to 'catch up' time lost in delays).
</para>
-@priority:
-@interval:
-@function:
-@data:
-@notify:
-@Returns:
+@priority: the priority of the function. See #G_PRIORITY_DEFAULT,
+#G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH, #G_PRIORITY_HIGH_IDLE, and
+#G_PRIORITY_LOW.
+@interval: the time between calls to the function, in milliseconds (1/1000ths
+of a second.)
+@function: the function to call at each interval.
+@data: data to pass to @function (and @notify).
+@notify: the function to call when the timeout is destroyed, or NULL.
+@Returns: the id of event source.
<!-- ##### USER_FUNCTION GSourceFunc ##### -->
<para>
-
+Specifies the type of function passed to g_timeout_add(), g_timeout_add_full(),
+g_idle_add(), and g_idle_add_full().
</para>
-@data:
-@Returns:
+@data: data passed to the function, set when the source was created with one
+of the above functions.
+@Returns: it should return FALSE if the source should be removed.
<!-- ##### FUNCTION g_idle_add ##### -->
<para>
-
+Adds a function to be called whenever there are no higher priority events
+pending. The function is given the default idle priority,
+#G_PRIORITY_DEFAULT_IDLE.
+If the function returns FALSE it is automatically removed from the list of
+event sources and will not be called again.
</para>
-@function:
-@data:
-@Returns:
+@function: the function to call.
+@data: data to pass to the function.
+@Returns: the id of the event source.
<!-- ##### FUNCTION g_idle_add_full ##### -->
<para>
-
+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.
</para>
-@priority:
-@function:
-@data:
-@destroy:
-@Returns:
+@priority: the priority of the idle function, which should be somewhere around
+#G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.
+@function: the function to call.
+@data: data to pass to the function.
+@destroy: the function to call when the timeout is destroyed, or NULL.
+@Returns: the id of the event source.
<!-- ##### FUNCTION g_idle_remove_by_data ##### -->
<para>
-
+Removes the idle function with the given data.
</para>
-@data:
-@Returns:
+@data: the data which is passed to the idle function.
+@Returns: TRUE if the idle function was found.
<!-- ##### FUNCTION g_main_add_poll ##### -->
<para>
-
+Adds a file descriptor to be polled.
+This is usually combined with g_source_add() to add an event source.
+The event source's check function will typically test the revents
+field in the #GPollFD struct and return TRUE if events need to be processed.
</para>
-@fd:
-@priority:
+@fd: a #GPollFD, which is a file descriptor together with a bitwise
+combination of #GIOCondition flags determining which events to poll for.
+@priority: the priority of the poll, which should be the same as the priority
+used for g_source_add() to ensure that the file descriptor is polled whenever
+the results may be needed.
+See #G_PRIORITY_DEFAULT, #G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH,
+#G_PRIORITY_HIGH_IDLE, and #G_PRIORITY_LOW.
<!-- ##### STRUCT GPollFD ##### -->
<para>
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>#gint fd;</entry>
+<entry>the file descriptor to poll (or a HANDLE on Win32 platforms).</entry>
+</row>
+
+<row>
+<entry>#gushort events;</entry>
+<entry>a bitwise combination of flags from #GIOCondition, specifying which
+events should be polled for. Typically for reading from a file descriptor
+you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use
+%G_IO_OUT | %G_IO_ERR.
+</entry>
+</row>
+
+<row>
+<entry>#gushort revents;</entry>
+<entry>a bitwise combination of flags from #GIOCondition, returned from the
+poll() function to indicate which events occurred.
+</entry>
+</row>
+</tbody></tgroup></informaltable>
+
</para>
@fd:
<!-- ##### FUNCTION g_main_remove_poll ##### -->
<para>
-
+Removes a file descriptor from the list being polled.
</para>
-@fd:
+@fd: the #GPollFD to remove.
<!-- ##### FUNCTION g_main_set_poll_func ##### -->
<para>
-
+Sets the function to use to handle polling of file descriptors.
+It will be used instead of the <function>poll()</function> system call
+(or GLib's replacement function, which is used where
+<function>poll()</function> isn't available).
+</para>
+<para>
+This function could possibly be used to integrate the GLib event loop
+with an external event loop.
</para>
-@func:
+@func: the function to call to poll all file descriptors.
<!-- ##### FUNCTION g_main_win32_get_poll_func ##### -->
<!-- ##### USER_FUNCTION GPollFunc ##### -->
<para>
-
+Specifies the type of function passed to g_main_set_poll_func().
+The semantics of the function should match those of the
+<function>poll()</function> system call.
</para>
-@ufds:
-@nfsd:
-@timeout:
-@Returns:
+@ufds: an array of #GPollFD elements.
+@nfsd: the number of elements in @ufds.
+@timeout: the maximum time to wait for an event of the file descriptors.
+@Returns: the number of #GPollFD elements which have events or errors reported,
+or -1 if an error occurred.
<!-- ##### FUNCTION g_source_add ##### -->
<para>
-
+Adds an event source to the main loop.
</para>
-@priority:
-@can_recurse:
-@funcs:
-@source_data:
-@user_data:
-@notify:
-@Returns:
+@priority: the priority of the event source. See #G_PRIORITY_DEFAULT,
+#G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH, #G_PRIORITY_HIGH_IDLE, and
+#G_PRIORITY_LOW.
+@can_recurse: if it is safe to call the source functions recursively.
+@funcs: the functions to handle the source.
+@source_data: data specific to the type of event source.
+@user_data: user data which will be passed to the user function handling the
+source.
+@notify: the function to call when the source is destroyed.
+@Returns: the id of the event source.
<!-- ##### STRUCT GSourceFuncs ##### -->
<para>
-
+The #GSourceFuncs struct contains a table of functions used to handle
+event sources in a generic manner.
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>prepare</entry>
+<entry>
+Called before all the file descriptors are polled.
+If the source can determine that it is ready here (without waiting for the
+results of the poll() call) it should return TRUE.
+It can also return a @timeout value which should be the maximum timeout
+(in milliseconds) which should be passed to the poll() call.
+The actual timeout used will be -1 if all sources returned -1, or it will
+be the minimum of all the @timeout values returned which were >= 0.
+</entry>
+</row>
+
+<row>
+<entry>check</entry>
+<entry>
+Called after all the file descriptors are polled.
+The source should return TRUE if it is ready to be processed.
+Note that some time may have passed since the previous prepare function was
+called, so the source should be checked again here.
+</entry>
+</row>
+
+<row>
+<entry>dispatch</entry>
+<entry>
+Called to process the event source, after it has returned TRUE in either
+its @prepare or its @check function.
+</entry>
+</row>
+
+<row>
+<entry>destroy</entry>
+<entry>
+Called when the source is destroyed. It will be called with the user data
+parameter passed to the g_source_add() and related functions.
+</entry>
+</row>
+</tbody></tgroup></informaltable>
+</para>
+
+<para>
+For idle sources, the prepare and check functions always return TRUE to
+indicate that the source is always ready to be processed.
+The prepare function also returns a timeout value of 0 to ensure that the
+poll() call doesn't block (since that would be time wasted which could have
+been spent running the idle function).
+</para>
+<para>
+For timeout sources, the prepare and check functions both return TRUE if the
+timeout interval has expired.
+The prepare function also returns a timeout value to ensure that the poll()
+call doesn't block too long and miss the next timeout.
+</para>
+<para>
+For file descriptor sources, the prepare function typically returns FALSE,
+since it must wait until poll() has been called before it knows whether any
+events need to be processed. It sets the returned timeout to -1 to indicate
+that it doesn't mind how long the poll() call blocks.
+In the check function, it tests the results of the poll() call to see if
+the required condition has been met, and returns TRUE if so.
</para>
@prepare:
<!-- ##### FUNCTION g_source_remove ##### -->
<para>
-
+Removes the event source with the given id.
+The id is returned when the source is created, either directly with
+g_source_add(), or indirectly with g_idle_add(), g_idle_add_full(),
+g_timeout_add() and g_timeout_add_full().
</para>
-@tag:
-@Returns:
+@tag: the id of the event source to remove.
+@Returns: TRUE if the source was found and removed.
<!-- ##### FUNCTION g_source_remove_by_funcs_user_data ##### -->
<para>
-
+Removes the first event source found with the given #GSourceFuncs and user
+data.
+</para>
+<para>
+Event sources are sorted with the highest priority first. Sources with equal
+priority are stored in the order in which they were added.
</para>
-@funcs:
-@user_data:
-@Returns:
+@funcs: the #GSourceFuncs of the source to remove.
+@user_data: the user data of the source to remove.
+@Returns: TRUE if an event source was found and removed.
<!-- ##### FUNCTION g_source_remove_by_source_data ##### -->
<para>
-
+Removes the first event source found with the given source data.
+</para>
+<para>
+Event sources are sorted with the highest priority first. Sources with equal
+priority are stored in the order in which they were added.
</para>
-@source_data:
-@Returns:
+@source_data: the source data, which contains information specific to the
+type of source.
+@Returns: TRUE if an event source was found and removed.
<!-- ##### FUNCTION g_source_remove_by_user_data ##### -->
<para>
-
+Removes the first event source found with the given user data.
+</para>
+<para>
+Event sources are sorted with the highest priority first. Sources with equal
+priority are stored in the order in which they were added.
</para>
-@user_data:
-@Returns:
+@user_data: the user data of the source to remove.
+@Returns: TRUE if an event source was found and removed.
Memory Allocation
<!-- ##### SECTION Short_Description ##### -->
-
+general memory-handling.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+These functions provide support for allocating and freeing memory.
</para>
+<note>
+<para>
+If any call to allocate memory fails, the application is terminated.
+This also means that there is no need to check if the call succeeded.
+</para>
+</note>
<!-- ##### SECTION See_Also ##### -->
<para>
<!-- ##### MACRO g_new ##### -->
<para>
-
+Allocates @count elements of type @type.
+The returned pointer is cast to a pointer to the given type.
+If @count is 0 it returns NULL.
</para>
-@type:
-@count:
+@type: the type of the elements to allocate.
+@count: the number of elements to allocate.
+@Returns: a pointer to the allocated memory, cast to a pointer to @type.
<!-- ##### MACRO g_new0 ##### -->
<para>
-
+Allocates @count elements of type @type, initialized to 0's.
+The returned pointer is cast to a pointer to the given type.
+If @count is 0 it returns NULL.
</para>
-@type:
-@count:
+@type: the type of the elements to allocate.
+@count: the number of elements to allocate.
+@Returns: a pointer to the allocated memory, cast to a pointer to @type.
<!-- ##### MACRO g_renew ##### -->
<para>
-
+Reallocates the memory pointed to by @mem, so that it now has space for
+@count elements of type @type. It returns the new address of the memory,
+which may have been moved.
</para>
-@type:
-@mem:
-@count:
+@type: the type of the elements to allocate.
+@mem: the currently allocated memory.
+@count: the number of elements to allocate.
+@Returns: a pointer to the new allocated memory, cast to a pointer to @type.
<!-- ##### FUNCTION g_malloc ##### -->
<para>
-
+Allocates @size bytes of memory.
+If @size is 0 it returns NULL.
</para>
-@size:
-@Returns:
+@size: the number of bytes to allocate.
+@Returns: a pointer to the allocated memory.
<!-- ##### FUNCTION g_malloc0 ##### -->
<para>
-
+Allocates @size bytes of memory, initialized to 0's.
+If @size is 0 it returns NULL.
</para>
-@size:
-@Returns:
+@size: the number of bytes to allocate.
+@Returns: a pointer to the allocated memory.
<!-- ##### FUNCTION g_realloc ##### -->
<para>
-
+Reallocates the memory pointed to by @mem, so that it now has space for
+@size bytes of memory. It returns the new address of the memory, which may
+have been moved.
</para>
-@mem:
-@size:
-@Returns:
+@mem: the memory to reallocate.
+@size: the new size of the allocated memory, in bytes.
+@Returns: the new address of the allocated memory.
<!-- ##### FUNCTION g_free ##### -->
<para>
-
+Frees the memory pointed to by @mem.
+If @mem is NULL it simply returns.
</para>
-@mem:
+@mem: the memory to free.
<!-- ##### MACRO g_memmove ##### -->
<para>
-
+Copies a block of memory @n bytes long, from @s to @d.
+The source and destination areas may overlap.
</para>
+<note>
+<para>
+On architectures where memmove() is not available, this function is implemented
+using bcopy(), which may not be able to handle overlapping areas.
+</para>
+</note>
-@d:
-@s:
-@n:
+@d: the destination address to copy the bytes to.
+@s: the source address to copy the bytes from.
+@n: the number of bytes to copy.
<!-- ##### FUNCTION g_memdup ##### -->
<para>
-
+Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
+from @mem. If @mem is NULL it returns NULL.
</para>
-@mem:
-@byte_size:
-@Returns:
+@mem: the memory to copy.
+@byte_size: the number of bytes to copy.
+@Returns: a pointer to the newly allocated copy of the memory, or NULL if @mem
+is NULL.
<!-- ##### FUNCTION g_mem_profile ##### -->
<para>
-
+Outputs a summary of memory usage.
+To use this function you must configure glib with the flag
+'--enable-mem-profile=yes' before compiling.
+</para>
+<para>
+It outputs the frequency of allocations of different sizes,
+the total number of bytes which have been allocated,
+the total number of bytes which have been freed,
+and the difference between the previous two values, i.e. the number of bytes
+still in use.
</para>
<!-- ##### FUNCTION g_mem_check ##### -->
<para>
-
+Checks if the given memory has already been freed. If it has it outputs
+a warning message.
+To use this function you must configure glib with the flag
+'--enable-mem-check=yes' before compiling.
</para>
-@mem:
+@mem: the memory to check.
Memory Chunks
<!-- ##### SECTION Short_Description ##### -->
-
+efficient way to allocate groups of equal-sized chunks of memory.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+Memory chunks provide an efficient way to allocate equal-sized pieces of
+memory, called atoms. They are used extensively within GLib itself.
+For example, the
+<link linkend="glib-Doubly-Linked-lists">Doubly Linked Lists</link>
+use memory chunks to allocate space for elements of the lists.
+</para>
+<para>
+There are two types of memory chunks, #G_ALLOC_ONLY, and #G_ALLOC_AND_FREE.
+<itemizedlist>
+<listitem><para>
+#G_ALLOC_ONLY chunks only allow allocation of atoms. The atoms can never
+be freed individually. The memory chunk can only be free in its entirety.
+</para></listitem>
+<listitem><para>
+#G_ALLOC_AND_FREE chunks do allow atoms to be freed individually.
+The disadvantage of this is that the memory chunk has to keep track of which
+atoms have been freed. This results in more memory being used and a slight
+degradation in performance.
+</para></listitem>
+
+</itemizedlist>
+</para>
+<para>
+To create a memory chunk use g_mem_chunk_new() or the convenience macro
+g_mem_chunk_create().
+</para>
+<para>
+To allocate a new atom use g_mem_chunk_alloc(), g_mem_chunk_alloc0(),
+or the convenience macros g_chunk_new() or g_chunk_new0().
+</para>
+<para>
+To free an atom use g_mem_chunk_free(), or the convenience macro
+g_chunk_free(). (Atoms can only be freed if the memory chunk is created
+with the type set to #G_ALLOC_AND_FREE.)
+</para>
+<para>
+To free any blocks of memory which are no longer being used, use
+g_mem_chunk_clean(). To clean all memory chunks, use g_blow_chunks().
+</para>
+<para>
+To reset the memory chunk, freeing all of the atoms, use g_mem_chunk_reset().
+</para>
+<para>
+To destroy a memory chunk, use g_mem_chunk_destroy().
+</para>
+<para>
+To help debug memory chunks, use g_mem_chunk_info() and g_mem_chunk_print().
</para>
+<example>
+<title>Using a GMemChunk.</title>
+<programlisting>
+ GMemChunk *mem_chunk;
+ gchar *mem[10000];
+ gint i;
+
+ /* Create a GMemChunk with atoms 50 bytes long, and memory blocks holding
+ 100 bytes. Note that this means that only 2 atoms fit into each memory
+ block and so isn't very efficient. */
+ mem_chunk = g_mem_chunk_new ("test mem chunk", 50, 100, G_ALLOC_AND_FREE);
+
+ /* Now allocate 10000 atoms. */
+ for (i = 0; i < 10000; i++)
+ {
+ mem[i] = g_chunk_new (gchar, mem_chunk);
+
+ /* Fill in the atom memory with some junk. */
+ for (j = 0; j < 50; j++)
+ mem[i][j] = i * j;
+ }
+
+ /* Now free all of the atoms. Note that since we are going to destroy the
+ GMemChunk, this wouldn't normally be used. */
+ for (i = 0; i < 10000; i++)
+ {
+ g_mem_chunk_free (mem_chunk, mem[i]);
+ }
+
+ /* We are finished with the GMemChunk, so we destroy it. */
+ g_mem_chunk_destroy (mem_chunk);
+</programlisting></example>
+
+<example>
+<title>Using a GMemChunk with data structures.</title>
+<programlisting>
+ GMemChunk *array_mem_chunk;
+ GRealArray *array;
+
+ /* Create a GMemChunk to hold GRealArray structures, using the
+ g_mem_chunk_create() convenience macro. We want 1024 atoms in each
+ memory block, and we want to be able to free individual atoms. */
+ array_mem_chunk = g_mem_chunk_create (GRealArray, 1024, G_ALLOC_AND_FREE);
+
+ /* Allocate one atom, using the g_chunk_new() convenience macro. */
+ array = g_chunk_new (GRealArray, array_mem_chunk);
+
+ /* We can now use array just like a normal pointer to a structure. */
+ array->data = NULL;
+ array->len = 0;
+ array->alloc = 0;
+ array->zero_terminated = (zero_terminated ? 1 : 0);
+ array->clear = (clear ? 1 : 0);
+ array->elt_size = elt_size;
+
+ /* We can free the element, so it can be reused. */
+ g_chunk_free (array, array_mem_chunk);
+
+ /* We destroy the GMemChunk when we are finished with it. */
+ g_mem_chunk_destroy (array_mem_chunk);
+</programlisting></example>
+
<!-- ##### SECTION See_Also ##### -->
<para>
<!-- ##### STRUCT GMemChunk ##### -->
<para>
-
+The #GMemChunk struct is an opaque data structure representing a memory
+chunk. It should be accessed only through the use of the following functions.
</para>
<!-- ##### MACRO G_ALLOC_AND_FREE ##### -->
<para>
-
+Specifies the type of a #GMemChunk.
+Used in g_mem_chunk_new() and g_mem_chunk_create() to specify that atoms
+will be freed individually.
</para>
<!-- ##### MACRO G_ALLOC_ONLY ##### -->
<para>
-
+Specifies the type of a #GMemChunk.
+Used in g_mem_chunk_new() and g_mem_chunk_create() to specify that atoms
+will never be freed individually.
</para>
<!-- ##### FUNCTION g_mem_chunk_new ##### -->
<para>
-
+Creates a new #GMemChunk.
</para>
-@name:
-@atom_size:
-@area_size:
-@type:
-@Returns:
+@name: a string to identify the #GMemChunk. It is not copied so it
+should be valid for the lifetime of the #GMemChunk. It is only used in
+g_mem_chunk_print(), which is used for debugging.
+@atom_size: the size, in bytes, of each element in the #GMemChunk.
+@area_size: the size, in bytes, of each block of memory allocated to contain
+the atoms.
+@type: the type of the #GMemChunk.
+#G_ALLOC_AND_FREE is used if the atoms will be freed individually.
+#G_ALLOC_ONLY should be used if atoms will never be freed individually.
+#G_ALLOC_ONLY is quicker, since it does not need to track free atoms,
+but it obviously wastes memory if you no longer need many of the atoms.
+@Returns: the new #GMemChunk.
<!-- ##### FUNCTION g_mem_chunk_alloc ##### -->
<para>
-
+Allocates an atom of memory from a #GMemChunk.
</para>
-@mem_chunk:
-@Returns:
+@mem_chunk: a #GMemChunk.
+@Returns: a pointer to the allocated atom.
<!-- ##### FUNCTION g_mem_chunk_alloc0 ##### -->
<para>
-
+Allocates an atom of memory from a #GMemChunk, setting the memory to 0.
</para>
-@mem_chunk:
-@Returns:
+@mem_chunk: a #GMemChunk.
+@Returns: a pointer to the allocated atom.
<!-- ##### FUNCTION g_mem_chunk_free ##### -->
<para>
-
+Frees an atom in a #GMemChunk.
+This should only be called if the #GMemChunk was created with
+#G_ALLOC_AND_FREE. Otherwise it will simply return.
</para>
-@mem_chunk:
-@mem:
+@mem_chunk: a #GMemChunk.
+@mem: a pointer to the atom to free.
<!-- ##### FUNCTION g_mem_chunk_destroy ##### -->
<para>
-
+Frees all of the memory allocated for a #GMemChunk.
</para>
-@mem_chunk:
+@mem_chunk: a #GMemChunk.
<!-- ##### MACRO g_mem_chunk_create ##### -->
<para>
-
+A convenience macro for creating a new #GMemChunk.
+It calls g_mem_chunk_new(), using the given type to create the #GMemChunk
+name. The atom size is determined using <function>sizeof()</function>, and the
+area size is calculated by multiplying the @pre_alloc parameter with
+the atom size.
</para>
-@type:
-@pre_alloc:
-@alloc_type:
+@type: the type of the atoms, typically a structure name.
+@pre_alloc: the number of atoms to store in each block of memory.
+@alloc_type: the type of the #GMemChunk.
+#G_ALLOC_AND_FREE is used if the atoms will be freed individually.
+#G_ALLOC_ONLY should be used if atoms will never be freed individually.
+#G_ALLOC_ONLY is quicker, since it does not need to track free atoms,
+but it obviously wastes memory if you no longer need many of the atoms.
+@Returns: the new #GMemChunk.
<!-- ##### MACRO g_chunk_new ##### -->
<para>
-
+A convenience macro to allocate an atom of memory from a #GMemChunk.
+It calls g_mem_chunk_alloc() and casts the returned atom to a pointer to
+the given type, avoiding a type cast in the source code.
</para>
-@type:
-@chunk:
+@type: the type of the #GMemChunk atoms, typically a structure name.
+@chunk: a #GMemChunk.
+@Returns: a pointer to the allocated atom, cast to a pointer to @type.
<!-- ##### MACRO g_chunk_new0 ##### -->
<para>
-
+A convenience macro to allocate an atom of memory from a #GMemChunk.
+It calls g_mem_chunk_alloc0() and casts the returned atom to a pointer to
+the given type, avoiding a type cast in the source code.
</para>
-@type:
-@chunk:
+@type: the type of the #GMemChunk atoms, typically a structure name.
+@chunk: a #GMemChunk.
+@Returns: a pointer to the allocated atom, cast to a pointer to @type.
<!-- ##### MACRO g_chunk_free ##### -->
<para>
-
+A convenience macro to free an atom of memory from a #GMemChunk.
+It simply switches the arguments and calls g_mem_chunk_free()
+It is included simply to complement the other convenience macros, g_chunk_new()
+and g_chunk_new0().
</para>
-@mem:
-@mem_chunk:
+@mem: a pointer to the atom to be freed.
+@mem_chunk: a #GMemChunk.
<!-- ##### FUNCTION g_mem_chunk_reset ##### -->
<para>
-
+Resets a GMemChunk to its initial state.
+It frees all of the currently allocated blocks of memory.
</para>
-@mem_chunk:
+@mem_chunk: a #GMemChunk.
<!-- ##### FUNCTION g_mem_chunk_clean ##### -->
<para>
-
+Frees any blocks in a #GMemChunk which are no longer being used.
</para>
-@mem_chunk:
+@mem_chunk: a #GMemChunk.
<!-- ##### FUNCTION g_blow_chunks ##### -->
<para>
-
+Calls g_mem_chunk_clean() on all #GMemChunk objects.
</para>
<!-- ##### FUNCTION g_mem_chunk_info ##### -->
<para>
-
+Outputs debugging information for all #GMemChunk objects currently in use.
+It outputs the number of #GMemChunk objects currently allocated,
+and calls g_mem_chunk_print() to output information on each one.
</para>
<!-- ##### FUNCTION g_mem_chunk_print ##### -->
<para>
-
+Outputs debugging information for a #GMemChunk.
+It outputs the name of the #GMemChunk (set with g_mem_chunk_new()),
+the number of bytes used, and the number of blocks of memory allocated.
</para>
-@mem_chunk:
+@mem_chunk: a #GMemChunk.
Message Logging
<!-- ##### SECTION Short_Description ##### -->
-
+versatile support for logging messages with different levels of importance.
<!-- ##### SECTION Long_Description ##### -->
<para>
+These functions provide support for logging error messages or messages
+used for debugging.
+</para>
+<para>
+There are several built-in levels of messages, defined in #GLogLevelFlags.
+These can be extended with user-defined levels.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### MACRO G_LOG_DOMAIN ##### -->
<para>
-
+Defines the log domain.
+For applications, this is typically left as the default NULL (or "") domain.
+Libraries should define this so that any messages which they log can
+be differentiated from messages from other libraries and application code.
+But be careful not to define it in any public header files.
</para>
+<para>
+For example, GTK uses this in its Makefile.am:
+</para>
+<informalexample><programlisting>
+INCLUDES = \
+ -DG_LOG_DOMAIN=\"Gtk\"
+</programlisting></informalexample>
<!-- ##### MACRO G_LOG_FATAL_MASK ##### -->
<para>
-
+GLib log levels that are considered fatal by default.
</para>
<!-- ##### MACRO G_LOG_LEVEL_USER_SHIFT ##### -->
<para>
-
+Log level shift offset for user defined log levels (0-7 are used by GLib).
</para>
<!-- ##### USER_FUNCTION GLogFunc ##### -->
<para>
-
+Specifies the prototype of log handler functions.
</para>
-@log_domain:
-@log_level:
-@message:
-@user_data:
+@log_domain: the log domain of the message.
+@log_level: the log level of the message (including the fatal and recursion
+flags).
+@message: the message to process.
+@user_data: user data, set in g_log_set_handler().
<!-- ##### ENUM GLogLevelFlags ##### -->
<para>
-
+Flags specifying the level of log messages.
</para>
@G_LOG_FLAG_RECURSION:
<!-- ##### FUNCTION g_log ##### -->
<para>
-
+Logs an error or debugging message.
+If the log level has been set as fatal, the <function>abort()</function>
+function is called to terminate the program.
</para>
-@log_domain:
-@log_level:
-@format:
-@Varargs:
+@log_domain: the log domain, usually #G_LOG_DOMAIN.
+@log_level: the log level, either from #GLogLevelFlags or a user-defined level.
+@format: the message format. See the <function>printf()</function>
+documentation.
+@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_logv ##### -->
<para>
-
+Logs an error or debugging message.
+If the log level has been set as fatal, the <function>abort()</function>
+function is called to terminate the program.
</para>
-@log_domain:
-@log_level:
-@format:
-@args:
+@log_domain: the log domain.
+@log_level: the log level.
+@format: the message format. See the <function>printf()</function>
+documentation.
+@args: the parameters to insert into the format string.
<!-- ##### MACRO g_message ##### -->
<para>
-
+A convenience function/macro to log a normal message.
</para>
@...:
+<!-- # Unused Parameters # -->
+@format: the message format. See the <function>printf()</function>
+documentation.
+@args...: the parameters to insert into the format string.
<!-- ##### MACRO g_warning ##### -->
<para>
-
+A convenience function/macro to log a warning message.
</para>
@...:
+<!-- # Unused Parameters # -->
+@format: the message format. See the <function>printf()</function>
+documentation.
+@args...: the parameters to insert into the format string.
<!-- ##### MACRO g_critical ##### -->
<!-- ##### MACRO g_error ##### -->
<para>
-
+A convenience function/macro to log an error message.
+Error messages are always fatal, resulting in a call to
+<function>abort()</function> to terminate the application.
</para>
@...:
+<!-- # Unused Parameters # -->
+@format: the message format. See the <function>printf()</function>
+documentation.
+@args...: the parameters to insert into the format string.
<!-- ##### FUNCTION g_log_set_handler ##### -->
<para>
-
+Sets the log handler for a domain and a set of log levels.
+To handle fatal and recursive messages the @log_levels parameter
+must be combined with the G_LOG_FLAG_FATAL and G_LOG_FLAG_RECURSIVE bit flags.
+</para>
+<para>
+Note that since the G_LOG_LEVEL_ERROR log level is always fatal, if you want
+to set a handler for this log level you must combine it with G_LOG_FLAG_FATAL.
</para>
-@log_domain:
-@log_levels:
-@log_func:
-@user_data:
-@Returns:
+<example>
+<title>Adding a log handler for all warning messages</title>
+<programlisting>
+ g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
+ | G_LOG_FLAG_RECURSIVE, my_log_handler, NULL);
+</programlisting>
+</example>
+
+@log_domain: the log domain, or NULL for the default "" application domain.
+@log_levels: the log levels to apply the log handler for. To handle fatal
+and recursive messages as well, combine the log levels with the
+G_LOG_FLAG_FATAL and G_LOG_FLAG_RECURSIVE bit flags.
+@log_func: the log handler function.
+@user_data: data passed to the log handler.
+@Returns: the id of the new handler.
<!-- ##### FUNCTION g_log_remove_handler ##### -->
<para>
-
+Removes the log handler.
</para>
-@log_domain:
-@handler_id:
+@log_domain: the log domain.
+@handler_id: the id of the handler, which was returned in g_log_set_handler().
<!-- ##### FUNCTION g_log_set_always_fatal ##### -->
<para>
-
+Sets the message levels which are always fatal, in any log domain.
+When a message with any of these levels is logged the program terminates.
+You can only set the levels defined by GLib to be fatal.
+%G_LOG_LEVEL_ERROR is always fatal.
</para>
-@fatal_mask:
-@Returns:
+@fatal_mask: the mask containing bits set for each level of error which is
+to be fatal.
+@Returns: the old fatal mask.
<!-- ##### FUNCTION g_log_set_fatal_mask ##### -->
<para>
-
+Sets the log levels which are fatal in the given domain.
+%G_LOG_LEVEL_ERROR is always fatal.
</para>
-@log_domain:
-@fatal_mask:
-@Returns:
+@log_domain: the log domain.
+@fatal_mask: the new fatal mask.
+@Returns: the old fatal mask for the log domain.
<!-- ##### FUNCTION g_log_default_handler ##### -->
<para>
-
+The default log handler.
+This is used if no log handler has been set for the particular log domain
+and log level combination. It outputs the message to stderr or stdout
+and if the log level is fatal it calls <function>abort()</function>.
+</para>
+<para>
+stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL, and
+%G_LOG_LEVEL_WARNING. stdout is used for the rest.
+(On the Windows platform, stdout is always used.)
</para>
-@log_domain:
-@log_level:
-@message:
-@unused_data:
+@log_domain: the log domain of the message.
+@log_level: the level of the message.
+@message: the message.
+@unused_data: data passed from g_log which is unused.
<!-- ##### FUNCTION g_set_error_handler ##### -->
<para>
-
+Sets the function to be called to handle error messages.
+This function is deprecated in favour of the new logging facilities.
</para>
-@func:
-@Returns:
+@func: the function to be called to handle error messages.
+@Returns: the old error handler.
<!-- ##### USER_FUNCTION GErrorFunc ##### -->
<para>
-
+Specifies the type of function passed to g_set_error_handler().
</para>
-@str:
+@str: the error message.
<!-- ##### FUNCTION g_set_warning_handler ##### -->
<para>
-
+Sets the function to be called to handle warning messages.
+This function is deprecated in favour of the new logging facilities.
</para>
-@func:
-@Returns:
+@func: the function to be called to handle warning messages.
+@Returns: the old warning handler.
<!-- ##### USER_FUNCTION GWarningFunc ##### -->
<para>
-
+Specifies the type of function passed to g_set_warning_handler().
</para>
-@str:
+@str: the warning message.
<!-- ##### FUNCTION g_set_message_handler ##### -->
<para>
-
+Sets the function to be called to handle messages.
+This function is deprecated in favour of the new logging facilities.
</para>
-@func:
-@Returns:
+@func: the function to be called to handle normal messages.
+@Returns: the old message handler.
Miscellaneous Utility Functions
<!-- ##### SECTION Short_Description ##### -->
-
+a selection of portable utility functions.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+These are portable utility functions.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### FUNCTION g_get_prgname ##### -->
<para>
-
+Gets the name of the program.
+(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 argv[0].)
</para>
-@Returns:
+@Returns: the name of the program.
<!-- ##### FUNCTION g_set_prgname ##### -->
<para>
-
+Sets the name of the program.
</para>
-@prgname:
+@prgname: the name of the program.
<!-- ##### FUNCTION g_getenv ##### -->
<para>
-
+Returns an environment variable.
+On windows systems the returned value is only valid until the next call to
+g_getenv().
</para>
-@variable:
-@Returns:
+@variable: the environment variable to get.
+@Returns: the value of the environment variable, or NULL if the environment
+variable is not found.
<!-- ##### FUNCTION g_get_user_name ##### -->
<para>
-
+Gets the user name of the current user.
</para>
-@Returns:
+@Returns: the user name of the current user.
<!-- ##### FUNCTION g_get_real_name ##### -->
<para>
-
+Gets the real name of the user. This comes from the user's entry in the
+passwd file.
</para>
-@Returns:
+@Returns: the user's real name.
<!-- ##### FUNCTION g_get_home_dir ##### -->
<para>
-
+Gets the current user's home directory.
</para>
-@Returns:
+@Returns: the current user's home directory.
<!-- ##### FUNCTION g_get_tmp_dir ##### -->
<para>
-
+Gets the directory to use for temporary files.
+This is found from inspecting the environment variables TMPDIR, TMP, and TEMP
+in that order. If none of those are defined "/tmp" is returned.
</para>
-@Returns:
+@Returns: the directory to use for temporary files.
<!-- ##### FUNCTION g_get_current_dir ##### -->
<para>
-
+Gets the current directory.
+The returned string should be freed when no longer needed.
</para>
-@Returns:
+@Returns: the current directory.
<!-- ##### FUNCTION g_basename ##### -->
<para>
-
+Gets the name of the file without any leading directory components.
+It returns a pointer into the given file name string.
</para>
-@file_name:
-@Returns:
+@file_name: the name of the file.
+@Returns: the name of the file without any leading directory components.
<!-- ##### FUNCTION g_dirname ##### -->
<para>
-
+Gets the directory components of a file name.
+If the file name has no directory components "." is returned.
+The returned string should be freed when no longer needed.
</para>
-@file_name:
-@Returns:
+@file_name: the name of the file.
+@Returns: the directory components of the file.
<!-- ##### FUNCTION g_path_is_absolute ##### -->
<para>
-
+Returns TRUE if the given @file_name is an absolute file name,
+i.e. it contains a full path from the root directory such as '/usr/local'
+or 'C:/windows' on windows systems.
</para>
-@file_name:
-@Returns:
+@file_name: a file name.
+@Returns: TRUE if @file_name is an absolute path.
<!-- ##### FUNCTION g_path_skip_root ##### -->
<para>
-
+Returns a pointer into @file_name after the root component, i.e. after
+the '/' in Unix or 'C:/' under Windows. If @file_name is not an absolute
+path it returns NULL.
</para>
-@file_name:
-@Returns:
+@file_name: a file name.
+@Returns: a pointer into @file_name after the root component.
<!-- ##### FUNCTION g_path_get_dirname ##### -->
<!-- ##### FUNCTION g_bit_nth_lsf ##### -->
<para>
-
+Find the position of the first bit set in @mask, searching from (but not
+including) @nth_bit upwards. Bits are numbered from 0 (least significant)
+to 31. To start searching from the 0th bit, set @nth_bit to -1.
</para>
-@mask:
-@nth_bit:
-@Returns:
+@mask: a #guint32 containing up to 32 bit flags.
+@nth_bit: the index of the bit to start the search from.
+@Returns: the index of the first bit set which is higher than @nth_bit.
<!-- ##### FUNCTION g_bit_nth_msf ##### -->
<para>
-
+Find the position of the first bit set in @mask, searching from (but not
+including) @nth_bit downwards. Bits are numbered from 0 (least significant)
+to 31. To start searching from the 31st bit, set @nth_bit to 32 or -1.
</para>
-@mask:
-@nth_bit:
-@Returns:
+@mask: a #guint32 containing up to 32 bit flags.
+@nth_bit: the index of the bit to start the search from.
+@Returns: the index of the first bit set which is lower than @nth_bit.
<!-- ##### FUNCTION g_bit_storage ##### -->
<para>
-
+Gets the number of bits used to hold @number,
+e.g. if @number is 4, 3 bits are needed.
</para>
-@number:
-@Returns:
+@number: a guint.
+@Returns: the number of bits used to hold @number.
<!-- ##### FUNCTION g_spaced_primes_closest ##### -->
<para>
-
+Gets the smallest prime number from a built-in array of primes which
+is larger than @num. This is used within GLib to calculate the optimum
+size of a #GHashTable.
+</para>
+<para>
+The built-in array of primes ranges from 11 to 13845163 such that
+each prime is approximately 1.5-2 times the previous prime.
</para>
-@num:
-@Returns:
+@num: a guint.
+@Returns: the smallest prime number from a built-in array of primes which is
+larger than @num.
<!-- ##### FUNCTION g_atexit ##### -->
<para>
-
+Specifies a function to be called at normal program termination.
</para>
-@func:
+@func: the function to call on normal program termination.
<!-- ##### FUNCTION g_parse_debug_string ##### -->
<para>
-
+Parses a string containing debugging options separated by ':' 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.
</para>
-@string:
-@keys:
-@nkeys:
-@Returns:
+@string: a list of debug options separated by ':' or "all" to set all flags.
+@keys: pointer to an array of #GDebugKey which associate strings with
+bit flags.
+@nkeys: the number of #GDebugKey in the array.
+@Returns: the combined set of bit flags.
<!-- ##### STRUCT GDebugKey ##### -->
<para>
-
+Associates a string with a bit flag.
+Used in g_parse_debug_string().
</para>
@key:
<!-- ##### USER_FUNCTION GVoidFunc ##### -->
<para>
-
+Declares a type of function which takes no arguments and has no return value.
+It is used to specify the type function passed to g_atexit().
</para>
<!-- ##### USER_FUNCTION GFreeFunc ##### -->
<para>
-
+Declares a type of function which takes an arbitrary data pointer argument
+and has no return value. It is not currently used in GLib or GTK+.
</para>
@data:
Dynamic Loading of Modules
<!-- ##### SECTION Short_Description ##### -->
-
+portable method for dynamically loading 'plug-ins'.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+These functions provide a portable way to dynamically load object files
+(commonly known as 'plug-ins').
+The current implementation supports all systems that provide
+an implementation of dlopen() (e.g. Linux/Sun), as well as HP-UX via its
+shl_load() mechanism, and Windows platforms via DLLs.
+</para>
+<para>
+To use them you must first determine whether dynamic loading
+is supported on the platform by calling g_module_supported().
+If it is, you can open a module with g_module_open(),
+find the module's symbols (e.g. function names) with g_module_symbol(),
+and later close the module with g_module_close().
+g_module_name() will return the file name of a currently opened module.
+</para>
+<para>
+If any of the above functions fail, the error status can be found with
+g_module_error().
+</para>
+<para>
+The gmodule implementation features reference counting for opened modules,
+and supports hook functions within a module which are called when the
+module is loaded and unloaded (see #GModuleCheckInit and #GModuleUnload).
+</para>
+<para>
+If your module introduces static data to common subsystems in the running
+program, e.g. through calling g_quark_from_static_string ("my-module-stuff"),
+it must ensure that it is never unloaded, by calling g_module_make_resident().
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GModule ##### -->
<para>
-
+The #GModule struct is an opaque data structure to represent a
+<link linkend="glib-Dynamic-Loading-of-Modules">Dynamically-Loaded Module</link>.
+It should only be accessed via the following functions.
</para>
<!-- ##### FUNCTION g_module_supported ##### -->
<para>
-
+Checks if modules are supported on the current platform.
</para>
-@Returns:
+@Returns: TRUE if modules are supported.
<!-- ##### FUNCTION g_module_build_path ##### -->
<para>
-
+A portable way to build the filename of a module. The platform-specific
+prefix and suffix are added to the filename, if needed, and the result is
+added to the directory, using the correct separator character.
+</para>
+<para>
+The directory should specify the directory where the module can be found.
+It can be NULL or an empty string to indicate that the module is in a standard
+operating-system specific directory, though this is not recommended since the
+wrong module may be found.
+</para>
+<para>
+For example, calling g_module_build_path() on a Linux system with a directory
+of "/lib" and a module_name of "mylibrary" will return "/lib/libmylibrary.so".
+On a Windows system, using "\Windows" as the directory it will return
+"\Windows\mylibrary.dll".
</para>
-@directory:
-@module_name:
-@Returns:
+@directory: the directory where the module is. This can be NULL or the empty
+string to indicate that the standard operating system-specific directories
+will be used, though that is not recommended.
+@module_name: the name of the module.
+@Returns: the complete path of the module, including the standard library
+prefix and suffix. This should be freed when no longer needed.
<!-- ##### FUNCTION g_module_open ##### -->
<para>
-
+Opens a module.
+If the module has already been opened, its reference count is incremented.
</para>
-@file_name:
-@flags:
-@Returns:
+@file_name: the name of the file containing the module.
+@flags: the flags used for opening the module. Currently this can be 0 or
+G_MODULE_BIND_LAZY for lazy binding, where symbols are only bound when needed.
+@Returns: a #GModule on success, or NULL on failure.
<!-- ##### ENUM GModuleFlags ##### -->
<para>
-
+Flags passed to g_module_open().
+G_MODULE_BIND_LAZY specifies that symbols are only resolved when needed.
+The default action is to bind all symbols when the module is loaded.
+(G_MODULE_BIND_LAZY is not supported on all platforms.)
</para>
@G_MODULE_BIND_LAZY:
<!-- ##### FUNCTION g_module_symbol ##### -->
<para>
-
+Gets a symbol pointer from a module.
</para>
-@module:
-@symbol_name:
-@symbol:
-@Returns:
+@module: the module.
+@symbol_name: the name of the symbol to find.
+@symbol: returns the pointer to the symbol value.
+@Returns: TRUE on success.
<!-- ##### FUNCTION g_module_name ##### -->
<para>
-
+Gets the file name from a #GModule.
</para>
-@module:
-@Returns:
+@module: the module.
+@Returns: the file name of the module, or "main" if the module is the main
+program itself.
<!-- ##### FUNCTION g_module_make_resident ##### -->
<para>
-
+Ensures that a module will never be unloaded.
+Any future g_module_close() calls on the module will be ignored.
</para>
-@module:
+@module: a module to make permanently resident.
<!-- ##### FUNCTION g_module_close ##### -->
<para>
-
+Closes a module.
</para>
-@module:
-@Returns:
+@module: the module to close.
+@Returns: TRUE on success.
<!-- ##### FUNCTION g_module_error ##### -->
<para>
-
+Gets a string describing the last module error.
</para>
-@Returns:
+@Returns: a string describing the last module error.
<!-- ##### USER_FUNCTION GModuleCheckInit ##### -->
<para>
-
+Specifies the type of the module initialization function.
+If a module contains a function named g_module_check_init() it is called
+automatically when the module is loaded. It is passed the #GModule structure
+and should return NULL on success or a string describing the initialization
+error.
</para>
-@module:
-@Returns:
+@module: the #GModule corresponding to the module which has just been loaded.
+@Returns: NULL on success, or a string describing the initialization error.
<!-- ##### USER_FUNCTION GModuleUnload ##### -->
<para>
-
+Specifies the type of the module function called when it is unloaded.
+If a module contains a function named g_module_unload() it is called
+automatically when the module is unloaded.
+It is passed the #GModule structure.
</para>
-@module:
+@module: the module about to be unloaded.
<!-- ##### MACRO G_MODULE_EXPORT ##### -->
<para>
-
+Used to declare functions exported by modules.
</para>
<!-- ##### MACRO G_MODULE_IMPORT ##### -->
<para>
-
+Used to declare functions imported from modules.
</para>
Quarks
<!-- ##### SECTION Short_Description ##### -->
-
+a 2-way association between a string and a unique integer identifier.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+Quarks are associations between strings and integer identifiers.
+Given either the string or the #GQuark identifier it is possible to
+retrieve the other.
+</para>
+<para>
+Quarks are used for both
+<link linkend="glib-datasets">Datasets</link> and
+<link linkend="glib-keyed-data-lists">Keyed Data Lists</link>.
+</para>
+<para>
+To create a new quark from a string, use g_quark_from_string() or
+g_quark_from_static_string().
+</para>
+<para>
+To find the string corresponding to a given #GQuark, use g_quark_to_string().
+</para>
+<para>
+To find the #GQuark corresponding to a given string, use g_quark_try_string().
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### TYPEDEF GQuark ##### -->
<para>
-
+A GQuark is an integer which uniquely identifies a particular string.
</para>
<!-- ##### FUNCTION g_quark_from_string ##### -->
<para>
-
+Gets the #GQuark identifying the given string.
+If the string does not currently have an associated #GQuark, a new
+#GQuark is created, using a copy of the string.
</para>
-@string:
-@Returns:
+@string: a string.
+@Returns: the #GQuark identifying the string.
<!-- ##### FUNCTION g_quark_from_static_string ##### -->
<para>
-
+Gets the #GQuark identifying the given (static) string.
+If the string does not currently have an associated #GQuark, a new
+#GQuark is created, linked to the given string.
+</para>
+<para>
+Note that this function is identical to g_quark_from_string() except
+that if a new #GQuark is created the string itself is used rather than
+a copy. This saves memory, but can only be used if the string will
+always exist (if, for example, it is a statically-allocated string).
</para>
-@string:
-@Returns:
+@string: a string.
+@Returns: the #GQuark identifying the string.
<!-- ##### FUNCTION g_quark_to_string ##### -->
<para>
-
+Gets the string associated with the given #GQuark.
</para>
-@quark:
-@Returns:
+@quark: a #GQuark.
+@Returns: the string associated with the #GQuark.
<!-- ##### FUNCTION g_quark_try_string ##### -->
<para>
-
+Gets the #GQuark associated with the given string, or 0 if the string has
+no associated #GQuark.
+</para>
+<para>
+If you want the GQuark to be created if it doesn't already exist, use
+g_quark_from_string() or g_quark_from_static_string().
</para>
-@string:
-@Returns:
+@string: a string.
+@Returns: the #GQuark associated with the string, or 0 if there is no
+#GQuark associated with the string.
Relations and Tuples
<!-- ##### SECTION Short_Description ##### -->
-
+tables of data which can be indexed on any number of fields.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+A #GRelation is a table of data which can be indexed on any number of fields,
+rather like simple database tables. A #GRelation contains a number of
+records, called tuples. Each record contains a number of fields.
+Records are not ordered, so it is not possible to find the record at a
+particular index.
+</para>
+<para>
+Note that #GRelation tables are currently limited to 2 fields.
+</para>
+<para>
+To create a GRelation, use g_relation_new().
+</para>
+<para>
+To specify which fields should be indexed, use g_relation_index().
+Note that this must be called before any tuples are added to the #GRelation.
+</para>
+<para>
+To add records to a #GRelation use g_relation_insert().
+</para>
+<para>
+To determine if a given record appears in a #GRelation, use
+g_relation_exists(). Note that fields are compared directly, so pointers
+must point to the exact same position (i.e. different copies of the same
+string will not match.)
+</para>
+<para>
+To count the number of records which have a particular value in a given
+field, use g_relation_count().
+</para>
+<para>
+To get all the records which have a particular value in a given field,
+use g_relation_select(). To access fields of the resulting records,
+use g_tuples_index(). To free the resulting records use g_tuples_destroy().
+</para>
+<para>
+To delete all records which have a particular value in a given field,
+use g_relation_delete().
+</para>
+<para>
+To destroy the #GRelation, use g_relation_destroy().
+</para>
+<para>
+To help debug #GRelation objects, use g_relation_print().
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GRelation ##### -->
<para>
-
+The #GRelation struct is an opaque data structure to represent a
+<link linkend="glib-Relations-and-Tuples">Relation</link>.
+It should only be accessed via the following functions.
</para>
<!-- ##### FUNCTION g_relation_new ##### -->
<para>
-
+Creates a new #GRelation with the given number of fields.
+Note that currently the number of fields must be 2.
</para>
-@fields:
-@Returns:
+@fields: the number of fields.
+@Returns: a new #GRelation.
<!-- ##### FUNCTION g_relation_index ##### -->
<para>
-
+Creates an index on the given field.
+Note that this must be called before any records are added to the #GRelation.
</para>
-@relation:
-@field:
-@hash_func:
-@key_compare_func:
+@relation: a #GRelation.
+@field: the field to index, counting from 0.
+@hash_func: a function to produce a hash value from the field data.
+@key_compare_func: a function to compare two values of the given field.
<!-- ##### FUNCTION g_relation_insert ##### -->
<para>
-
+Inserts a record into a #GRelation.
</para>
-@relation:
-@Varargs:
+@relation: a #GRelation.
+@Varargs: the fields of the record to add. This must match the number of
+fields in the #GRelation.
<!-- ##### FUNCTION g_relation_exists ##### -->
<para>
-
+Returns TRUE if a record with the given values exists in a #GRelation.
+Note that the values are compared directly, so that, for example, two
+copies of the same string will not match.
</para>
-@relation:
-@Varargs:
-@Returns:
+@relation: a #GRelation.
+@Varargs: the fields of the record to compare. The number must match the
+number of fields in the #GRelation.
+@Returns: TRUE if a record matches.
<!-- ##### FUNCTION g_relation_count ##### -->
<para>
-
+Returns the number of tuples in a #GRelation that have the given value
+in the given field.
</para>
-@relation:
-@key:
-@field:
-@Returns:
+@relation: a #GRelation.
+@key: the value to compare with.
+@field: the field of each record to match.
+@Returns: the number of matches.
<!-- ##### FUNCTION g_relation_select ##### -->
<para>
-
+Returns all of the tuples which have the given key in the given field.
+Use g_tuples_index() to access the returned records.
+The returned records should be freed with g_tuples_destroy().
</para>
-@relation:
-@key:
-@field:
-@Returns:
+@relation: a #GRelation.
+@key: the value to compare with.
+@field: the field of each record to match.
+@Returns: the records (tuples) that matched.
<!-- ##### FUNCTION g_relation_delete ##### -->
<para>
-
+Deletes any records from a GRelation that have the given key value in
+the given field.
</para>
-@relation:
-@key:
-@field:
-@Returns:
+@relation: a #GRelation.
+@key: the value to compare with.
+@field: the field of each record to match.
+@Returns: the number of records deleted.
<!-- ##### FUNCTION g_relation_destroy ##### -->
<para>
-
+Destroys the #GRelation, freeing all memory allocated.
+However, it does not free memory allocated for the
+tuple data, so you should free that first if appropriate.
</para>
-@relation:
+@relation: a #GRelation.
<!-- ##### FUNCTION g_relation_print ##### -->
<para>
-
+Outputs information about all records in a #GRelation, as well as the indexes.
+It is for debugging.
</para>
-@relation:
+@relation: a #GRelation.
<!-- ##### STRUCT GTuples ##### -->
<para>
-
+The #GTuples struct is used to return records (or tuples) from the
+#GRelation by g_relation_select().
+It only contains one public member - the number of records that matched.
+To access the matched records, you must use g_tuples_index().
</para>
@len:
<!-- ##### FUNCTION g_tuples_destroy ##### -->
<para>
-
+Frees the records which were returned by g_relation_select().
+This should always be called after g_relation_select() when you are
+finished with the records.
+The records are not removed from the #GRelation.
</para>
-@tuples:
+@tuples: the tuple data to free.
<!-- ##### FUNCTION g_tuples_index ##### -->
<para>
-
+Gets a field from the records returned by g_relation_select().
+It returns the given field of the record at the given index.
+The returned value should not be changed.
</para>
-@tuples:
-@index:
-@field:
-@Returns:
+@tuples: the tuple data, returned by g_relation_select().
+@index: the index of the record.
+@field: the field to return.
+@Returns: the field of the record.
Lexical Scanner
<!-- ##### SECTION Short_Description ##### -->
-
+a general purpose lexical scanner.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GScanner and its associated functions provide a general purpose
+lexical scanner.
+</para>
+<para>
+FIXME: really needs an example and more detail, but I don't completely
+understand it myself. Look at gtkrc.c for some code using the scanner.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GScanner ##### -->
<para>
-
+The data structure representing a lexical scanner.
+</para>
+<para>
+You should set input_name after creating the scanner, since it is used
+by the default message handler when displaying warnings and errors.
+If you are scanning a file, the file name would be a good choice.
+</para>
+<para>
+The <structfield>user_data</structfield> and
+<structfield>derived_data</structfield> fields are not used.
+If you need to associate extra data with the scanner you can place them here.
+</para>
+<para>
+If you want to use your own message handler you can set the
+<structfield>msg_handler</structfield> field. The type of the message
+handler function is declared by #GScannerMsgFunc.
</para>
@user_data:
<!-- ##### FUNCTION g_scanner_new ##### -->
<para>
-
+Creates a new #GScanner.
+The @config_templ structure specifies the initial settings of the scanner,
+which are copied into the #GScanner <structfield>config</structfield> field.
+If you pass NULL then the default settings are used.
+(See g_scanner_config_template in gscanner.c for the defaults.)
</para>
-@config_templ:
-@Returns:
+@config_templ: the initial scanner settings.
+@Returns: the new #GScanner.
<!-- ##### STRUCT GScannerConfig ##### -->
<para>
-
+Specifies the #GScanner settings.
+</para>
+<para>
+<structfield>cset_skip_characters</structfield> specifies which characters
+should be skipped by the scanner (the default is the whitespace characters:
+space, tab, carriage-return and line-feed).
+</para>
+<para>
+<structfield>cset_identifier_first</structfield> specifies the characters
+which can start identifiers.
+(the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z).
+</para>
+<para>
+<structfield>cset_identifier_nth</structfield> specifies the characters
+which can be used in identifiers, after the first character.
+The default is #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS,
+#G_CSET_LATINC.
+</para>
+<para>
+<structfield>cpair_comment_single</structfield> specifies the characters
+at the start and end of single-line comments. The default is "#\n" which
+means that single-line comments start with a '#' and continue until a '\n'
+(end of line).
+</para>
+<para>
+<structfield>case_sensitive</structfield> specifies if symbols are
+case sensitive.
+</para>
+<para>
+The rest of the fields are flags which turn features on or off.
+FIXME: should describe these.
</para>
@cset_skip_characters:
<!-- ##### FUNCTION g_scanner_input_file ##### -->
<para>
-
+Prepares to scan a file.
</para>
-@scanner:
-@input_fd:
+@scanner: a #GScanner.
+@input_fd: a file descriptor.
<!-- ##### FUNCTION g_scanner_sync_file_offset ##### -->
<!-- ##### FUNCTION g_scanner_stat_mode ##### -->
<para>
-
+Gets the file attributes.
+This is the <structfield>st_mode</structfield> field from the
+<structname>stat</structname> structure. See the <function>stat()</function>
+documentation.
</para>
-@filename:
-@Returns:
+@filename: the file name.
+@Returns: the file attributes.
<!-- ##### FUNCTION g_scanner_input_text ##### -->
<para>
-
+Prepares to scan a text buffer.
</para>
-@scanner:
-@text:
-@text_len:
+@scanner: a #GScanner.
+@text: the text buffer to scan.
+@text_len: the length of the text buffer.
<!-- ##### FUNCTION g_scanner_peek_next_token ##### -->
<para>
-
+Gets the next token, without removing it from the input stream.
+The token data is placed in the
+<structfield>next_token</structfield>,
+<structfield>next_value</structfield>,
+<structfield>next_line</structfield>, and
+<structfield>next_position</structfield> fields of the #GScanner structure.
</para>
-@scanner:
-@Returns:
+@scanner: a #GScanner.
+@Returns: the type of the token.
<!-- ##### FUNCTION g_scanner_get_next_token ##### -->
<para>
-
+Gets the next token, removing it from the input stream.
+The token data is placed in the
+<structfield>token</structfield>,
+<structfield>value</structfield>,
+<structfield>line</structfield>, and
+<structfield>position</structfield> fields of the #GScanner structure.
</para>
-@scanner:
-@Returns:
+@scanner: a #GScanner.
+@Returns: the type of the token.
<!-- ##### FUNCTION g_scanner_cur_line ##### -->
<para>
-
+Gets the current line in the input stream (counting from 1).
</para>
-@scanner:
-@Returns:
+@scanner: a #GScanner.
+@Returns: the current line.
<!-- ##### FUNCTION g_scanner_cur_position ##### -->
<para>
-
+Gets the current position in the current line (counting from 0).
</para>
-@scanner:
-@Returns:
+@scanner: a #GScanner.
+@Returns: the current position on the line.
<!-- ##### FUNCTION g_scanner_cur_token ##### -->
<para>
-
+Gets the current token type.
+This is simply the <structfield>token</structfield> field in the #GScanner
+structure.
</para>
-@scanner:
-@Returns:
+@scanner: a #GScanner.
+@Returns: the current token type.
<!-- ##### FUNCTION g_scanner_cur_value ##### -->
<para>
-
+Gets the current token value.
+This is simply the <structfield>value</structfield> field in the #GScanner
+structure.
</para>
-@scanner:
-@Returns:
+@scanner: a #GScanner.
+@Returns: the current token value.
<!-- ##### FUNCTION g_scanner_eof ##### -->
<para>
-
+Returns TRUE if the scanner has reached the end of the file or text buffer.
</para>
-@scanner:
-@Returns:
+@scanner: a #GScanner.
+@Returns: TRUE if the scanner has reached the end of the file or text buffer.
<!-- ##### FUNCTION g_scanner_set_scope ##### -->
<para>
-
+Sets the current scope.
</para>
-@scanner:
-@scope_id:
-@Returns:
+@scanner: a #GScanner.
+@scope_id: the new scope id.
+@Returns: the old scope id.
<!-- ##### FUNCTION g_scanner_scope_add_symbol ##### -->
<para>
-
+Adds a symbol to the given scope.
</para>
-@scanner:
-@scope_id:
-@symbol:
-@value:
+@scanner: a #GScanner.
+@scope_id: the scope id.
+@symbol: the symbol to add.
+@value: the value of the symbol.
<!-- ##### FUNCTION g_scanner_scope_foreach_symbol ##### -->
@scope_id:
@func:
@user_data:
+<!-- # Unused Parameters # -->
+@func_data:
<!-- ##### FUNCTION g_scanner_scope_lookup_symbol ##### -->
<!-- ##### FUNCTION g_scanner_warn ##### -->
<para>
-
+Outputs a warning message, via the #GScanner message handler.
</para>
-@scanner:
-@format:
-@Varargs:
+@scanner: a #GScanner.
+@format: the message format. See the <function>printf()</function>
+documentation.
+@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_scanner_error ##### -->
<para>
-
+Outputs an error message, via the #GScanner message handler.
</para>
-@scanner:
-@format:
-@Varargs:
+@scanner: a #GScanner.
+@format: the message format. See the <function>printf()</function>
+documentation.
+@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_scanner_unexp_token ##### -->
<para>
-
+Outputs a message resulting from an unexpected token in the input stream.
+FIXME: I don't understand the arguments here.
</para>
-@scanner:
-@expected_token:
-@identifier_spec:
-@symbol_spec:
+@scanner: a #GScanner.
+@expected_token: the expected token.
+@identifier_spec: a string describing the expected type of identifier,
+or NULL to use the default "identifier" string.
+@symbol_spec: a string describing the expected type of identifier,
+or NULL to use the default "symbol" string.
@symbol_name:
-@message:
-@is_error:
+@message: a message string to output at the end of the warning/error, or NULL.
+@is_error: if TRUE it is output as an error. If False it is output as a
+warning.
<!-- ##### USER_FUNCTION GScannerMsgFunc ##### -->
<!-- ##### FUNCTION g_scanner_destroy ##### -->
<para>
-
+Frees all memory used by the #GScanner.
</para>
-@scanner:
+@scanner: a #GScanner.
<!-- ##### ENUM GTokenType ##### -->
<para>
-
+The possible types of token returned from each g_scanner_get_next_token() call.
</para>
@G_TOKEN_EOF:
<!-- ##### UNION GTokenValue ##### -->
<para>
-
+A union holding the value of the token.
</para>
<!-- ##### ENUM GErrorType ##### -->
<para>
-
+The possible errors, used in the <structfield>v_error</structfield> field
+of #GTokenValue, when the token is a G_TOKEN_ERROR.
</para>
@G_ERR_UNKNOWN:
<!-- ##### MACRO G_CSET_a_2_z ##### -->
<para>
-
+The set of lower-case ASCII alphabet characters.
+Used for specifying valid identifier characters in #GScannerConfig.
</para>
<!-- ##### MACRO G_CSET_A_2_Z ##### -->
<para>
-
+The set of upper-case ASCII alphabet characters.
+Used for specifying valid identifier characters in #GScannerConfig.
</para>
<!-- ##### MACRO G_CSET_LATINC ##### -->
<para>
-
+Part of the set of extended characters in the Latin character sets.
+FIXME: lower case?
+Used for specifying valid identifier characters in #GScannerConfig.
</para>
<!-- ##### MACRO G_CSET_LATINS ##### -->
<para>
-
+Part of the set of extended characters in the Latin character sets.
+FIXME: upper case?
+Used for specifying valid identifier characters in #GScannerConfig.
</para>
<!-- ##### MACRO g_scanner_add_symbol ##### -->
<para>
-
+Adds a symbol to the default scope.
+Deprecated in favour of g_scanner_scope_add_symbol().
</para>
-@scanner:
-@symbol:
-@value:
+@scanner: a #GScanner.
+@symbol: the symbol to add.
+@value: the value of the symbol.
<!-- ##### MACRO g_scanner_remove_symbol ##### -->
<para>
-
+Removes a symbol from the default scope.
+Deprecated in favour of g_scanner_scope_remove_symbol().
</para>
-@scanner:
-@symbol:
+@scanner: a #GScanner.
+@symbol: the symbol to remove.
<!-- ##### MACRO g_scanner_foreach_symbol ##### -->
<para>
-
+Calls a function for each symbol in the default scope.
+Deprecated in favour of g_scanner_scope_foreach_symbol().
</para>
-@scanner:
-@func:
-@data:
+@scanner: a #GScanner.
+@func: the function to call with each symbol.
+@data: data to pass to the function.
String Chunks
<!-- ##### SECTION Short_Description ##### -->
-
+efficient storage of groups of strings.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+String chunks are used to store groups of strings.
+Memory is allocated in blocks, and as strings are added to the #GStringChunk
+they are copied into the next free position in a block. When a block is
+full a new block is allocated.
+</para>
+<para>
+When storing a large number of strings, string chunks are more efficient
+than using g_strdup() since fewer calls to <function>malloc()</function>
+are needed, and less memory is wasted in memory allocation overheads.
+</para>
+<para>
+By adding strings with g_string_chunk_insert_const() it is also possible
+to remove duplicates.
+</para>
+<para>
+To create a new #GStringChunk use g_string_chunk_new().
+</para>
+<para>
+To add strings to a #GStringChunk use g_string_chunk_insert().
+</para>
+<para>
+To add strings to a #GStringChunk, but without duplicating strings which are
+already in the #GStringChunk, use g_string_chunk_insert_const().
+</para>
+<para>
+To free the entire #GStringChunk use g_string_chunk_free().
+It is not possible to free individual strings.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GStringChunk ##### -->
<para>
-
+An opaque data structure representing String Chunks.
+It should only be accessed by using the following functions.
</para>
<!-- ##### FUNCTION g_string_chunk_new ##### -->
<para>
-
+Creates a new #GStringChunk.
</para>
-@size:
-@Returns:
+@size: 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.
+@Returns: a new #GStringChunk.
<!-- ##### FUNCTION g_string_chunk_insert ##### -->
<para>
-
+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.
+</para>
+<para>
+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.
</para>
-@chunk:
-@string:
-@Returns:
+@chunk: a #GStringChunk.
+@string: the string to add.
+@Returns: a pointer to the copy of @string within the #GStringChunk.
<!-- ##### FUNCTION g_string_chunk_insert_const ##### -->
<para>
-
+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().
+</para>
+<para>
+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.
+</para>
+<para>
+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.
</para>
-@chunk:
-@string:
-@Returns:
+@chunk: a #GStringChunk.
+@string: the string to add.
+@Returns: a pointer to the new or existing copy of @string within the
+#GStringChunk.
<!-- ##### FUNCTION g_string_chunk_free ##### -->
<para>
-
+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.
</para>
-@chunk:
+@chunk: a #GStringChunk.
String Utility Functions
<!-- ##### SECTION Short_Description ##### -->
-
+various string-related functions.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+This section describes a number of utility functions for creating,
+duplicating, and manipulating strings.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### FUNCTION g_strdup ##### -->
<para>
-
+Duplicates a string.
+The returned string should be freed when no longer needed.
</para>
-@str:
-@Returns:
+@str: the string to duplicate.
+@Returns: a newly-allocated copy of @str.
<!-- ##### FUNCTION g_strndup ##### -->
<para>
-
+Duplicates the first @n characters of a string, returning a newly-allocated
+buffer @n + 1 characters long which will always be null-terminated.
+If @str is less than @n characters long the buffer is padded with nulls.
+The returned value should be freed when no longer needed.
</para>
-@str:
-@n:
-@Returns:
+@str: the string to duplicate part of.
+@n: the maximum number of characters to copy from @str.
+@Returns: a newly-allocated buffer containing the first @n characters of @str,
+null-terminated.
<!-- ##### FUNCTION g_strnfill ##### -->
<para>
-
+Creates a new string @length characters long filled with @fill_char.
+The returned string should be freed when no longer needed.
</para>
-@length:
-@fill_char:
-@Returns:
+@length: the length of the new string.
+@fill_char: the character to fill the string with.
+@Returns: a newly-allocated string filled the @fill_char.
<!-- ##### FUNCTION g_strlcpy ##### -->
<!-- ##### FUNCTION g_strdup_printf ##### -->
<para>
-
+Similar to the standard C <function>sprintf()</function> function
+but safer, since it calculates the maximum space required and allocates
+memory to hold the result.
+The returned string should be freed when no longer needed.
</para>
-@format:
-@Varargs:
-@Returns:
+@format: the standard <function>sprintf()</function> format string.
+@Varargs: the parameters to insert into the format string.
+@Returns: a newly-allocated string holding the result.
<!-- ##### FUNCTION g_strdup_vprintf ##### -->
<para>
-
+Similar to the standard C <function>vsprintf()</function> function
+but safer, since it calculates the maximum space required and allocates
+memory to hold the result.
+The returned string should be freed when no longer needed.
</para>
-@format:
-@args:
-@Returns:
+@format: the standard <function>sprintf()</function> format string.
+@args: the list of parameters to insert into the format string.
+@Returns: a newly-allocated string holding the result.
<!-- ##### FUNCTION g_snprintf ##### -->
<para>
-
+A safer form of the standard <function>sprintf()</function> function.
+The output is guaranteed to not exceed @n characters (including the
+terminating NULL character), so it is easy to ensure that a buffer overflow
+cannot occur.
+</para>
+<para>
+See also g_strdup_printf().
+</para>
+<note>
+<para>
+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 NULL-terminated.
</para>
+</note>
-@string:
-@n:
-@format:
-@Varargs:
-@Returns:
+@string: the buffer to hold the output.
+@n: the maximum number of characters to produce (including the terminating null
+character).
+@format: the format string. See the <function>sprintf()</function>
+documentation.
+@Varargs: the arguments to insert in the output.
+@Returns: the length of the output string.
<!-- ##### FUNCTION g_vsnprintf ##### -->
<para>
-
+A safer form of the standard <function>vsprintf()</function> function.
+The output is guaranteed to not exceed @n characters (including the
+terminating NULL character), so it is easy to ensure that a buffer overflow
+cannot occur.
+</para>
+<para>
+See also g_strdup_vprintf().
</para>
+<note>
+<para>
+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 NULL-terminated.
+</para>
+</note>
-@string:
-@n:
-@format:
-@args:
-@Returns:
+@string: the buffer to hold the output.
+@n: the maximum number of characters to produce (including the terminating null
+character).
+@format: the format string. See the <function>sprintf()</function>
+documentation.
+@args: the list of arguments to insert in the output.
+@Returns: the length of the output string.
<!-- ##### FUNCTION g_printf_string_upper_bound ##### -->
<para>
-
+Calculates the maximum space needed to store the output of the
+<function>sprintf()</function> function.
</para>
-@format:
-@args:
-@Returns:
+@format: the format string. See the <function>printf()</function>
+documentation.
+@args: the parameters to be inserted into the format string.
+@Returns: the maximum space needed to store the formatted string.
<!-- ##### FUNCTION g_strup ##### -->
<para>
-
+Converts a string to upper case.
</para>
-@string:
+@string: the string to convert.
@Returns:
<!-- ##### FUNCTION g_strdown ##### -->
<para>
-
+Converts a string to lower case.
</para>
-@string:
+@string: the string to convert.
@Returns:
<!-- ##### FUNCTION g_strcasecmp ##### -->
<para>
-
+A case-insensitive string comparison, corresponding to the standard
+<function>strcasecmp()</function> function on platforms which support it.
</para>
-@s1:
-@s2:
-@Returns:
+@s1: a string.
+@s2: a string to compare with @s1.
+@Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive
+value if @s1 > @s2.
<!-- ##### FUNCTION g_strncasecmp ##### -->
<para>
-
+A case-insensitive string comparison, corresponding to the standard
+<function>strncasecmp()</function> function on platforms which support it.
+It is similar to g_strcasecmp() except it only compares the first @n characters
+of the strings.
</para>
-@s1:
-@s2:
-@n:
-@Returns:
+@s1: a string.
+@s2: a string to compare with @s1.
+@n: the maximum number of characters to compare.
+@Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive
+value if @s1 > @s2.
<!-- ##### FUNCTION g_strreverse ##### -->
<para>
-
+Reverses all of the characters in a string.
+For example, g_strreverse ("abcdef") would be "fedcba".
</para>
-@string:
+@string: the string to reverse.
@Returns:
<!-- ##### FUNCTION g_strtod ##### -->
<para>
-
+Converts a string to a gdouble value.
+It calls the standard <function>strtod()</function> function
+to handle the conversion, but if the string is not completely converted
+it attempts the conversion again in the "C" locale, and returns the best
+match.
</para>
-@nptr:
-@endptr:
-@Returns:
+@nptr: the string to convert to a numeric value.
+@endptr: if non-NULL, it returns the character after the last character used
+in the conversion.
+@Returns: the gdouble value.
<!-- ##### FUNCTION g_strchug ##### -->
<para>
-
+Removes leading whitespace from a string, by moving the rest of the
+characters forward.
</para>
-@string:
-@Returns:
+@string: a string to remove the leading whitespace from.
+@Returns: @string.
<!-- ##### FUNCTION g_strchomp ##### -->
<para>
-
+Removes trailing whitespace from a string.
</para>
-@string:
-@Returns:
+@string: a string to remove the trailing whitespace from.
+@Returns: @string.
<!-- ##### MACRO g_strstrip ##### -->
<para>
-
+Removes leading and trailing whitespace from a string.
</para>
-@string:
+@string: a string to remove the leading and trailing whitespace from.
<!-- ##### FUNCTION g_strdelimit ##### -->
<para>
-
+Converts any delimiter characters in @string to @new_delimiter.
+Any characters in @string which are found in @delimiters are changed
+to the @new_delimiter character.
</para>
-@string:
-@delimiters:
-@new_delimiter:
+@string: the string to convert.
+@delimiters: a string containing the current delimiters, or NULL to use the
+standard delimiters defined in #G_STR_DELIMITERS.
+@new_delimiter: the new delimiter character.
@Returns:
<!-- ##### MACRO G_STR_DELIMITERS ##### -->
<para>
-
+The standard delimiters, used in #g_strdelimit.
</para>
<!-- ##### FUNCTION g_strescape ##### -->
<para>
-
+Escapes all backslash characters, '\' in a string, by inserting a second '\'.
</para>
@source:
@exceptions:
-@Returns:
+@Returns: a newly allocated copy of @string, with all backslash characters
+escaped using a second backslash.
+<!-- # Unused Parameters # -->
+@string: a string to escape the backslashes in.
<!-- ##### FUNCTION g_strcompress ##### -->
<!-- ##### FUNCTION g_strsplit ##### -->
<para>
-
+Splits a string into a maximum of @max_tokens pieces, using the given
+@delimiter. If @max_tokens is reached, the final string in the returned
+string array contains the remainder of @string.
</para>
-@string:
-@delimiter:
-@max_tokens:
-@Returns:
+@string: a string to split.
+@delimiter: 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.
+@max_tokens: the maximum number of strings to split @string into. If this is
+less than 1, the string is split completely.
+@Returns: a newly-allocated array of strings. Use g_strfreev() to free it.
<!-- ##### FUNCTION g_strfreev ##### -->
<para>
-
+Frees a NULL-terminated array of strings, and the array itself.
</para>
-@str_array:
+@str_array: a NULL-terminated array of strings to free.
<!-- ##### FUNCTION g_strconcat ##### -->
<para>
-
+Concatenates all of the given strings into one long string.
+The returned string should be freed when no longer needed.
</para>
-@string1:
-@Varargs:
-@Returns:
+@string1: The first string to add, which must not be NULL.
+@Varargs: a NULL-terminated list of strings to append to the string.
+@Returns: a newly-allocated string containing all the string arguments.
<!-- ##### FUNCTION g_strjoin ##### -->
<para>
-
+Joins a number of strings together to form one long string, with the optional
+@separator inserted between each of them.
</para>
-@separator:
-@Varargs:
-@Returns:
+@separator: a string to insert between each of the strings, or NULL.
+@Varargs: a NULL-terminated list of strings to join.
+@Returns: a newly-allocated string containing all of the strings joined
+together, with @separator between them.
<!-- ##### FUNCTION g_strjoinv ##### -->
<para>
-
+Joins a number of strings together to form one long string, with the optional
+@separator inserted between each of them.
</para>
-@separator:
-@str_array:
-@Returns:
+@separator: a string to insert between each of the strings, or NULL.
+@str_array: a NULL-terminated array of strings to join.
+@Returns: a newly-allocated string containing all of the strings joined
+together, with @separator between them.
<!-- ##### FUNCTION g_strerror ##### -->
<para>
-
+Returns a string corresponding to the given error code, e.g. "no such process".
+This function is included since not all platforms support the
+<function>strerror()</function> function.
</para>
-@errnum:
-@Returns:
+@errnum: the system error number. See the standard C %errno
+documentation.
+@Returns: a string describing the error code.
+If the error code is unknown, it returns "unknown error (<code>)".
+The string can only be used until the next call to g_strerror.
<!-- ##### FUNCTION g_strsignal ##### -->
<para>
-
+Returns a string describing the given signal, e.g. "Segmentation fault".
+This function is included since not all platforms support the
+<function>strsignal()</function> function.
</para>
-@signum:
-@Returns:
+@signum: the signal number. See the <literal>signal</literal>
+documentation.
+@Returns: a string describing the signal.
+If the signal is unknown, it returns "unknown signal (<signum>)".
+The string can only be used until the next call to g_strsignal.
Strings
<!-- ##### SECTION Short_Description ##### -->
-
+text buffers which grow automatically as text is added.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+A #GString is similar to a standard C string, except that it grows
+automatically as text is appended or inserted.
+</para>
+<para>
+The space allocated for the string is always a power of two, so as the
+string grows it will occupy 2, 4, 8, 16, 32, 64, 128 etc. characters.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GString ##### -->
<para>
-
+The #GString struct contains the public fields of a #GString.
+The <structfield>str</structfield> field points to the character data.
+It may move as text is added.
+The <structfield>len</structfield> field contains the length of the string,
+not including the terminating null character.
+</para>
+<para>
+The str field is zero-terminated and so can be used as an ordinary C
+string. But it may be moved when text is appended or inserted into the
+string.
</para>
@str:
<!-- ##### FUNCTION g_string_new ##### -->
<para>
-
+Creates a new #GString, initialized with the given string.
</para>
-@init:
-@Returns:
+@init: the initial text to copy into the string.
+@Returns: the new #GString.
<!-- ##### FUNCTION g_string_sized_new ##### -->
<para>
-
+Creates a new GString, with enough space for @dfl_size characters.
+This is useful if you are going to add a lot of text to the string and
+don't want it to be reallocated too often.
</para>
-@dfl_size:
-@Returns:
+@dfl_size: the default size of the space allocated to hold the string.
+@Returns: the new #GString.
<!-- ##### FUNCTION g_string_assign ##### -->
<para>
-
+Copies the characters from one #GString into another, 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.
</para>
@string:
-@rval:
-@Returns:
+@rval: the source #GString.
+@Returns: the destination #GString.
+<!-- # Unused Parameters # -->
+@lval: the destination #GString. Its current contents are destroyed.
<!-- ##### FUNCTION g_string_sprintf ##### -->
<para>
-
+Writes a formatted string into a #GString.
+This is similar to the standard <function>sprintf()</function> function,
+except that the GString buffer automatically expands to contain the results.
+The previous contents of the GString are destroyed.
</para>
-@string:
-@format:
-@Varargs:
+@string: a #GString.
+@format: the string format. See the <function>sprintf()</function>
+documentation.
+@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_string_sprintfa ##### -->
<para>
-
+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.
</para>
-@string:
-@format:
-@Varargs:
+@string: a #GString.
+@format: the string format. See the <function>sprintf()</function>
+documentation.
+@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_string_append ##### -->
<para>
-
+Adds a string onto the end of a #GString, expanding it if necessary.
</para>
-@string:
-@val:
-@Returns:
+@string: a #GString.
+@val: the string to append onto the end of the #GString.
+@Returns: the #GString.
<!-- ##### FUNCTION g_string_append_c ##### -->
<para>
-
+Adds a character onto the end of a #GString, expanding it if necessary.
</para>
-@string:
-@c:
-@Returns:
+@string: a #GString.
+@c: the character to append onto the end of the #GString.
+@Returns: the #GString.
<!-- ##### FUNCTION g_string_append_len ##### -->
<!-- ##### FUNCTION g_string_prepend ##### -->
<para>
-
+Adds a string on to the start of a #GString, expanding it if necessary.
</para>
-@string:
-@val:
-@Returns:
+@string: a #GString.
+@val: the string to prepend on the start of the #GString.
+@Returns: the #GString.
<!-- ##### FUNCTION g_string_prepend_c ##### -->
<para>
-
+Adds a character onto the start of a #GString, expanding it if necessary.
</para>
-@string:
-@c:
-@Returns:
+@string: a #GString.
+@c: the character to prepend on the start of the #GString.
+@Returns: the #GString.
<!-- ##### FUNCTION g_string_prepend_len ##### -->
<!-- ##### FUNCTION g_string_insert ##### -->
<para>
-
+Inserts a copy of a string into a #GString, expanding it if necessary.
</para>
-@string:
-@pos:
-@val:
-@Returns:
+@string: a #GString.
+@pos: the position to insert the copy of the string.
+@val: the string to insert.
+@Returns: the #GString.
<!-- ##### FUNCTION g_string_insert_c ##### -->
<para>
-
+Inserts a character into a #GString, expanding it if necessary.
</para>
-@string:
-@pos:
-@c:
-@Returns:
+@string: a #GString.
+@pos: the position to insert the character.
+@c: the character to insert.
+@Returns: the #GString.
<!-- ##### FUNCTION g_string_insert_len ##### -->
<!-- ##### FUNCTION g_string_erase ##### -->
<para>
-
+Removes @len characters from a #GString, starting at position @pos.
+The rest of the #GString is shifted down to fill the gap.
</para>
-@string:
-@pos:
-@len:
-@Returns:
+@string: a #GString.
+@pos: the position of the characters to remove.
+@len: the number of characters to remove.
+@Returns: the #GString.
<!-- ##### FUNCTION g_string_truncate ##### -->
<para>
-
+Cuts off the end of the GString, leaving the first @len characters.
</para>
-@string:
-@len:
-@Returns:
+@string: a #GString.
+@len: the new size of the #GString.
+@Returns: the #GString.
<!-- ##### FUNCTION g_string_free ##### -->
<para>
-
+Frees the memory allocated for the #GString.
+If free_segment is TRUE it also frees the character data.
</para>
-@string:
-@free_segment:
+@string: a #GString.
+@free_segment: if TRUE the actual character data is freed as well.
@Returns:
<!-- ##### FUNCTION g_string_up ##### -->
<para>
-
+Converts a #GString to upper case.
</para>
-@string:
-@Returns:
+@string: a #GString.
+@Returns: the #GString.
<!-- ##### FUNCTION g_string_down ##### -->
<para>
-
+Converts a #GString to lower case.
</para>
-@string:
-@Returns:
+@string: a #GString.
+@Returns: the #GString.
<!-- ##### FUNCTION g_string_hash ##### -->
<!-- ##### SECTION Title ##### -->
+
Threads
<!-- ##### SECTION Short_Description ##### -->
+thread abstraction; including mutexes, conditions and thread private data.
<!-- ##### SECTION Long_Description ##### -->
+
<para>
+Threads act almost like processes, but unlike processes all threads of
+one process share the same memory. This is good, as it provides easy
+communication between the involved threads via this shared memory, and
+it is bad, because strange things (so called Heisenbugs) might happen,
+when the program is not carefully designed. Especially bad is, that due
+to the concurrent nature of threads no assumptions on the order of
+execution of different threads can be done unless explictly forced by
+the programmer through synchronization primitives.
+</para>
+<para>
+The aim of the thread related functions in GLib is to provide a
+portable means for writing multithread safe software. There are
+primitives for mutexes to protect the access to portions of memory
+(#GMutex, #GStaticMutex, #G_LOCK_DEFINE and friends), there are
+primitives for condition variables to allow synchronization of threads
+(#GCond) and finally there are primitives for thread-private data,
+that every thread has a private instance of (#GPrivate,
+#GStaticPrivate).
+</para>
+
+<para>
+Currently there is only as much thread support included in GLib as is
+necessary to make GLib itself multithread safe. Version 1.4 of GLib
+will contain full thread support. For now the most portable way to
+create threads is to require the macro #G_THREADS_IMPL_POSIX to be
+defined and use POSIX threads then. This will work on almost all
+platforms (except most notably Solaris and DCE threads.).
</para>
<!-- ##### SECTION See_Also ##### -->
</para>
<!-- ##### MACRO G_THREADS_ENABLED ##### -->
-<para>
+<para>
+This macro is defined, if GLib was compiled with thread support. This
+does not necessarily mean, that there is a thread implementation
+available, but the infrastructure is in place and once you provide a
+thread implementation to g_thread_init(), GLib will be multithread
+safe. It isn't and can't be, if #G_THREADS_ENABLED is not defined.
</para>
<!-- ##### MACRO G_THREADS_IMPL_POSIX ##### -->
-<para>
+<para>
+This macro is defined, if POSIX style threads are used.
</para>
<!-- ##### MACRO G_THREADS_IMPL_SOLARIS ##### -->
-<para>
+<para>
+This macro is defined, if the SOLARIS thread system is used.
</para>
<!-- ##### MACRO G_THREADS_IMPL_NONE ##### -->
-<para>
+<para>
+This macro is defined, if no thread implementation is used. You can
+however provide one to g_thread_init() to make GLib multithread safe.
</para>
@G_THREAD_ERROR_AGAIN:
<!-- ##### STRUCT GThreadFunctions ##### -->
+
<para>
+This function table is used by g_thread_init() to initialize the
+thread system. The functions in that table are directly used by their
+g_* prepended counterparts, that are described here, e.g. if you call
+g_mutex_new() then mutex_new() from the table provided to
+g_thread_init() will be called.
+</para>
+<note>
+<para>
+This struct should only be used, if you know, what you are doing.
</para>
+</note>
@mutex_new:
@mutex_lock:
@thread_self:
<!-- ##### FUNCTION g_thread_init ##### -->
+
+<para>
+Before you use a thread related function in GLib, you should
+initialize the thread system. This is done by calling
+g_thread_init(). Most of the time you will only have to call
+g_thread_init(NULL).
+</para>
+
+<note>
+<para>
+You should only call g_thread_init() with a non-NULL parameter, if you
+really know, what you are doing.
+</para>
+</note>
+
+<note>
+<para>
+g_thread_init() must not be called directly or indirectly as a
+callback from GLib.
+</para>
+</note>
+
<para>
+g_thread_init() might only be called once. On the second call
+it will abort with an error. If you want to make sure, that the thread
+system is initialized, you can do that too:
+</para>
+
+<para>
+<informalexample>
+<programlisting>
+if (!g_thread_supported ()) g_thread_init (NULL);
+</programlisting>
+</informalexample>
+</para>
+
+<para>
+After that line either the thread system is initialized or the program
+will abort, if no thread system is available in GLib, i.e. either
+#G_THREADS_ENABLED is not defined or #G_THREADS_IMPL_NONE is defined.
+</para>
+<para>
+If no thread system is available and @vtable is NULL or if not all
+elements of @vtable are non-NULL, then g_thread_init() will abort.
+</para>
+
+<note>
+<para>
+To use g_thread_init() in your program, you have to link with the
+libraries, that the command "glib-config --libs gthread" outputs. This
+is not the case for all the other thread related functions of
+GLib. Those can be used without having to link with the thread
+libraries.
</para>
+</note>
-@vtable:
+@vtable: a function table of type #GThreadFunctions, that provides the
+entry points to the thread system to be used.
<!-- ##### FUNCTION g_thread_supported ##### -->
<para>
+This function returns, whether the thread system is initialized or
+not.
+</para>
+<note>
+<para>
+This function is actually a macro. Apart from taking the address of it
+you can however use it as if it was a function.
</para>
+</note>
-@Returns:
+@Returns: TRUE, if the thread system is initialized.
<!-- ##### USER_FUNCTION GThreadFunc ##### -->
<!-- ##### STRUCT GMutex ##### -->
+
+<para>
+The #GMutex struct is an opaque data structure to represent a mutex
+(mutual exclusion). It can be used to protect data against shared
+access. Take for example the following function:
+
+<example>
+<title>A function which will not work in a threaded environment</title>
+<programlisting>
+ int give_me_next_number ()
+ {
+ static int current_number = 0;
+
+ /* now do a very complicated calculation to calculate the new number,
+ this might for example be a random number generator */
+ current_number = calc_next_number (current_number);
+ return current_number;
+ }
+</programlisting>
+</example>
+</para>
+
+<para>
+It is easy to see, that this won't work in a multithreaded
+application. There current_number must be protected against shared
+access. A first naive implementation would be:
+</para>
+
+<para>
+<example>
+<title>The wrong way to write a thread-safe function</title>
+<programlisting>
+ int give_me_next_number ()
+ {
+ static int current_number = 0;
+ int ret_val;
+ static GMutex * mutex = NULL;
+
+ if (!mutex)
+ mutex = g_mutex_new ();
+ g_mutex_lock (mutex);
+ ret_val = current_number = calc_next_number (current_number);
+ g_mutex_unlock (mutex);
+ return ret_val;
+ }
+</programlisting>
+</example>
+</para>
+
+<para>
+This looks like it would work, but there is a race condition while
+constructing the mutex and this code can't work reliable. So please do
+not use such constructs in your own programs. One working solution is:
+</para>
+
+<para>
+<example>
+<title>A correct thread-safe function</title>
+<programlisting>
+ static GMutex *give_me_next_number_mutex = NULL;
+
+ /* this function must be called before any call to give_me_next_number ()
+ it must be called exactly once. */
+ void init_give_me_next_number ()
+ {
+ g_assert (give_me_next_number_mutex == NULL);
+ give_me_next_number_mutex = g_mutex_new ();
+ }
+
+ int give_me_next_number ()
+ {
+ static int current_number = 0;
+ int ret_val;
+
+ g_mutex_lock (give_me_next_number_mutex);
+ ret_val = current_number = calc_next_number (current_number);
+ g_mutex_unlock (give_me_next_number_mutex);
+ return ret_val;
+ }
+</programlisting>
+</example>
+</para>
+
<para>
+#GStaticMutex provides a simpler and safer way of doing this.
+</para>
+<para>
+A #GMutex should only be accessed via the following functions.
</para>
+<note>
+<para>
+All of the g_mutex_* functions are actually macros. Apart from taking
+the addresses of them, you can however use them as if they were functions.
+</para>
+</note>
+
<!-- ##### FUNCTION g_mutex_new ##### -->
+
<para>
+Creates a new #GMutex.
+</para>
+<note>
+<para>
+This function will abort, if g_thread_init() has not been called yet.
</para>
+</note>
-@Returns:
+@Returns: a new #GMutex.
<!-- ##### FUNCTION g_mutex_lock ##### -->
+
<para>
+Locks the #GMutex. If the #GMutex is already locked by another thread,
+the current thread will block until the #GMutex is unlocked by the
+other thread.
+</para>
+<para>
+This function can also be used, if g_thread_init() has not yet been
+called and will do nothing then.
</para>
-@mutex:
+<note>
+<para>
+#GMutex is not guaranteed to be recursive, i.e. a thread might block,
+if it already has locked the #GMutex. It will deadlock then, of
+course.
+</para>
+</note>
+
+@mutex: a #GMutex.
<!-- ##### FUNCTION g_mutex_trylock ##### -->
+
<para>
+Tries to lock the #GMutex. If the #GMutex is already locked by another
+thread, it immediately returns FALSE. Otherwise it locks the #GMutex
+and returns TRUE.
+</para>
+<para>
+This function can also be used, if g_thread_init() has not yet been
+called and will immediately return TRUE then.
</para>
-@mutex:
-@Returns:
+@mutex: a #GMutex.
+@Returns: TRUE, if the #GMutex could be locked.
<!-- ##### FUNCTION g_mutex_unlock ##### -->
-<para>
+<para>
+Unlocks the #GMutex. If another thread is blocked in a g_mutex_lock()
+call, it will be woken and can lock the #GMutex itself. This function
+can also be used, if g_thread_init() has not yet been called and will
+do nothing then.
</para>
-@mutex:
+@mutex: a #GMutex.
<!-- ##### FUNCTION g_mutex_free ##### -->
-<para>
+<para>
+Destroys the #GMutex.
</para>
-@mutex:
+@mutex: a #GMutex.
<!-- ##### STRUCT GStaticMutex ##### -->
+
+<para>
+A #GStaticMutex works like a #GMutex, but it has one significant
+advantage. It doesn't need to be created at run-time like a #GMutex,
+but can be defined at compile-time. Here is a shorter, easier and
+safer version of our give_me_next_number() example:
+</para>
+
+<para>
+<example>
+<title>Using GStaticMutex to simplify thread-safe programming</title>
+<programlisting>
+ int give_me_next_number ()
+ {
+ static int current_number = 0;
+ int ret_val;
+ static GStaticMutex mutex = G_STATIC_MUTEX_INIT;
+
+ g_static_mutex_lock (&mutex);
+ ret_val = current_number = calc_next_number (current_number);
+ g_static_mutex_unlock (&mutex);
+ return ret_val;
+ }
+</programlisting>
+</example>
+</para>
+
<para>
+Even though #GStaticMutex is not opaque, it should only be used with
+the following functions, as it is defined differently on different
+platforms.
+</para>
+<para>All of the g_static_mutex_* functions can also be used, if
+g_thread_init() has not yet.
</para>
+<note>
+<para>
+All of the g_static_mutex_* functions are actually macros. Apart from
+taking the addresses of them, you can however use them as if they were
+functions.
+</para>
+</note>
+
<!-- ##### MACRO G_STATIC_MUTEX_INIT ##### -->
+
<para>
+Every #GStaticMutex must be initialized with this macro, before it can
+be used.
+</para>
+<para>
+<example>
+<title>Initializing a GStaticMutext</title>
+<programlisting>
+GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;
+</programlisting>
+</example>
</para>
<!-- ##### FUNCTION g_static_mutex_lock ##### -->
<para>
-
+works like g_mutex_lock(), but for a #GStaticMutex.
</para>
-@mutex:
+@mutex: a #GStaticMutex.
<!-- ##### FUNCTION g_static_mutex_trylock ##### -->
-<para>
+<para>
+works like g_mutex_trylock(), but for a #GStaticMutex.
</para>
-@mutex:
-@Returns:
+@mutex: a #GStaticMutex.
+@Returns: TRUE, if the #GStaticMutex could be locked.
<!-- ##### FUNCTION g_static_mutex_unlock ##### -->
-<para>
+<para>
+works like g_mutex_unlock(), but for a #GStaticMutex.
</para>
-@mutex:
+@mutex: a #GStaticMutex.
<!-- ##### FUNCTION g_static_mutex_get_mutex ##### -->
-<para>
+<para>
+For some operations (like g_cond_wait()) you must have a #GMutex
+instead of a #GStaticMutex. This function will return the
+corresponding #GMutex for every #GStaticMutex.
</para>
-@mutex:
-@Returns:
+@mutex: a #GStaticMutex.
+@Returns: the corresponding #GMutex.
<!-- ##### MACRO G_LOCK_DEFINE ##### -->
+
+<para>
+The G_LOCK_* macros provide a convenient interface to #GStaticMutex
+with the advantage that they will expand to nothing in programs
+compiled against a thread-disabled GLib, saving code and memory
+there. #G_LOCK_DEFINE defines a lock. It can occur, where variable
+definitions may occur in programs, i.e. in the first block of a
+function or outside of functions. The @name parameter will be mangled
+to get the name of the #GStaticMutex. This means, that you can use
+names of existing variables as the parameter, e.g. the name of the
+variable you intent to protect with the lock. Look at our
+give_me_next_number() example using the G_LOCK_* macros:
+</para>
+
<para>
+<example>
+<title>Using the G_LOCK_* convenience macros</title>
+<programlisting>
+G_LOCK_DEFINE (current_number);
+int give_me_next_number ()
+ {
+ static int current_number = 0;
+ int ret_val;
+
+ G_LOCK (current_number);
+ ret_val = current_number = calc_next_number (current_number);
+ G_UNLOCK (current_number);
+ return ret_val;
+ }
+</programlisting>
+</example>
</para>
-@name:
+@name: the name of the lock.
<!-- ##### MACRO G_LOCK_DEFINE_STATIC ##### -->
-<para>
+<para>
+This works like #G_LOCK_DEFINE, but it creates a static object.
</para>
-@name:
+@name: the name of the lock.
<!-- ##### MACRO G_LOCK_EXTERN ##### -->
-<para>
+<para>
+This declares a lock, that is defined with #G_LOCK_DEFINE in another module.
</para>
-@name:
+@name: the name of the lock.
<!-- ##### MACRO G_LOCK ##### -->
-<para>
+<para>
+works like g_mutex_lock(), but for a lock defined with #G_LOCK_DEFINE.
</para>
-@name:
+@name: the name of the lock.
<!-- ##### MACRO G_TRYLOCK ##### -->
-<para>
+<para>
+works like g_mutex_trylock(), but for a lock defined with #G_LOCK_DEFINE.
</para>
-@name:
+@name: the name of the lock.
+@Returns: TRUE, if the lock could be locked.
<!-- ##### MACRO G_UNLOCK ##### -->
-<para>
+<para>
+works like g_mutex_unlock(), but for a lock defined with #G_LOCK_DEFINE.
</para>
-@name:
+@name: the name of the lock.
<!-- ##### STRUCT GStaticRecMutex ##### -->
<!-- ##### STRUCT GCond ##### -->
+
+<para>
+The #GCond struct is an opaque data structure to represent a
+condition. A #GCond is an object, that threads can block on, if they
+find a certain condition to be false. If other threads change the
+state of this condition they can signal the #GCond, such that the
+waiting thread is woken up.
+</para>
+
+<para>
+<example>
+<title>Using GCond to block a thread until a condition is satisfied</title>
+<programlisting>
+GCond* data_cond = NULL; /* Must be initialized somewhere */
+GMutex* data_mutex = NULL; /* Must be initialized somewhere */
+gpointer current_data = NULL;
+
+void push_data (gpointer data)
+{
+ g_mutex_lock (data_mutex);
+ current_data = data;
+ g_cond_signal (data_cond);
+ g_mutex_unlock (data_mutex);
+}
+
+gpointer pop_data ()
+{
+ gpointer data;
+
+ g_mutex_lock (data_mutex);
+ while (!current_data)
+ g_cond_wait (data_cond, data_mutex);
+ data = current_data;
+ current_data = NULL;
+ g_mutex_unlock (data_mutex);
+ return data;
+}
+</programlisting>
+</example>
+</para>
+
+<para>
+Whenever a thread calls pop_data() now, it will wait until
+current_data is non-NULL, i.e. until some other thread has called
+push_data().
+</para>
+
+<note>
<para>
+It is important to use the g_cond_wait() and g_cond_timed_wait()
+functions only inside a loop, which checks for the condition to be
+true as it is not guaranteed that the waiting thread will find it
+fulfilled, even if the signaling thread left the condition
+in that state. This is because another thread can have altered the
+condition, before the waiting thread got the chance to be woken up,
+even if the condition itself is protected by a #GMutex, like above.
+</para>
+</note>
+<para>
+A #GCond should only be accessed via the following functions.
</para>
+<note>
+<para>
+All of the g_cond_* functions are actually macros. Apart from taking
+the addresses of them, you can however use them as if they were functions.
+</para>
+</note>
+
<!-- ##### FUNCTION g_cond_new ##### -->
-<para>
+<para>
+Creates a new #GCond. This function will abort, if g_thread_init()
+has not been called yet.
</para>
-@Returns:
+@Returns: a new #GCond.
<!-- ##### FUNCTION g_cond_signal ##### -->
<para>
+If threads are waiting for @cond, exactly one of them is woken up. It
+is good practice to hold the same lock as the waiting thread, while
+calling this function, though not required.
+</para>
+<para>
+This function can also be used, if g_thread_init() has
+not yet been called and will do nothing then.
</para>
-@cond:
+@cond: a #GCond.
<!-- ##### FUNCTION g_cond_broadcast ##### -->
+
<para>
+If threads are waiting for @cond, all of them are woken up. It is good
+practice to lock the same mutex as the waiting threads, while calling
+this function, though not required.
+</para>
+<para>
+This function can also be used, if g_thread_init() has
+not yet been called and will do nothing then.
</para>
-@cond:
+@cond: a #GCond.
<!-- ##### FUNCTION g_cond_wait ##### -->
+
<para>
+Waits until this thread is woken up on the #GCond. The #GMutex is
+unlocked before falling asleep and locked again before resuming.
+</para>
+<para>
+This function can also be used, if g_thread_init() has not yet been
+called and will immediately return then.
</para>
-@cond:
-@mutex:
+@cond: a #GCond.
+@mutex: the #GMutex, that is currently locked.
<!-- ##### FUNCTION g_cond_timed_wait ##### -->
+
<para>
+Waits until this thread is woken up on the #GCond, but not longer than
+until the time, that is specified by @abs_time. The #GMutex is
+unlocked before falling asleep and locked again before resuming.
+</para>
+<para>
+If @abs_time is NULL, g_cond_timed_wait() acts like g_cond_wait().
</para>
-@cond:
-@mutex:
-@abs_time:
-@Returns:
+<para>
+This function can also be used, if g_thread_init() has not yet been
+called and will immediately return TRUE then.
+</para>
+
+@cond: a #GCond.
+@mutex: the #GMutex, that is currently locked.
+@abs_time: a #GTimeVal, determining the final time.
+@Returns: TRUE, if the thread is woken up in time.
<!-- ##### FUNCTION g_cond_free ##### -->
-<para>
+<para>
+Destroys the #GCond.
</para>
-@cond:
+@cond: a #GCond.
<!-- ##### STRUCT GPrivate ##### -->
<para>
+The #GPrivate struct is an opaque data structure to represent a thread
+private data key. Threads can thereby obtain and set a pointer, which
+is private to the current thread. Take our give_me_next_number()
+example from above. Now we don't want current_number to be shared
+between the threads, but to be private to each thread. This can be
+done as follows:
+
+<example>
+<title>Using GPrivate for per-thread data</title>
+<programlisting>
+ GPrivate* current_number_key = NULL; /* Must be initialized somewhere */
+ /* with g_private_new (g_free); */
+
+ int give_me_next_number ()
+ {
+ int *current_number = g_private_get (current_number_key);
+
+ if (!current_number)
+ {
+ current_number = g_new (int,1);
+ *current_number = 0;
+ g_private_set (current_number_key, current_number);
+ }
+ *current_number = calc_next_number (*current_number);
+ return *current_number;
+ }
+</programlisting>
+</example>
+</para>
+
+<para>
+Here the pointer belonging to the key current_number_key is read. If
+it is NULL, it has not been set yet. Then get memory for an integer
+value, assign this memory to the pointer and write the pointer
+back. Now we have an integer value, that is private to the current
+thread.
+</para>
+
+<para>
+The #GPrivate struct should only be accessed via the following functions.
+</para>
+<note>
+<para>
+All of the g_private_* functions are actually macros. Apart from taking
+the addresses of them, you can however use them as if they were functions.
</para>
+</note>
<!-- ##### FUNCTION g_private_new ##### -->
+
+<para>
+Creates a new #GPrivate. If @destructor is non-NULL, it is a pointer
+to a destructor function. Whenever a thread ends and the corresponding
+pointer keyed to this instance of #GPrivate is non-NULL, the
+destructor is called with this pointer as the argument.
+</para>
+
+<note>
<para>
+The @destructor is working quite differently from @notify in
+g_static_private_set().
+</para>
+</note>
+<note>
+<para>
+A #GPrivate can not be destroyed. Reuse it instead, if you can to
+avoid shortage.
</para>
+</note>
-@destructor:
+<note>
+<para>
+This function will abort, if g_thread_init() has not been called yet.
+</para>
+</note>
+
+@destructor: a function to handle the data keyed to #GPrivate, when a
+thread ends.
@Returns:
<!-- ##### FUNCTION g_private_get ##### -->
+
<para>
+Returns the pointer keyed to @private_key for the current thread. This
+pointer is NULL, when g_private_set() hasn't been called for the
+current @private_key and thread yet.
+</para>
+<para>
+This function can also be used, if g_thread_init() has not yet been
+called and will return the value of @private_key casted to #gpointer then.
</para>
-@private_key:
-@Returns:
+@private_key: a #GPrivate.
+@Returns: the corresponding pointer.
<!-- ##### FUNCTION g_private_set ##### -->
+
<para>
+Sets the pointer keyed to @private_key for the current thread.
+</para>
+<para>
+This function can also be used, if g_thread_init() has not yet been
+called and will set @private_key to @data casted to #GPrivate* then.
</para>
-@private_key:
-@data:
+@private_key: a #GPrivate.
+@data: the new pointer.
+<!-- # Unused Parameters # -->
+@value:
<!-- ##### STRUCT GStaticPrivate ##### -->
+
<para>
+A #GStaticPrivate works almost like a #GPrivate, but it has one
+significant advantage. It doesn't need to be created at run-time like
+a #GPrivate, but can be defined at compile-time. This is similar to
+the difference between #GMutex and #GStaticMutex. Now look at our
+give_me_next_number() example with #GStaticPrivate:
+</para>
+<para>
+<example>
+<title>Using GStaticPrivate for per-thread data</title>
+<programlisting>
+ int give_me_next_number ()
+ {
+ static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT;
+ int *current_number = g_static_private_get (&current_number_key);
+
+ if (!current_number)
+ {
+ current_number = g_new (int,1);
+ *current_number = 0;
+ g_static_private_set (&current_number_key, current_number, g_free);
+ }
+ *current_number = calc_next_number (*current_number);
+ return *current_number;
+ }
+</programlisting>
+</example>
</para>
@index:
<!-- ##### MACRO G_STATIC_PRIVATE_INIT ##### -->
<para>
+Every #GStaticPrivate must be initialized with this macro, before it can
+be used.
+</para>
+<para>
+<informalexample>
+<programlisting>
+GStaticPrivate my_private = G_STATIC_PRIVATE_INIT;
+</programlisting>
+</informalexample>
</para>
<!-- ##### FUNCTION g_static_private_get ##### -->
<para>
+Works like g_private_get() only for a #GStaticPrivate.
+</para>
+<para>
+This function also works, if g_thread_init() has not yet been called.
</para>
-@private_key:
-@Returns:
+@private_key: a #GStaticPrivate.
+@Returns: the corresponding pointer.
<!-- ##### FUNCTION g_static_private_get_for_thread ##### -->
<!-- ##### FUNCTION g_static_private_set ##### -->
<para>
+Sets the pointer keyed to @private_key for the current thread and the
+function @notify to be called with that pointer (NULL or non-NULL),
+whenever the pointer is set again or whenever the current thread ends.
+</para>
+<para>
+This function also works, if g_thread_init() has not yet been
+called. If g_thread_init() is called later, the @data keyed to
+@private_key will be inherited only by the main thread, i.e. the one that
+called g_thread_init().
</para>
-@private_key:
-@data:
-@notify:
+<note>
+<para>
+The @notify is working quite differently from @destructor in
+g_private_new().
+</para>
+</note>
+
+@private_key: a #GStaticPrivate.
+@data: the new pointer.
+@notify: a function to be called with the pointer, whenever the
+current thread ends or sets this pointer again.
<!-- ##### FUNCTION g_static_private_set_for_thread ##### -->
Timers
<!-- ##### SECTION Short_Description ##### -->
-
+functions to time operations.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+Timers can be used to time operations, in a similar way to a stopwatch.
+Call g_timer_new () to create the timer, g_timer_start () to start it,
+g_timer_elapsed () to determine the time which has elapsed since the timer
+was started, and g_timer_stop () to stop the timer.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GTimer ##### -->
<para>
-
+An opaque data structure which holds the timer information.
</para>
<!-- ##### FUNCTION g_timer_new ##### -->
<para>
-
+Creates a new timer.
</para>
-@Returns:
+@Returns: the new timer.
<!-- ##### FUNCTION g_timer_start ##### -->
<para>
-
+Starts the timer.
</para>
-@timer:
+@timer: the timer.
<!-- ##### FUNCTION g_timer_stop ##### -->
<para>
-
+Stops the timer.
</para>
-@timer:
+@timer: the timer.
<!-- ##### FUNCTION g_timer_elapsed ##### -->
</para>
-@timer:
-@microseconds:
-@Returns:
+@timer: the timer.
+@microseconds: if non-NULL, this will be set to the microseconds component
+of the elapsed time (it does not include the number of seconds elapsed).
+@Returns: the elapsed time in seconds, as a double.
<!-- ##### FUNCTION g_timer_reset ##### -->
<para>
-
+Resets the elapsed time to 0, leaving the timer running.
</para>
-@timer:
+@timer: the timer.
<!-- ##### FUNCTION g_timer_destroy ##### -->
<para>
-
+Destroys the timer, freeing the memory allocated for it.
</para>
-@timer:
+@timer: the timer.
Balanced Binary Trees
<!-- ##### SECTION Short_Description ##### -->
-
+a sorted collection of key/value pairs optimised for searching
+and traversing in order.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GTree structure and its associated functions provide a sorted collection
+of key/value pairs optimised for searching and traversing in order.
+</para>
+<para>
+To create a new #GTree use g_tree_new().
+</para>
+<para>
+To insert a key/value pair into a #GTree use g_tree_insert().
+</para>
+<para>
+To lookup the value corresponding to a given key, use g_tree_lookup().
+</para>
+<para>
+To find out the number of nodes in a #GTree, use g_tree_nnodes().
+To get the height of a #GTree, use g_tree_height().
+</para>
+<para>
+To traverse a #GTree, calling a function for each node visited in the
+traversal, use g_tree_traverse().
+</para>
+<para>
+To remove a key/value pair use g_tree_remove().
+</para>
+<para>
+To destroy a #GTree, use g_tree_destroy().
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GTree ##### -->
<para>
-
+The #GTree struct is an opaque data structure representing a
+<link linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>.
+It should be accessed only by using the following functions.
</para>
<!-- ##### FUNCTION g_tree_new ##### -->
<para>
-
+Creates a new GTree.
</para>
-@key_compare_func:
-@Returns:
+@key_compare_func: the function used to order the nodes in the #GTree.
+It should return values similar to the standard <function>strcmp()</function>
+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.
+@Returns: a new #GTree.
<!-- ##### FUNCTION g_tree_insert ##### -->
<para>
-
+Inserts a key/value pair into a #GTree.
+If the given key already exists in the #GTree it is set to the new value.
+(If you are using dynamically allocated keys and values you should be careful
+to ensure that the old values are freed.)
+</para>
+<para>
+The tree is automatically 'balanced' as new key/value pairs are added,
+so that the distance from the root to every leaf is as small as possible.
</para>
-@tree:
-@key:
-@value:
+@tree: a #GTree.
+@key: the key to insert.
+@value: the value corresponding to the key.
<!-- ##### FUNCTION g_tree_nnodes ##### -->
<para>
-
+Gets the number of nodes in a #GTree.
</para>
-@tree:
-@Returns:
+@tree: a #GTree.
+@Returns: the number of nodes in the #GTree.
<!-- ##### FUNCTION g_tree_height ##### -->
<para>
-
+Gets the height of a #GTree.
+</para>
+<para>
+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.
</para>
-@tree:
-@Returns:
+@tree: a #GTree.
+@Returns: the height of the #GTree.
<!-- ##### FUNCTION g_tree_lookup ##### -->
<para>
-
+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.
</para>
-@tree:
-@key:
-@Returns:
+@tree: a #GTree.
+@key: the key to look up.
+@Returns: the value corresponding to the key.
<!-- ##### FUNCTION g_tree_search ##### -->
<para>
-
+Searches a #GTree using an alternative form of the comparison function.
+</para>
+<para>
+This function is not as useful as it sounds.
+It allows you to use a different function for performing the lookup of
+a key. However, since the tree is ordered according to the @key_compare_func
+function passed to g_tree_new(), the function you pass to g_tree_search() must
+return exactly the same value as would be returned by the comparison function,
+for each pair of tree nodes, or the search will not work.
+</para>
+<para>
+To search for a specific value, you can use g_tree_traverse().
</para>
-@tree:
-@search_func:
-@data:
-@Returns:
+@tree: a #GTree.
+@search_func: the comparison function used to search the #GTree.
+@data: the data passed as the second argument to the @search_func function.
+@Returns: the value corresponding to the found key, or NULL if the key is
+not found.
<!-- ##### FUNCTION g_tree_traverse ##### -->
<para>
-
+Calls the given function for each node in the GTree.
</para>
-@tree:
-@traverse_func:
-@traverse_type:
-@data:
+@tree: a #GTree.
+@traverse_func: the function to call for each node visited. If this function
+returns TRUE, the traversal is stopped.
+@traverse_type: the order in which nodes are visited, one of %G_IN_ORDER,
+%G_PRE_ORDER and %G_POST_ORDER.
+@data: user data to pass to the traverse function.
<!-- ##### USER_FUNCTION GTraverseFunc ##### -->
<para>
-
+Specifies the type of function passed to g_tree_traverse().
+It is passed the key and value of each node, together with
+the @user_data parameter passed to g_tree_traverse().
+If the function returns TRUE, the traversal is stopped.
</para>
-@key:
-@value:
-@data:
-@Returns:
+@key: a key of a #GTree node.
+@value: the value corresponding to the key.
+@data: user data passed to g_tree_traverse().
+@Returns: TRUE to stop the traversal.
<!-- ##### ENUM GTraverseType ##### -->
<para>
-
+Specifies the type of traveral performed by g_tree_traverse(),
+g_node_traverse() and g_node_find().
+<itemizedlist>
+<listitem><para>
+%G_PRE_ORDER visits a node, then its children.
+</para></listitem>
+<listitem><para>
+%G_IN_ORDER vists a node's left child first, then the node itself, then its
+right child. This is the one to use if you want the output sorted according
+to the compare function.
+</para></listitem>
+<listitem><para>
+%G_POST_ORDER visits the node's children, then the node itself.
+</para></listitem>
+<listitem><para>
+%G_LEVEL_ORDER is not implemented for
+<link linkend="glib-Balanced-Binary-Trees">Balanced Binary Trees</link>.
+For <link linkend="glib-N-ary-Trees">N-ary Trees</link>
+it calls the function for each child of the node, then it recursively visits
+each child.
+</para></listitem>
+</itemizedlist>
</para>
@G_IN_ORDER:
<!-- ##### FUNCTION g_tree_remove ##### -->
<para>
-
+Removes a key/value pair from a #GTree.
+If the key or value is dynamically allocated you must remember to free them
+yourself.
</para>
-@tree:
-@key:
+@tree: a #GTree.
+@key: the key to remove.
<!-- ##### FUNCTION g_tree_destroy ##### -->
<para>
-
+Destroys the #GTree, freeing all of the memory allocated.
+But it doesn't free keys or values.
</para>
-@tree:
+@tree: a #GTree.
N-ary Trees
<!-- ##### SECTION Short_Description ##### -->
-
+trees of data with any number of branches.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The #GNode struct and its associated functions provide a N-ary tree data
+structure, where nodes in the tree can contain arbitrary data.
+</para>
+<para>
+To create a new tree use g_node_new().
+</para>
+<para>
+To insert a node into a tree use g_node_insert(), g_node_insert_before(),
+g_node_append() and g_node_prepend().
+</para>
+<para>
+To create a new node and insert it into a tree use g_node_insert_data(),
+g_node_insert_data_before(), g_node_append_data() and g_node_prepend_data().
+</para>
+<para>
+To reverse the children of a node use g_node_reverse_children().
+</para>
+<para>
+To find a node use g_node_get_root(), g_node_find(), g_node_find_child(),
+g_node_child_index(), g_node_child_position(),
+g_node_first_child(), g_node_last_child(),
+g_node_nth_child(), g_node_first_sibling(), g_node_prev_sibling(),
+g_node_next_sibling() or g_node_last_sibling().
+</para>
+<para>
+To get information about a node or tree use G_NODE_IS_LEAF(),
+G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(), g_node_n_children(),
+g_node_is_ancestor() or g_node_max_height().
+</para>
+<para>
+To traverse a tree, calling a function for each node visited in the
+traversal, use g_node_traverse() or g_node_children_foreach().
+</para>
+<para>
+To remove a node or subtree from a tree use g_node_unlink() or
+g_node_destroy().
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GNode ##### -->
<para>
-
+The #GNode struct represents one node in a
+<link linkend="glib-N-ary-Trees">N-ary Tree</link>.
+The <structfield>data</structfield> field contains the actual data of the node.
+The <structfield>next</structfield> and <structfield>prev</structfield>
+fields point to the node's siblings (a sibling is another #GNode with the
+same parent).
+The <structfield>parent</structfield> field points to the parent of the #GNode,
+or is NULL if the #GNode is the root of the tree.
+The <structfield>children</structfield> field points to the first child of the
+#GNode. The other children are accessed by using the
+<structfield>next</structfield> pointer of each child.
</para>
@data:
<!-- ##### FUNCTION g_node_new ##### -->
<para>
-
+Creates a new #GNode containing the given data.
+Used to create the first node in a tree.
</para>
-@data:
-@Returns:
+@data: the data of the new node.
+@Returns: a new #GNode.
<!-- ##### FUNCTION g_node_copy ##### -->
<!-- ##### FUNCTION g_node_insert ##### -->
<para>
-
+Inserts a #GNode beneath the parent at the given position.
</para>
-@parent:
-@position:
-@node:
-@Returns:
+@parent: the #GNode to place @node under.
+@position: the position to place @node at, with respect to its siblings.
+If position is -1, @node is inserted as the last child of @parent.
+@node: the #GNode to insert.
+@Returns: the inserted #GNode.
<!-- ##### FUNCTION g_node_insert_before ##### -->
<para>
-
+Inserts a #GNode beneath the parent before the given sibling.
</para>
-@parent:
-@sibling:
-@node:
-@Returns:
+@parent: the #GNode to place @node under.
+@sibling: the sibling #GNode to place @node before. If sibling is NULL,
+the node is inserted as the last child of @parent.
+@node: the #GNode to insert.
+@Returns: the inserted #GNode.
<!-- ##### MACRO g_node_append ##### -->
<para>
-
+Inserts a #GNode as the last child of the given parent.
</para>
-@parent:
-@node:
+@parent: the #GNode to place the new #GNode under.
+@node: the #GNode to insert.
+@Returns: the inserted #GNode.
<!-- ##### FUNCTION g_node_prepend ##### -->
<para>
-
+Inserts a #GNode as the first child of the given parent.
</para>
-@parent:
-@node:
-@Returns:
+@parent: the #GNode to place the new #GNode under.
+@node: the #GNode to insert.
+@Returns: the inserted #GNode.
<!-- ##### MACRO g_node_insert_data ##### -->
<para>
-
+Inserts a new #GNode at the given position.
</para>
-@parent:
-@position:
-@data:
+@parent: the #GNode to place the new #GNode under.
+@position: the position to place the new #GNode at.
+If position is -1, the new #GNode is inserted as the last child of @parent.
+@data: the data for the new #GNode.
+@Returns: the new #GNode.
<!-- ##### MACRO g_node_insert_data_before ##### -->
<para>
-
+Inserts a new #GNode before the given sibling.
</para>
-@parent:
-@sibling:
-@data:
+@parent: the #GNode to place the new #GNode under.
+@sibling: the sibling #GNode to place the new #GNode before.
+@data: the data for the new #GNode.
+@Returns: the new #GNode.
<!-- ##### MACRO g_node_append_data ##### -->
<para>
-
+Inserts a new #GNode as the last child of the given parent.
</para>
-@parent:
-@data:
+@parent: the #GNode to place the new #GNode under.
+@data: the data for the new #GNode.
+@Returns: the new #GNode.
<!-- ##### MACRO g_node_prepend_data ##### -->
<para>
-
+Inserts a new #GNode as the first child of the given parent.
</para>
-@parent:
-@data:
+@parent: the #GNode to place the new #GNode under.
+@data: the data for the new #GNode.
+@Returns: the new #GNode.
<!-- ##### FUNCTION g_node_reverse_children ##### -->
<para>
-
+Reverses the order of the children of a #GNode.
+(It doesn't change the order of the grandchildren.)
</para>
-@node:
+@node: a #GNode.
<!-- ##### FUNCTION g_node_traverse ##### -->
<para>
-
+Traverses a tree starting at the given root #GNode.
+It calls the given function for each node visited.
+The traversal can be halted at any point by returning TRUE from @func.
</para>
-@root:
-@order:
-@flags:
-@max_depth:
-@func:
-@data:
+@root: the root #GNode of the tree to traverse.
+@order: the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER,
+%G_POST_ORDER, or %G_LEVEL_ORDER.
+@flags: which types of children are to be visited, one of %G_TRAVERSE_ALL,
+%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS.
+@max_depth: the maximum depth of the traversal. Nodes below this
+depth will not be visited. If max_depth is -1 all nodes in the tree are
+visited. If depth is 1, only the root is visited. If depth is 2, the root
+and its children are visited. And so on.
+@func: the function to call for each visited #GNode.
+@data: user data to pass to the function.
<!-- ##### ENUM GTraverseFlags ##### -->
<para>
-
+Specifies which nodes are visited during several of the tree functions,
+including g_node_traverse() and g_node_find().
+<itemizedlist>
+<listitem><para>
+%G_TRAVERSE_LEAFS specifies that only leaf nodes should be visited.
+</para></listitem>
+<listitem><para>
+%G_TRAVERSE_NON_LEAFS specifies that only non-leaf nodes should be visited.
+</para></listitem>
+<listitem><para>
+%G_TRAVERSE_ALL specifies that all nodes should be visited.
+</para></listitem>
+</itemizedlist>
</para>
@G_TRAVERSE_LEAFS:
<!-- ##### USER_FUNCTION GNodeTraverseFunc ##### -->
<para>
-
+Specifies the type of function passed to g_node_traverse().
+The function is called with each of the nodes visited, together with the
+user data passed to g_node_traverse().
+If the function returns TRUE, then the traversal is stopped.
</para>
-@node:
-@data:
-@Returns:
+@node: a #GNode.
+@data: user data passed to g_node_traverse().
+@Returns: TRUE to stop the traversal.
<!-- ##### FUNCTION g_node_children_foreach ##### -->
<para>
-
+Calls a function for each of the children of a #GNode.
+Note that it doesn't descend beneath the child nodes.
</para>
-@node:
-@flags:
-@func:
-@data:
+@node: a #GNode.
+@flags: which types of children are to be visited, one of %G_TRAVERSE_ALL,
+%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS.
+@func: the function to call for each visited node.
+@data: user data to pass to the function.
<!-- ##### USER_FUNCTION GNodeForeachFunc ##### -->
<para>
-
+Specifies the type of function passed to g_node_children_foreach().
+The function is called with each child node, together with the user data
+passed to g_node_children_foreach().
</para>
-@node:
-@data:
+@node: a #GNode.
+@data: user data passed to g_node_children_foreach().
<!-- ##### FUNCTION g_node_get_root ##### -->
<para>
-
+Gets the root of a tree.
</para>
-@node:
-@Returns:
+@node: a #GNode.
+@Returns: the root of the tree.
<!-- ##### FUNCTION g_node_find ##### -->
<para>
-
+Finds a #GNode in a tree.
</para>
-@root:
-@order:
-@flags:
-@data:
-@Returns:
+@root: the root #GNode of the tree to search.
+@order: the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER,
+%G_POST_ORDER, or %G_LEVEL_ORDER.
+@flags: which types of children are to be searched, one of %G_TRAVERSE_ALL,
+%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS.
+@data: the data to find.
+@Returns: the found #GNode, or NULL if the data is not found.
<!-- ##### FUNCTION g_node_find_child ##### -->
<para>
-
+Finds the first child of a #GNode with the given data.
</para>
-@node:
-@flags:
-@data:
-@Returns:
+@node: a #GNode.
+@flags: which types of children are to be searched, one of %G_TRAVERSE_ALL,
+%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS.
+@data: the data to find.
+@Returns: the found child #GNode, or NULL if the data is not found.
<!-- ##### FUNCTION g_node_child_index ##### -->
<para>
-
+Gets the position of the first child of a #GNode which contains the given data.
</para>
-@node:
-@data:
-@Returns:
+@node: a #GNode.
+@data: the data to find.
+@Returns: the index of the child of @node which contains @data, or -1
+if the data is not found.
<!-- ##### FUNCTION g_node_child_position ##### -->
<para>
-
+Gets the position of a #GNode with respect to its siblings.
+@child must be a child of @node.
+The first child is numbered 0, the second 1, and so on.
</para>
-@node:
-@child:
-@Returns:
+@node: a #GNode.
+@child: a child of @node.
+@Returns: the position of @child with respect to its siblings.
<!-- ##### MACRO g_node_first_child ##### -->
<para>
-
+Gets the first child of a #GNode.
</para>
-@node:
+@node: a #GNode.
+@Returns: the last child of @node, or NULL if @node is NULL or has no children.
<!-- ##### FUNCTION g_node_last_child ##### -->
<para>
-
+Gets the last child of a #GNode.
</para>
-@node:
-@Returns:
+@node: a #GNode (must not be NULL).
+@Returns: the last child of @node, or NULL if @node has no children.
<!-- ##### FUNCTION g_node_nth_child ##### -->
<para>
-
+Gets a child of a #GNode, using the given index.
+The first child is at index 0. If the index is too big, NULL is returned.
</para>
-@node:
-@n:
-@Returns:
+@node: a #GNode.
+@n: the index of the desired child.
+@Returns: the child of @node at index @n.
<!-- ##### FUNCTION g_node_first_sibling ##### -->
<para>
-
+Gets the first sibling of a #GNode.
+This could possibly be the node itself.
</para>
-@node:
-@Returns:
+@node: a #GNode.
+@Returns: the first sibling of @node.
<!-- ##### MACRO g_node_next_sibling ##### -->
<para>
-
+Gets the next sibling of a #GNode.
</para>
-@node:
+@node: a #GNode.
+@Returns: the next sibling of @node, or NULL if @node is NULL.
<!-- ##### MACRO g_node_prev_sibling ##### -->
<para>
-
+Gets the previous sibling of a #GNode.
</para>
-@node:
+@node: a #GNode.
+@Returns: the previous sibling of @node, or NULL if @node is NULL.
<!-- ##### FUNCTION g_node_last_sibling ##### -->
<para>
-
+Gets the last sibling of a #GNode.
+This could possibly be the node itself.
</para>
-@node:
-@Returns:
+@node: a #GNode.
+@Returns: the last sibling of @node.
<!-- ##### MACRO G_NODE_IS_LEAF ##### -->
<para>
-
+Returns TRUE if a #GNode is a leaf node.
</para>
-@node:
+@node: a #GNode.
+@Returns: TRUE if the #GNode is a leaf node (i.e. it has no children).
<!-- ##### MACRO G_NODE_IS_ROOT ##### -->
<para>
-
+Returns TRUE if a #GNode is the root of a tree.
</para>
-@node:
+@node: a #GNode.
+@Returns: TRUE if the #GNode is the root of a tree (i.e. it has no parent
+or siblings).
<!-- ##### FUNCTION g_node_depth ##### -->
<para>
-
+Gets the depth of a #GNode.
+</para>
+<para>
+If @node is NULL the depth is 0.
+The root node has a depth of 1.
+For the children of the root node the depth is 2. And so on.
</para>
-@node:
-@Returns:
+@node: a #GNode.
+@Returns: the depth of the #GNode.
<!-- ##### FUNCTION g_node_n_nodes ##### -->
<para>
-
+Gets the number of nodes in a tree.
</para>
-@root:
-@flags:
-@Returns:
+@root: a #GNode.
+@flags: which types of children are to be counted, one of %G_TRAVERSE_ALL,
+%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS.
+@Returns: the number of nodes in the tree.
<!-- ##### FUNCTION g_node_n_children ##### -->
<para>
-
+Gets the number of children of a #GNode.
</para>
-@node:
-@Returns:
+@node: a #GNode.
+@Returns: the number of children of @node.
<!-- ##### FUNCTION g_node_is_ancestor ##### -->
<para>
-
+Returns TRUE if @node is an ancestor of @descendant.
+This is true if node is the parent of descendant, or if node is the
+grandparent of descendant etc.
</para>
-@node:
-@descendant:
-@Returns:
+@node: a #GNode.
+@descendant: a #GNode.
+@Returns: TRUE if @node is an ancestor of @descendant.
<!-- ##### FUNCTION g_node_max_height ##### -->
<para>
-
+Gets the maximum height of all branches beneath a #GNode.
+This is the maximum distance from the #GNode to all leaf nodes.
+</para>
+<para>
+If @root is NULL, 0 is returned. If @root has no children, 1 is returned.
+If @root has children, 2 is returned. And so on.
</para>
-@root:
-@Returns:
+@root: a #GNode.
+@Returns: the maximum height of the tree beneath @root.
<!-- ##### FUNCTION g_node_unlink ##### -->
<para>
-
+Unlinks a #GNode from a tree, resulting in two separate trees.
</para>
-@node:
+@node: the #GNode to unlink, which becomes the root of a new tree.
<!-- ##### FUNCTION g_node_destroy ##### -->
<para>
-
+Removes the #GNode and its children from the tree, freeing any memory
+allocated.
</para>
-@root:
+@root: the root of the tree/subtree to destroy.
<!-- ##### FUNCTION g_node_push_allocator ##### -->
<para>
-
+Sets the allocator to use to allocate #GNode elements.
+Use g_node_pop_allocator() to restore the previous allocator.
</para>
-@allocator:
+@allocator: the #GAllocator to use when allocating #GNode elements.
<!-- ##### FUNCTION g_node_pop_allocator ##### -->
<para>
-
+Restores the previous #GAllocator, used when allocating #GNode elements.
</para>
Type Conversion Macros
<!-- ##### SECTION Short_Description ##### -->
-
+a portable method for storing #gint & #guint values in #gpointer variables.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+These macros provide a portable method of storing #gint and #guint values in
+#gpointer variables.
+</para>
+<para>
+Many of the GLib data types are based on storing #gpointer values,
+e.g. #GHashTable, #GList, #GSList, #GTree, and #GNode.
+By using the type conversion macros described below you can store #gint and
+#guint values inside a #gpointer. So you can, for example, create
+a hash table of #gint values, or a linked list of #guint values.
+</para>
+<para>
+The type conversion macros are necessary because the size of a #gpointer can
+vary across different platforms. So the type conversion has to be done
+carefully.
+</para>
+<para>
+Note that the reverse operation, storing #gpointer values in
+integer variables, is not supported, since an integer is not guaranteed to
+be large enough to store #gpointer values across all platforms.
+</para>
+<para>
+To convert an integer value, a #gint, to a #gpointer, use #GINT_TO_POINTER.
+To convert it back to a #gint, use #GPOINTER_TO_INT.
+</para>
+<para>
+To convert an unsigned integer, a #guint, to a #gpointer, use
+#GUINT_TO_POINTER. To convert it back to a #guint, use #GPOINTER_TO_UINT.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### MACRO GINT_TO_POINTER ##### -->
<para>
-
+Converts a #gint to a #gpointer.
</para>
-@i:
+@i: a #gint value.
+@Returns: the value converted to a #gpointer.
<!-- ##### MACRO GPOINTER_TO_INT ##### -->
<para>
-
+Converts a #gpointer to a #gint.
</para>
-@p:
+@p: a #gpointer value.
+@Returns: the value converted to a #gint.
<!-- ##### MACRO GUINT_TO_POINTER ##### -->
<para>
-
+Converts a #guint to a #gpointer.
</para>
-@u:
+@u: a #guint value.
+@Returns: the value converted to a #gpointer.
<!-- ##### MACRO GPOINTER_TO_UINT ##### -->
<para>
-
+Converts a #gpointer to a #guint.
</para>
-@p:
+@p: a #gpointer value.
+@Returns: the value converted to a #guint.
Basic Types
<!-- ##### SECTION Short_Description ##### -->
-
+standard GLib types, defined for ease-of-use and portability.
<!-- ##### SECTION Long_Description ##### -->
<para>
+GLib defines a number of commonly used types, which can be divided into
+4 groups:
+
+<itemizedlist>
+<listitem><para>
+New types which are not part of standard C - #gboolean, #gsize, #gssize.
+</para></listitem>
+
+<listitem><para>
+Integer types which are guaranteed to be the same size across all platforms -
+#gint8, #guint8, #gint16, #guint16, #gint32, #guint32, #gint64, #guint64.
+</para></listitem>
+
+<listitem><para>
+Types which are easier to use than their standard C counterparts -
+#gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong.
+</para></listitem>
+
+<listitem><para>
+Types which correspond exactly to standard C types, but are included
+for completeness - #gchar, #gint, #gshort, #glong, #gfloat, #gdouble.
+</para></listitem>
+</itemizedlist>
</para>
<!-- ##### TYPEDEF gboolean ##### -->
<para>
-
+A standard <type>boolean</type> type.
+Variables of this type should only contain the value #TRUE or #FALSE.
</para>
<!-- ##### TYPEDEF gpointer ##### -->
<para>
-
+An untyped pointer.
+#gpointer looks better and is easier to use than <type>void*</type>.
</para>
<!-- ##### TYPEDEF gconstpointer ##### -->
<para>
-
+An untyped pointer to constant data.
+The data pointed to should not be changed.
+</para>
+<para>
+This is typically used in function prototypes to indicate that the
+data pointed to will not be altered by the function.
</para>
<!-- ##### TYPEDEF gchar ##### -->
<para>
-
+Corresponds to the standard C <type>char</type> type.
</para>
<!-- ##### TYPEDEF guchar ##### -->
<para>
-
+Corresponds to the standard C <type>unsigned char</type> type.
</para>
<!-- ##### TYPEDEF gint ##### -->
<para>
-
+Corresponds to the standard C <type>int</type> type.
+Values of this type can range from #G_MININT to #G_MAXINT.
</para>
<!-- ##### TYPEDEF guint ##### -->
<para>
-
+Corresponds to the standard C <type>unsigned int</type> type.
</para>
<!-- ##### TYPEDEF gshort ##### -->
<para>
-
+Corresponds to the standard C <type>short</type> type.
+Values of this type can range from #G_MINSHORT to #G_MAXSHORT.
</para>
<!-- ##### TYPEDEF gushort ##### -->
<para>
-
+Corresponds to the standard C <type>unsigned short</type> type.
</para>
<!-- ##### TYPEDEF glong ##### -->
<para>
-
+Corresponds to the standard C <type>long</type> type.
+Values of this type can range from #G_MINLONG to #G_MAXLONG.
</para>
<!-- ##### TYPEDEF gulong ##### -->
<para>
-
+Corresponds to the standard C <type>unsigned long</type> type.
</para>
<!-- ##### TYPEDEF gint8 ##### -->
<para>
-
+A signed integer guaranteed to be 8 bits on all platforms.
+Values of this type can range from -128 to 127.
</para>
<!-- ##### TYPEDEF guint8 ##### -->
<para>
-
+An unsigned integer guaranteed to be 8 bits on all platforms.
+Values of this type can range from 0 to 255.
</para>
<!-- ##### TYPEDEF gint16 ##### -->
<para>
-
+A signed integer guaranteed to be 16 bits on all platforms.
+Values of this type can range from -32,768 to 32,767.
</para>
<!-- ##### TYPEDEF guint16 ##### -->
<para>
-
+An unsigned integer guaranteed to be 16 bits on all platforms.
+Values of this type can range from 0 to 65,535.
</para>
<!-- ##### TYPEDEF gint32 ##### -->
<para>
-
+A signed integer guaranteed to be 32 bits on all platforms.
+Values of this type can range from -2,147,483,648 to 2,147,483,647.
</para>
<!-- ##### TYPEDEF guint32 ##### -->
<para>
-
+An unsigned integer guaranteed to be 32 bits on all platforms.
+Values of this type can range from 0 to 4,294,967,295.
</para>
<!-- ##### MACRO G_HAVE_GINT64 ##### -->
<para>
-
+This macro is defined if 64-bit signed and unsigned integers are available
+on the platform.
</para>
<!-- ##### TYPEDEF gint64 ##### -->
<para>
-
+A signed integer guaranteed to be 64 bits on all platforms on which it is
+available (see #G_HAVE_GINT64).
+Values of this type can range from -9,223,372,036,854,775,808 to
+9,223,372,036,854,775,807.
</para>
<!-- ##### TYPEDEF guint64 ##### -->
<para>
-
+An unsigned integer guaranteed to be 64 bits on all platforms on which it is
+available (see #G_HAVE_GINT64).
+Values of this type can range from 0 to 18,446,744,073,709,551,615.
</para>
<!-- ##### MACRO G_GINT64_CONSTANT ##### -->
<para>
-
+This macro is used to insert 64-bit integer literals into the source code.
</para>
-@val:
+@val: a literal integer value, e.g. 0x1d636b02300a7aa7U.
<!-- ##### TYPEDEF gfloat ##### -->
<para>
-
+Corresponds to the standard C <type>float</type> type.
+Values of this type can range from #G_MINFLOAT to #G_MAXFLOAT.
</para>
<!-- ##### TYPEDEF gdouble ##### -->
<para>
-
+Corresponds to the standard C <type>double</type> type.
+Values of this type can range from #G_MINDOUBLE to #G_MAXDOUBLE.
</para>
<!-- ##### TYPEDEF gsize ##### -->
<para>
-
+An unsigned 32-bit integer intended to represent sizes of data structures.
</para>
<!-- ##### TYPEDEF gssize ##### -->
<para>
-
+A signed 32-bit integer intended to represent sizes of data structures.
</para>
<!-- ##### SECTION Title ##### -->
-Warnings and Assertions
+Message Output and Debugging Functions
<!-- ##### SECTION Short_Description ##### -->
-
+functions to output messages and help debug applications.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+These functions provide support for outputting messages.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### FUNCTION g_print ##### -->
<para>
-
+Outputs a formatted message via the print handler.
+The default print handler simply outputs the message to stdout.
+</para>
+<para>
+g_print() should not be used from within libraries for debugging messages,
+since it may be redirected by applications to special purpose message
+windows or even files.
+Instead, libraries should use g_log(), or the convenience functions
+g_message(), g_warning() and g_error().
</para>
-@format:
-@Varargs:
+@format: the message format. See the <function>printf()</function>
+documentation.
+@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_set_print_handler ##### -->
<para>
-
+Sets the print handler.
+Any messages passed to g_print() will be output via the new handler.
+The default handler simply outputs the message to stdout.
+By providing your own handler you can redirect the output, to a GTK
+widget or a log file for example.
</para>
-@func:
-@Returns:
+@func: the new print handler.
+@Returns: the old print handler.
<!-- ##### USER_FUNCTION GPrintFunc ##### -->
<para>
-
+Specifies the type of the print handler functions.
+These are called with the complete formatted string to output.
</para>
-@string:
+@string: the message to be output.
<!-- ##### FUNCTION g_printerr ##### -->
<para>
-
+Outputs a formatted message via the error message handler.
+The default handler simply outputs the message to stderr.
+</para>
+<para>
+g_printerr() should not be used from within libraries. Instead g_log() should
+be used, or the convenience functions g_message(), g_warning() and g_error().
</para>
-@format:
-@Varargs:
+@format: the message format. See the <function>printf()</function>
+documentation.
+@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_set_printerr_handler ##### -->
<para>
-
+Sets the handler for printing error messages.
+Any messages passed to g_printerr() will be output via the new handler.
+The default handler simply outputs the message to stderr.
+By providing your own handler you can redirect the output, to a GTK
+widget or a log file for example.
</para>
-@func:
-@Returns:
+@func: the new error message handler.
+@Returns: the old error message handler.
<!-- ##### MACRO g_return_if_fail ##### -->
<para>
-
+Returns from the current function if the expression is not true.
+If the expression evaluates to FALSE, a critical message is logged and
+the function returns. This can only be used in functions which do not return
+a value.
</para>
-@expr:
+@expr: the expression to check.
<!-- ##### MACRO g_return_val_if_fail ##### -->
<para>
-
+Returns from the current function, returning the value @val, if the expression
+is not true.
+If the expression evaluates to FALSE, a critical message is logged and
+@val is returned.
</para>
-@expr:
-@val:
+@expr: the expression to check.
+@val: the value to return from the current function if the expression is not
+true.
<!-- ##### MACRO g_return_if_reached ##### -->
<!-- ##### MACRO g_assert ##### -->
<para>
-
+Debugging macro to terminate the application if the assertion fails.
+If the assertion fails (i.e. the expression is not true), an error message
+is logged and the application is terminated.
+</para>
+<para>
+The macro can be turned off in final releases of code by defining
+G_DISABLE_ASSERT when compiling the application.
</para>
-@expr:
+@expr: the expression to check.
<!-- ##### MACRO g_assert_not_reached ##### -->
<para>
-
+Debugging macro to terminate the application if it is ever reached.
+If it is reached, an error message is logged and the application is terminated.
+</para>
+<para>
+The macro can be turned off in final releases of code by defining
+G_DISABLE_ASSERT when compiling the application.
</para>
<!-- ##### FUNCTION g_on_error_query ##### -->
<para>
-
+Prompts the user with "[E]xit, [H]alt, show [S]tack trace or [P]roceed".
+This function is intended to be used for debugging use only.
+FIXME: How do you set it up?
+</para>
+<para>
+If Exit is selected, the application terminates with a call to
+<function>_exit(0)</function>.
+</para>
+<para>
+If Halt is selected, the application enters an infinite loop.
+The infinite loop can only be stopped by killing the application,
+or by setting glib_on_error_halt to FALSE (possibly via a debugger).
+</para>
+<para>
+If Stack trace is selected, g_on_error_stack_trace() is called. This
+invokes gdb, which attaches to the current process and shows a stack trace.
+The prompt is then shown again.
+</para>
+<para>
+If Proceed is selected, the function returns.
+</para>
+<para>
+This function may cause different actions on non-unix platforms.
</para>
-@prg_name:
+@prg_name: the program name, needed by gdb for the [S]tack trace option.
+If @prg_name is NULL, g_get_prgname() is called to get the program name
+(which will work correctly if gdk_init() or gtk_init() has been called).
<!-- ##### FUNCTION g_on_error_stack_trace ##### -->
<para>
-
+Invokes gdb, which attaches to the current process and shows a stack trace.
+Called by g_on_error_query() when the [S]tack trace option is selected.
+</para>
+<para>
+This function may cause different actions on non-unix platforms.
</para>
-@prg_name:
+@prg_name: the program name, needed by gdb for the [S]tack trace option.
+If @prg_name is NULL, g_get_prgname() is called to get the program name
+(which will work correctly if gdk_init() or gtk_init() has been called).
<!-- ##### MACRO G_BREAKPOINT ##### -->
<para>
-
+Inserts a breakpoint instruction into the code (on x86 machines only).
</para>
Windows Compatability Functions
<!-- ##### SECTION Short_Description ##### -->
-
+functions to support portability to the Windows environment.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+These functions and macros are provided in the GLib library when compiled
+on the Windows platform.
+</para>
+<para>
+Many of the macros simply rename available windows functions
+so that they use the same name as the standard Unix functions.
+This means that code written for the Unix platform will work without change
+under Windows.
+</para>
+<para>
+A few additional constants, types, and functions are also provided,
+to provide a common base set of functions across both the Unix and Windows
+environments.
</para>
<!-- ##### SECTION See_Also ##### -->
# The directory containing the source code (if it contains documentation).
DOC_SOURCE_DIR=$(top_srcdir)/gobject
+# Extra options to supply to gtkdoc-fixref
+FIXXREF_OPTIONS=--extra-dir=$(srcdir)/../glib/html
+
# Headers to ignore
IGNORE_HFILES=
scan:
-(cd $(srcdir) \
- && gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" )
+ && gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)")
templates:
cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE)
test -d $(srcdir)/html || mkdir $(srcdir)/html
-cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
@echo '-- Fixing Crossreferences'
- gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR)
+ gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)
clean-local:
rm -f *~ *.bak *.signals *-unused.txt
projects / platform / upstream / glib.git / commitdiff