+2001-12-12 Matthias Clasen <matthiasc@poet.de>
+
+ * glib/gconvert.c, glib/grand.c, glib/ghash.c,
+ glib/gthreadpool.c, glib/gtree.c: Documentation fixes.
+
Mon Dec 10 14:08:39 2001 HideToshi Tajima <hidetoshi.tajima@sun.com>
* glib/libcharset/config.charset (os):
+2001-12-12 Matthias Clasen <matthiasc@poet.de>
+
+ * glib/gconvert.c, glib/grand.c, glib/ghash.c,
+ glib/gthreadpool.c, glib/gtree.c: Documentation fixes.
+
Mon Dec 10 14:08:39 2001 HideToshi Tajima <hidetoshi.tajima@sun.com>
* glib/libcharset/config.charset (os):
+2001-12-12 Matthias Clasen <matthiasc@poet.de>
+
+ * glib/gconvert.c, glib/grand.c, glib/ghash.c,
+ glib/gthreadpool.c, glib/gtree.c: Documentation fixes.
+
Mon Dec 10 14:08:39 2001 HideToshi Tajima <hidetoshi.tajima@sun.com>
* glib/libcharset/config.charset (os):
+2001-12-12 Matthias Clasen <matthiasc@poet.de>
+
+ * glib/gconvert.c, glib/grand.c, glib/ghash.c,
+ glib/gthreadpool.c, glib/gtree.c: Documentation fixes.
+
Mon Dec 10 14:08:39 2001 HideToshi Tajima <hidetoshi.tajima@sun.com>
* glib/libcharset/config.charset (os):
+2001-12-12 Matthias Clasen <matthiasc@poet.de>
+
+ * glib/gconvert.c, glib/grand.c, glib/ghash.c,
+ glib/gthreadpool.c, glib/gtree.c: Documentation fixes.
+
Mon Dec 10 14:08:39 2001 HideToshi Tajima <hidetoshi.tajima@sun.com>
* glib/libcharset/config.charset (os):
+2001-12-12 Matthias Clasen <matthiasc@poet.de>
+
+ * glib/gconvert.c, glib/grand.c, glib/ghash.c,
+ glib/gthreadpool.c, glib/gtree.c: Documentation fixes.
+
Mon Dec 10 14:08:39 2001 HideToshi Tajima <hidetoshi.tajima@sun.com>
* glib/libcharset/config.charset (os):
+2001-12-12 Matthias Clasen <matthiasc@poet.de>
+
+ * glib/gconvert.c, glib/grand.c, glib/ghash.c,
+ glib/gthreadpool.c, glib/gtree.c: Documentation fixes.
+
Mon Dec 10 14:08:39 2001 HideToshi Tajima <hidetoshi.tajima@sun.com>
* glib/libcharset/config.charset (os):
+2001-12-12 Matthias Clasen <matthiasc@poet.de>
+
+ * glib/gconvert.c, glib/grand.c, glib/ghash.c,
+ glib/gthreadpool.c, glib/gtree.c: Documentation fixes.
+
Mon Dec 10 14:08:39 2001 HideToshi Tajima <hidetoshi.tajima@sun.com>
* glib/libcharset/config.charset (os):
+2001-12-12 Matthias Clasen <matthiasc@poet.de>
+
+ * glib/tmpl/allocators.sgml, glib/tmpl/arrays.sgml,
+ glib/tmpl/arrays_byte.sgml, glib/tmpl/arrays_pointer.sgml,
+ glib/tmpl/caches.sgml, glib/tmpl/completion.sgml,
+ glib/tmpl/conversions.sgml,
+ glib/tmpl/datalist.sgml, glib/tmpl/date.sgml,
+ glib/tmpl/error_reporting.sgml, glib/tmpl/fileutils.sgml,
+ glib/tmpl/hash_tables.sgml,
+ glib/tmpl/hooks.sgml, glib/tmpl/macros.sgml,
+ glib/tmpl/macros_misc.sgml, glib/tmpl/main.sgml, glib/tmpl/markup.sgml,
+ glib/tmpl/memory.sgml, glib/tmpl/memory_chunks.sgml,
+ glib/tmpl/messages.sgml, glib/tmpl/misc_utils.sgml,
+ glib/tmpl/modules.sgml, glib/tmpl/numerical.sgml,
+ glib/tmpl/patterns.sgml, glib/tmpl/queue.sgml,
+ glib/tmpl/shell.sgml, glib/tmpl/spawn.sgml,
+ glib/tmpl/string_utils.sgml, glib/tmpl/thread_pools.sgml,
+ glib/tmpl/threads.sgml, glib/tmpl/timers.sgml,
+ glib/tmpl/trees-binary.sgml, glib/tmpl/trees-nary.sgml,
+ glib/tmpl/type_conversion.sgml, glib/tmpl/unicode.sgml,
+ glib/tmpl/warnings.sgml, glib/tmpl/windows.sgml:
+ Improve markup of examples, general consistency improvements.
+
2001-12-06 Havoc Pennington <hp@redhat.com>
* glib/tmpl/messages.sgml: improve g_log_set_handler docs
<!-- ##### STRUCT GAllocator ##### -->
<para>
-The #GAllocator struct contains private data. and should only be accessed
+The <structname>GAllocator</structname> struct contains private data. and should only be accessed
using the following functions.
</para>
To free an array, use g_array_free().
</para>
<example>
-<title>Using a GArray to store gint values.</title>
+<title>Using a <structname>GArray</structname> to store gint values.</title>
<programlisting>
GArray *garray;
gint i;
The return value is cast to the given type.
<example>
-<title>Getting a pointer to an element in a GArray.</title>
+<title>Getting a pointer to an element in a <structname>GArray</structname>.</title>
<programlisting>
EDayViewEvent *event;
<!-- ##### SECTION Long_Description ##### -->
<para>
-GByteArray is based on #GArray, to provide arrays of bytes which grow
+#GByteArray is based on #GArray, to provide arrays of bytes which grow
automatically as elements are added.
</para>
<para>
g_byte_array_prepend().
</para>
<para>
-To set the size of a GByteArray, use g_byte_array_set_size().
+To set the size of a #GByteArray, use g_byte_array_set_size().
</para>
<para>
-To free a GByteArray, use g_byte_array_free().
+To free a #GByteArray, use g_byte_array_free().
</para>
<example>
-<title>Using a GByteArray.</title>
+<title>Using a <structname>GByteArray</structname>.</title>
<programlisting>
GByteArray *gbarray;
gint i;
- gbarray = g_byte_array_new ();
+ gbarray = g_byte_array_new (<!>);
for (i = 0; i < 10000; i++)
g_byte_array_append (gbarray, (guint8*) "abcd", 4);
<!-- ##### STRUCT GByteArray ##### -->
<para>
-The #GByteArray struct allows access to the public fields of a #GByteArray.
+The <structname>GByteArray</structname> struct allows access to the public fields of a <structname>GByteArray</structname>.
</para>
@data: a pointer to the element data. The data may be moved as elements are
<!-- ##### FUNCTION g_byte_array_free ##### -->
<para>
Frees the memory allocated by the #GByteArray.
-If free_segment is %TRUE it frees the actual byte data.
+If @free_segment is %TRUE it frees the actual byte data.
</para>
@array: a #GByteArray.
To free a pointer array, use g_ptr_array_free().
</para>
<example>
-<title>Using a GPtrArray.</title>
+<title>Using a <structname>GPtrArray</structname>.</title>
<programlisting>
GPtrArray *gparray;
gchar *string1 = "one", *string2 = "two", *string3 = "three";
- gparray = g_ptr_array_new ();
+ 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);
<!-- ##### 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:
-@len:
+@pdata: points to the array of pointers, which may be moved when the array grows.
+@len: number of pointers in the array.
<!-- ##### FUNCTION g_ptr_array_new ##### -->
<para>
system resources.
</para>
<para>
-GTK+ uses a #GCache for both GtkStyles and GdkGCs. These consume a lot of
-resources, so a #GCache is used to see if a GtkStyle or GdkGC with the
+GTK+ uses a #GCache for #GtkStyles; GDK uses one for #GdkGCs. These consume a lot of
+resources, 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.
+object is used instead of creating a new one.
</para>
<para>
#GCache uses keys and values.
<!-- ##### 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.
+a #GCache. It should only be accessed via the following functions.
</para>
<!-- ##### 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:
-@func:
-@prefix:
-@cache:
+@items: list of target items (strings or data structures).
+@func: function which is called to get the string associated with a target
+ item. It is %NULL if the target items are strings.
+@prefix: the last prefix passed to g_completion_complete().
+@cache: the list of items which begin with @prefix.
@strncmp_func:
<!-- ##### FUNCTION g_completion_new ##### -->
Character Set Conversion
<!-- ##### SECTION Short_Description ##### -->
-convert strings between different character sets using <function>iconv()</function>
+convert strings between different character sets using <function>iconv()</function>.
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<para>
Data lists are used in GTK+ for associating arbitrary data with
-GtkObjects, using gtk_object_set_data() and related functions.
+#GtkObjects, using gtk_object_set_data() and related functions.
</para>
<para>
<para>
The #GDate implementation has several nice features; it is only a
64-bit struct, so storing large numbers of dates is very efficient. It
-can keep both a Julian and Day-Month-Year representation of the date,
+can keep both a Julian and day-month-year representation of the date,
since some calculations are much easier with one representation or the
other. A Julian representation is simply a count of days since some
fixed day in the past; for #GDate the fixed day is January 1, 1 AD.
<para>
<emphasis>It is very important to use the API to access the #GDate
-struct.</emphasis> Often only the DMY or only the Julian
+struct.</emphasis> Often only the day-month-year or only the Julian
representation is valid. Sometimes neither is valid. Use the API.
</para>
<para>
Represents a precise time, with seconds and microseconds. Same as the
<structname>struct timeval</structname> returned by the
-<function>gettimeofday()</function> UNIX call.
+<function>gettimeofday()</function> Unix call.
</para>
@tv_sec: seconds.
<!-- ##### FUNCTION g_date_new_dmy ##### -->
<para>
Like g_date_new(), but also sets the value of the date. Assuming the
-day/month/year triplet you pass in represents an existing day, the
+day-month-year triplet you pass in represents an existing day, the
returned date will be valid.
</para>
<!-- ##### FUNCTION g_date_valid_dmy ##### -->
<para>
-Returns %TRUE if the day/month/year triplet forms a valid, existing day
+Returns %TRUE if the day-month-year triplet forms a valid, existing day
in the range of days #GDate understands (Year 1 or later, no more than
a few thousand years in the future).
</para>
Error Reporting
<!-- ##### SECTION Short_Description ##### -->
-
-System for reporting errors
+a system for reporting errors.
<!-- ##### SECTION Long_Description ##### -->
GLib provides a standard method of reporting errors from a called function to
the calling code. (This is the same problem solved by exceptions in other
languages.) It's important to understand that this method is both a
-<emphasis>data type </emphasis> (the #GError object) and a <emphasis>set of
-rules</emphasis>. If you use #GError incorrectly, then your code will not
+<emphasis>data type</emphasis> (the #GError object) and a <emphasis>set of
+rules.</emphasis> If you use #GError incorrectly, then your code will not
properly interoperate with other code that uses #GError, and users of your API
will probably get confused.
</para>
<para>
First and foremost: <emphasis>#GError should only be used to report
-recoverable runtime errors, never to report programming errors</emphasis>. If
+recoverable runtime errors, never to report programming errors.</emphasis> If
the programmer has screwed up, then you should use g_warning(),
g_return_if_fail(), g_assert(), g_error(), or some similar facility.
(Incidentally, remember that the g_error() function should
<para>
Functions that can fail take a return location for a #GError as their last argument.
For example:
-<programlisting>
+<informalexample><programlisting>
gchar* g_file_get_contents (const gchar *filename, GError **error);
-</programlisting>
+</programlisting></informalexample>
If you pass a non-%NULL value for the <literal>error</literal> argument, it should
point to a location where an error can be placed. For example:
-<programlisting>
+<informalexample><programlisting>
gchar *contents;
GError *err = NULL;
contents = g_file_get_contents ("foo.txt", &err);
/* Use file contents */
g_assert (contents != NULL);
}
-</programlisting>
+</programlisting></informalexample>
Note that <literal>err != NULL</literal> in this example is a
<emphasis>reliable</emphasis> indicator of whether
g_file_get_contents() failed. Also, g_file_get_contents() uses the
Because g_file_get_contents() returns %NULL on failure, if you are only
interested in whether it failed and don't need to display an error message, you
can pass %NULL for the <literal>error</literal> argument:
-<programlisting>
+<informalexample><programlisting>
contents = g_file_get_contents ("foo.txt", NULL); /* ignore errors */
if (contents != NULL)
/* no error occurred */ ;
else
/* error */ ;
-</programlisting>
+</programlisting></informalexample>
</para>
<para>
g_set_error(). Typically, if a fatal error occurs you want to g_set_error(),
then return immediately. g_set_error() does nothing if the error location passed
to it is %NULL. Here's an example:
-<programlisting>
+<informalexample><programlisting>
gint
foo_open_file (GError **error)
{
else
return fd;
}
-</programlisting>
+</programlisting></informalexample>
</para>
<para>
can report a #GError. If the sub-function indicates fatal errors in some way
other than reporting a #GError, such as by returning %TRUE on success, you can
simply do the following:
-<programlisting>
+<informalexample><programlisting>
gboolean
my_function_that_can_fail (GError **err)
{
/* otherwise continue, no error occurred */
g_assert (err == NULL || *err == NULL);
}
-</programlisting>
+</programlisting></informalexample>
</para>
<para>
If the sub-function does not indicate errors other than by reporting a #GError,
you need to create a temporary #GError since the passed-in one may be %NULL.
g_propagate_error() is intended for use in this case.
-<programlisting>
+<informalexample><programlisting>
gboolean
my_function_that_can_fail (GError **err)
{
if (tmp_error != NULL)
{
/* store tmp_error in err, if err != NULL,
- * otherwise call g_error_free() on tmp_error
+ * otherwise call g_error_free(<!>) on tmp_error
*/
g_propagate_error (err, tmp_error);
return FALSE;
/* otherwise continue, no error occurred */
}
-</programlisting>
+</programlisting></informalexample>
</para>
<para>
Error pileups are always a bug. For example, this code is incorrect:
-<programlisting>
+<informalexample><programlisting>
gboolean
my_function_that_can_fail (GError **err)
{
return FALSE;
}
}
-</programlisting>
+</programlisting></informalexample>
<literal>tmp_error</literal> should be checked immediately after
<function>sub_function_that_can_fail()</function>, and either cleared or propagated upward. The rule
is: <emphasis>after each error, you must either handle the error, or return it to the
equivalent of handling an error by always doing nothing about it. So the
following code is fine, assuming errors in <function>sub_function_that_can_fail()</function> are not
fatal to <function>my_function_that_can_fail()</function>:
-<programlisting>
+<informalexample><programlisting>
gboolean
my_function_that_can_fail (GError **err)
{
return FALSE;
}
}
-</programlisting>
+</programlisting></informalexample>
</para>
<para>
<!-- ##### ENUM GFileError ##### -->
<para>
Values corresponding to <literal>errno</literal> codes returned from file operations
-on UNIX. Unlike <literal>errno</literal> codes, #GFileError values are available on
+on Unix. Unlike <literal>errno</literal> codes, #GFileError values are available on
all systems, even Windows. The exact meaning of each code depends on what
-sort of file operation you were performing; the UNIX documentation
+sort of file operation you were performing; the Unix documentation
gives more details. The following error code descriptions come
from the GNU C Library manual, and are under the copyright
of that manual.
<!-- ##### STRUCT GHashTable ##### -->
<para>
-The #GHashTable struct is an opaque data structure to represent a
+The <structname>GHashTable</structname> 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>
<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.
+using pointers as keys in a #GHashTable.
</para>
@v: a gpointer key.
<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.
+using pointers to integers values as keys in a #GHashTable.
</para>
@v: a pointer to a #gint key.
<!-- ##### 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>#GHookFinalizeFunc finalize_hook;</entry>
-<entry>the function to call to finalize a #GHook element.
-The default behaviour is to call the hooks <function>destroy</function>
-function.</entry>
-</row>
-
-</tbody></tgroup></informaltable>
-
+The <structname>GHookList</structname> struct represents a
+list of hook functions.
</para>
-@seq_id:
-@hook_size:
-@is_setup:
-@hooks:
-@hook_memchunk:
-@finalize_hook:
+@seq_id: the next free #GHook id.
+@hook_size: the size of the #GHookList elements, in bytes.
+@is_setup: 1 if the #GHookList has been initialized.
+@hooks: the first #GHook element in the list.
+@hook_memchunk: the #GMemChunk used for allocating the #GHook elements.
+@finalize_hook: the function to call to finalize a #GHook element. The
+default behaviour is to call the hooks <function>destroy</function> function.
+
<!-- ##### USER_FUNCTION GHookFinalizeFunc ##### -->
<para>
<!-- ##### STRUCT GHook ##### -->
<para>
+The <structname>GHook</structname> struct represents a single hook
+function in a #GHookList.
+</para>
+
+@data: data which is passed to func when this hook is invoked.
+@next: pointer to the next hook in the list.
+@prev: pointer to the previous hook in the list.
+@ref_count: the reference count of this hook.
+@hook_id: the id of this hook, which is unique within its list.
+@flags: flags which are set for this hook. See #GHookFlagMask for
+predefined flags.
+@func: the function to call when this hook is invoked. The possible
+signatures for this function are #GHookFunc and #GHookCheckFunc.
+@destroy: the default <function>finalize_hook</function> function of a
+#GHookList calls this member of the hook that is being finalized.
-<informaltable pgwide=1 frame="none" role="struct">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry>#gpointer data;</entry>
-<entry>data which is passed to func when this hook is invoked.</entry>
-</row>
-
-<row>
-<entry>#GHook *next;</entry>
-<entry>pointer to the next hook in the list.</entry>
-</row>
-
-<row>
-<entry>#GHook *prev;</entry>
-<entry>pointer to the previous hook in the list.</entry>
-</row>
-
-<row>
-<entry>#guint ref_count;</entry>
-<entry>the reference count of this hook.</entry>
-</row>
-
-<row>
-<entry>#guint hook_id;</entry>
-<entry>the id of this hook, which is unique within its list.</entry>
-</row>
-
-<row>
-<entry>#guint flags;</entry>
-<entry>flags which are set for this hook. See #GHookFlagMask for
-predefined flags.</entry>
-</row>
-
-<row>
-<entry>#gpointer func;</entry>
-<entry>the function to call when this hook is invoked. The possible
-signatures for this function are #GHookFunc and #GHookCheckFunc.</entry>
-</row>
-
-<row>
-<entry>#GDestroyNotify destroy;</entry>
-<entry>the default <function>finalize_hook</function> function of a
-#GHookList calls this member of the hook that is being finalized.</entry>
-</row>
-
-</tbody></tgroup></informaltable>
-</para>
-
-@data:
-@next:
-@prev:
-@ref_count:
-@hook_id:
-@flags:
-@func:
-@destroy:
<!-- ##### USER_FUNCTION GHookFunc ##### -->
<para>
<!-- ##### MACRO G_OS_UNIX ##### -->
<para>
-This macro is defined only on UNIX. So you can bracket
-UNIX-specific code in "#ifdef G_OS_UNIX".
+This macro is defined only on Unix. So you can bracket
+Unix-specific code in "#ifdef G_OS_UNIX".
</para>
<!-- ##### MACRO G_BEGIN_DECLS ##### -->
<para>
Used (along with #G_END_DECLS) to bracket header files. If the
-compiler in use is a C++ compiler, adds 'extern "C"' around the header.
+compiler in use is a C++ compiler, adds <literal>extern "C"</literal>
+around the header.
</para>
<!-- ##### MACRO G_GNUC_EXTENSION ##### -->
<para>
-Expands to <literal>__extension__</literal> 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 <literal>-pedantic</literal> option.
+Expands to <literal>__extension__</literal> when <command>gcc</command> is
+used as the compiler.
+This simply tells <command>gcc</command> not to warn about the following non-standard code
+when compiling with the <option>-pedantic</option> option.
</para>
<!-- ##### MACRO G_GNUC_CONST ##### -->
<para>
-Expands to the GNU C const function attribute if the compiler is GNU C.
+Expands to the GNU C <literal>const</literal> function attribute if the compiler is <command>gcc</command>.
Declaring a function as const enables better optimization of the function.
A const function doesn't examine any values except its parameters,
and has no effects except its return value.
<!-- ##### MACRO G_GNUC_NORETURN ##### -->
<para>
-Expands to the GNU C noreturn function attribute if the compiler is GNU C.
+Expands to the GNU C <literal>noreturn</literal> function attribute if the compiler is <command>gcc</command>.
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.
<!-- ##### MACRO G_GNUC_UNUSED ##### -->
<para>
-Expands to the GNU C unused function attribute if the compiler is GNU C.
+Expands to the GNU C <literal>unused</literal> function attribute if the compiler is <command>gcc</command>.
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_PURE ##### -->
<para>
-Expands to the GNU C pure function attribute if the compiler is GNU C.
+Expands to the GNU C <literal>pure</literal> function attribute if the compiler is <command>gcc</command>.
Declaring a function as pure enables better optimization of the function.
A pure function has no effects except its return value and the return
value depends only on the parameters and/or global variables.
<!-- ##### MACRO G_GNUC_PRINTF ##### -->
<para>
-Expands to the GNU C format function attribute if the compiler is GNU C.
+Expands to the GNU C <literal>format</literal> function attribute if the compiler is <command>gcc</command>.
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.
<!-- ##### MACRO G_GNUC_SCANF ##### -->
<para>
-Expands to the GNU C format function attribute if the compiler is GNU C.
+Expands to the GNU C <literal>format</literal> function attribute if the compiler is <command>gcc</command>.
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.
<!-- ##### MACRO G_GNUC_FORMAT ##### -->
<para>
-Expands to the GNU C format_arg function attribute if the compiler is GNU C.
-The format_arg function attribute specifies that a function takes a format
+Expands to the GNU C <literal>format_arg</literal> function attribute if the compiler is <command>gcc</command>.
+This function attribute specifies that a function takes a format
string for a <function>printf()</function>, <function>scanf()</function>,
<function>strftime()</function> or <function>strfmon()</function> style
function and modifies it, so that the result can be passed to a
<!-- ##### MACRO G_GNUC_FUNCTION ##### -->
<para>
Expands to the GNU C <literal>__FUNCTION__</literal> variable if the
-compiler is GNU C, or "" if it isn't. The GNU C
+compiler is <command>gcc</command>, or "" if it isn't. The GNU C
<literal>__FUNCTION__</literal> 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 <literal>__PRETTY_FUNCTION__</literal> variable
-if the compiler is GNU C, or "" if it isn't.
+if the compiler is <command>gcc</command>, or "" if it isn't.
The GNU C <literal>__PRETTY_FUNCTION__</literal> variable contains the
name of the current function. For a C program this is the same as the
<literal>__FUNCTION__</literal> variable but for C++ it also includes
<!-- ##### MACRO G_GNUC_NO_INSTRUMENT ##### -->
<para>
-Expands to the GNU C no_instrument_function function attribute if
-the compiler is GNU C. Functions with this attribute will not be
+Expands to the GNU C <literal>no_instrument_function</literal> function
+attribute if the compiler is <command>gcc</command>. Functions with this
+attribute will not be
instrumented for profiling, when the compiler is called with the
<option>-finstrument-functions</option> option.
See the GNU C documentation for details.
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.
+In GDK this priority is used for events from the X server.
</para>
<row>
<entry>#gint fd;</entry>
-<entry>the file descriptor to poll (or a HANDLE on Win32 platforms).</entry>
+<entry>the file descriptor to poll (or a <type>HANDLE</type> on Win32 platforms).</entry>
</row>
<row>
<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.
+results of the <function>poll()</function> 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.
+(in milliseconds) which should be passed to the <function>poll()</function> 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>
Simple XML Subset Parser
<!-- ##### SECTION Short_Description ##### -->
-
-Parses a subset of XML
+parses a subset of XML.
<!-- ##### SECTION Long_Description ##### -->
<para>
The "GMarkup" parser is intended to parse a simple markup format
-that's a subset of XML format. This is a small, efficient, easy-to-use
+that's a subset of XML. This is a small, efficient, easy-to-use
parser. It should not be used if you expect to interoperate with other
applications generating full-scale XML. However, it's very useful for
application data files, config files, etc. where you know your
<!-- ##### MACRO g_alloca ##### -->
<para>
Allocates @size bytes on the stack; these bytes will be freed when the current
-stack frame is cleaned up. This macro essentially just wraps the alloca(3) function
-present on most unix variants. Thus it provides the same advantages and pitfalls
-as alloca():
+stack frame is cleaned up. This macro essentially just wraps the
+<function>alloca()</function> function present on most Unix variants.
+Thus it provides the same advantages and pitfalls as <function>alloca()</function>:
<msgtext><variablelist>
<varlistentry><term></term><listitem><para>
- + alloca() is very fast, as on most systems it's implemented by just adjusting
+ + <function>alloca()</function> is very fast, as on most systems it's implemented by just adjusting
the stack pointer register.
</para></listitem></varlistentry>
<varlistentry><term></term><listitem><para>
<varlistentry><term></term><listitem><para>
- Allocation sizes have to fit into the current stack frame. For instance in a
threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
- so be sparse with alloca() uses.
+ so be sparse with <funcion>alloca()</function> uses.
</para></listitem></varlistentry>
<varlistentry><term></term><listitem><para>
- Allocation failure due to insufficient stack space is not indicated with a %NULL
- return like e.g. with malloc(3). Instead, most systems probably handle it the same
+ return like e.g. with <function>malloc()</function>. Instead, most systems probably handle it the same
way as out of stack space situations from infinite function recursion, i.e.
with a segmentation fault.
</para></listitem></varlistentry>
<varlistentry><term></term><listitem><para>
- - Special care has to be taken when mixing alloca(3) with GCC variable sized arrays.
- Stack space allocated with alloca(3) in the same scope as a variable sized array
+ - Special care has to be taken when mixing <function>alloca()</function> with GNU C variable sized arrays.
+ Stack space allocated with <function>alloca()</function> in the same scope as a variable sized array
will be freed together with the variable sized array upon exit of that scope, and
not upon exit of the enclosing function scope.
</para></listitem></varlistentry>
<!-- ##### FUNCTION g_mem_set_vtable ##### -->
<para>
Sets the #GMemVTable to use for memory allocation. You can use this to provide
-custom memory allocation routines. THIS FUNCTION MUST BE CALLED BEFORE USING ANY
-OTHER GLIB FUNCTIONS. The @vtable only needs to provide <function>malloc()</function>, <function>realloc()</function>, and <function>free()</function>
+custom memory allocation routines. <emphasis>This function must be called before using any other GLib functions.</emphasis> The @vtable only needs to provide <function>malloc()</function>, <function>realloc()</function>, and <function>free()</function>
functions; GLib can provide default implementations of the others. The <function>malloc()</function>
and <function>realloc()</function> implementations should return %NULL on failure, GLib will handle
error-checking for you. @vtable is copied, so need not persist after this
GRealArray *array;
/* Create a GMemChunk to hold GRealArray structures, using the
- g_mem_chunk_create() convenience macro. We want 1024 atoms in each
+ 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);
For example, GTK+ uses this in its Makefile.am:
</para>
<informalexample><programlisting>
-INCLUDES = \
- -DG_LOG_DOMAIN=\"Gtk\"
+INCLUDES = -DG_LOG_DOMAIN=\"Gtk\"
</programlisting></informalexample>
A convenience function/macro to log a normal message.
</para>
-@...:
+@...: the parameters to insert into the format string.
<!-- # Unused Parameters # -->
@format: the message format. See the <function>printf()</function>
documentation.
A convenience function/macro to log a warning message.
</para>
-@...: format string, followed by parameters to insert into the format string (as with printf())
+@...: format string, followed by parameters to insert into the format string (as with <function>printf()</function>)
<!-- ##### MACRO g_critical ##### -->
example.
</para>
-@...: format string, followed by parameters to insert into the format string (as with printf())
+@...: format string, followed by parameters to insert into the format string (as with <function>printf()</function>)
<!-- ##### MACRO g_error ##### -->
assertion failure.
</para>
-@...:
+@...: the parameters to insert into the format string.
<!-- # Unused Parameters # -->
@format: the message format. See the <function>printf()</function>
documentation.
<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.
+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.
+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>
<para>
@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.
+@unused_data: data passed from g_log() which is unused.
<!-- ##### FUNCTION g_get_real_name ##### -->
<para>
-Gets the real name of the user. This comes from the user's entry in the
+Gets the real name of the user. This usually comes from the user's entry in the
<filename>passwd</filename> file.
</para>
Gets the directory to use for temporary files.
This is found from inspecting the environment variables <envar>TMPDIR</envar>,
<envar>TMP</envar>, and <envar>TEMP</envar>
-in that order. If none of those are defined "/tmp" is returned.
+in that order. If none of those are defined "/tmp" is returned on Unix and
+"C:\" on Windows.
</para>
@Returns: the directory to use for temporary files.
<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.
+on Unix or 'C:\windows' on Windows systems.
</para>
@file_name: a file name.
<!-- ##### 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
+the '/' in Unix or 'C:\' under Windows. If @file_name is not an absolute
path it returns %NULL.
</para>
each prime is approximately 1.5-2 times the previous prime.
</para>
-@num: a guint.
+@num: a #guint.
@Returns: the smallest prime number from a built-in array of primes which is
larger than @num.
<para>
Expands to the proper shared library suffix for the current platform
without the leading dot. For the most Unices and Linux this is "so",
-for some HPUX versions this is "sl" and for Windows this is "dll".
+for some HP-UX versions this is "sl" and for Windows this is "dll".
</para>
Numerical Definitions
<!-- ##### SECTION Short_Description ##### -->
-
-Mathematical constants, and floating point decomposition.
+mathematical constants, and floating point decomposition.
<!-- ##### SECTION Long_Description ##### -->
<para>
sign, mantissa and exponent of IEEE floats and doubles. These
unions are defined as appropriate for a given platform.
IEEE floats and doubles are supported (used for
- storage) by at least
intel, ppc and sparc, for reference: <ulink url="http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html">http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html</ulink>
+ storage) by at least
Intel, PPC and Sparc, for reference: <ulink url="http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html">http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html</ulink>
</para>
<!-- ##### SECTION See_Also ##### -->
sign, mantissa and exponent of IEEE floats and doubles. These
unions are defined as appropriate for a given platform.
IEEE floats and doubles are supported (used for
- storage) by at least intel, ppc and sparc, for reference:
+ storage) by at least Intel, PPC and Sparc, for reference:
<ulink url="http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html">http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html</ulink>
</para>
sign, mantissa and exponent of IEEE floats and doubles. These
unions are defined as appropriate for a given platform.
IEEE floats and doubles are supported (used for
- storage) by at least intel, ppc and sparc, for reference:
+ storage) by at least Intel, PPC and Sparc, for reference:
<ulink url="http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html">http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html</ulink>
</para>
Glob-style pattern matching
<!-- ##### SECTION Short_Description ##### -->
-
-Matches strings against patterns containing '*' (wildcard) and '?' (joker).
+matches strings against patterns containing '*' (wildcard) and '?' (joker).
<!-- ##### SECTION Long_Description ##### -->
<para>
Double-ended Queues
<!-- ##### SECTION Short_Description ##### -->
-double-ended queue data structure
+double-ended queue data structure.
<!-- ##### SECTION Long_Description ##### -->
<para>
Shell-related Utilities
<!-- ##### SECTION Short_Description ##### -->
-shell-like commandline handling
+shell-like commandline handling.
<!-- ##### SECTION Long_Description ##### -->
<para>
Spawning Processes
<!-- ##### SECTION Short_Description ##### -->
-Process launching with <function>fork()</function>/<function>exec()</function>
+process launching with <function>fork()</function>/<function>exec()</function>.
<!-- ##### SECTION Long_Description ##### -->
<para>
<!-- ##### FUNCTION g_strlcat ##### -->
<para>
-Portability wrapper that calls strlcat() on systems which have it, and emulates
-strlcat() otherwise. Appends nul-terminated @src string to @dest, guaranteeing
+Portability wrapper that calls <function>strlcat()</function> on systems which have it, and emulates it otherwise. Appends nul-terminated @src string to @dest, guaranteeing
nul-termination for @dest. The total size of @dest won't exceed
-@dest_size. Caveat: this is supposedly a more secure alternative to strcat() or
-strncat(), but for real security g_strconcat() is harder to mess up.
+@dest_size. Caveat: this is supposedly a more secure alternative to <function>strcat()</function> or
+<function>strncat()</function>, but for real security g_strconcat() is harder to mess up.
</para>
@dest: destination buffer, already containing one nul-terminated string
Determines whether a character is alphanumeric.
</para>
<para>
-Unlike the standard C library isalnum function, this only
+Unlike the standard C library <function>isalnum()</function> function, this only
recognizes standard ASCII letters and ignores the locale, returning
%FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
-on EOF but no need to cast to guchar before passing a possibly
-non-ASCII character in.
+library function, this takes a <type>char</type>, not an <type>int</type>,
+so don't call it on %EOF but no need to cast to #guchar before passing a
+possibly non-ASCII character in.
</para>
@c: any character
Determines whether a character is alphabetic (i.e. a letter).
</para>
<para>
-Unlike the standard C library isalpha function, this only
+Unlike the standard C library <function>isalpha()</function> function, this only
recognizes standard ASCII letters and ignores the locale, returning
%FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
-on EOF but no need to cast to guchar before passing a possibly
-non-ASCII character in.
+library function, this takes a <type>char</type>, not an <type>int</type,
+so don't call it on %EOF but no need to cast to #guchar before passing a
+possibly non-ASCII character in.
</para>
@c: any character
Determines whether a character is a control character.
</para>
<para>
-Unlike the standard C library iscntrl function, this only
+Unlike the standard C library <function>iscntrl()</function> function, this only
recognizes standard ASCII control characters and ignores the locale,
-returning%FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
-on EOF but no need to cast to guchar before passing a possibly
-non-ASCII character in.
+returning %FALSE for all non-ASCII characters. Also unlike the standard
+library function, this takes a <type>char</type>, not an <type>int</type>,
+so don't call it on %EOF but no need to cast to #guchar before passing a
+possibly non-ASCII character in.
</para>
@c: any character
Determines whether a character is digit (0-9).
</para>
<para>
-Unlike the standard C library isdigit function,
-this takes a char, not an int, so don't call it
-on EOF but no need to cast to guchar before passing a possibly
+Unlike the standard C library <function>isdigit()</function> function,
+this takes a <type>char</type>, not an <type>int</type>, so don't call it
+on %EOF but no need to cast to #guchar before passing a possibly
non-ASCII character in.
</para>
Determines whether a character is a printing character and not a space.
</para>
<para>
-Unlike the standard C library isgraph function, this only
-recognizes standard ASCII characters and ignores the locale, returning
-%FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
-on EOF but no need to cast to guchar before passing a possibly
-non-ASCII character in.
+Unlike the standard C library <function>isgraph()</function> function,
+this only recognizes standard ASCII characters and ignores the locale,
+returning %FALSE for all non-ASCII characters. Also unlike the standard
+library function, this takes a <type>char</type>, not an <type>int</type>,
+so don't call it on %EOF but no need to cast to #guchar before passing a
+possibly non-ASCII character in.
</para>
@c: any character
Determines whether a character is an ASCII lower case letter.
</para>
<para>
-Unlike the standard C library islower function, this only
-recognizes standard ASCII letters and ignores the locale, returning
-%FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
-on EOF but no need to worry about casting to guchar before passing
-a possibly non-ASCII character in.
+Unlike the standard C library <function>islower()</function> function,
+this only recognizes standard ASCII letters and ignores the locale,
+returning %FALSE for all non-ASCII characters. Also unlike the standard
+library function, this takes a <type>char</type>, not an <type>int</type>,
+so don't call it on %EOF but no need to worry about casting to #guchar
+before passing a possibly non-ASCII character in.
</para>
@c: any character
Determines whether a character is a printing character.
</para>
<para>
-Unlike the standard C library isprint function, this only
-recognizes standard ASCII characters and ignores the locale, returning
-%FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
-on EOF but no need to cast to guchar before passing a possibly
-non-ASCII character in.
+Unlike the standard C library <function>isprint()</function> function,
+this only recognizes standard ASCII characters and ignores the locale,
+returning %FALSE for all non-ASCII characters. Also unlike the standard
+library function, this takes a <type>char</type>, not an <type>int</type>,
+so don't call it on %EOF but no need to cast to #guchar before passing a
+possibly non-ASCII character in.
</para>
@c: any character
Determines whether a character is a punctuation character.
</para>
<para>
-Unlike the standard C library ispunct function, this only
-recognizes standard ASCII letters and ignores the locale, returning
-%FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
-on EOF but no need to cast to guchar before passing a possibly
-non-ASCII character in.
+Unlike the standard C library <function>ispunct()</function> function,
+this only recognizes standard ASCII letters and ignores the locale,
+returning %FALSE for all non-ASCII characters. Also unlike the standard
+library function, this takes a <type>char</type>, not an <type>int</type>,
+so don't call it on %EOF but no need to cast to #guchar before passing a
+possibly non-ASCII character in.
</para>
@c: any character
Determines whether a character is a white-space character.
</para>
<para>
-Unlike the standard C library isspace function, this only
-recognizes standard ASCII white-space and ignores the locale, returning
-%FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
-on EOF but no need to cast to guchar before passing a possibly
-non-ASCII character in.
+Unlike the standard C library <function>isspace()</function> function,
+this only recognizes standard ASCII white-space and ignores the locale,
+returning %FALSE for all non-ASCII characters. Also unlike the standard
+library function, this takes a <type>char</type>, not an <type>int</type>,
+so don't call it on %EOF but no need to cast to #guchar before passing a
+possibly non-ASCII character in.
</para>
@c: any character
Determines whether a character is an ASCII upper case letter.
</para>
<para>
-Unlike the standard C library isupper function, this only
-recognizes standard ASCII letters and ignores the locale, returning
-%FALSE for all non-ASCII characters. Also unlike the standard
-library function, this takes a char, not an int, so don't call it
-on EOF but no need to worry about casting to guchar before passing
-a possibly non-ASCII character in.
+Unlike the standard C library <function>isupper()</function> function,
+this only recognizes standard ASCII letters and ignores the locale,
+returning %FALSE for all non-ASCII characters. Also unlike the standard
+library function, this takes a <type>char</type>, not an <type>int</type>,
+so don't call it on %EOF but no need to worry about casting to #guchar
+before passing a possibly non-ASCII character in.
</para>
@c: any character
Determines whether a character is a hexadecimal-digit character.
</para>
<para>
-Unlike the standard C library isxdigit function,
-this takes a char, not an int, so
-don't call it on EOF but no need to cast to guchar before passing a
+Unlike the standard C library <function>isxdigit()</function> function,
+this takes a <type>char</type>, not an <type>int</type>, so
+don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
</para>
</para>
<para>
The problem with g_strncasecmp() is that it does the comparison by
-calling toupper()/tolower() on each byte. toupper()/tolower() are
+calling <function>toupper()</function>/<function>tolower()</function>
+on each byte. <function>toupper()</function>/<function>tolower()</function> are
locale-specific and operate on single bytes. However, it is impossible
to handle things correctly from an i18n standpoint by operating on
bytes, since characters may be multibyte. Thus g_strncasecmp() is
<!-- ##### FUNCTION g_strreverse ##### -->
<para>
Reverses all of the characters in a string.
-For example, g_strreverse ("abcdef") will result in "fedcba".
+For example, <literal>g_strreverse ("abcdef")</literal> will result in "fedcba".
</para>
@string: the string to reverse.
<!-- ##### MACRO G_ASCII_DTOSTR_BUF_SIZE ##### -->
<para>
-A good size for a buffer to be passed into <function>g_ascii_dtostr</function>.
+A good size for a buffer to be passed into g_ascii_dtostr().
It is guaranteed to be enough for all output of that function on systems with
- 64bit IEEE compatible doubles.
+ 64bit IEEE-compatible doubles.
</para>
<para>
The typical usage would be something like:
-</para>
-<para>
-<literal>
+<informalexample><programlisting>
char buf[G_ASCII_DTOSTR_BUF_SIZE];
fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
-</literal>
+</programlisting></informalexample>
</para>
<!-- ##### MACRO G_STR_DELIMITERS ##### -->
<para>
-The standard delimiters, used in #g_strdelimit.
+The standard delimiters, used in g_strdelimit().
</para>
Thread Pools
<!-- ##### SECTION Short_Description ##### -->
-Pools of threads to execute work concurrently
+pools of threads to execute work concurrently.
<!-- ##### SECTION Long_Description ##### -->
<para>
<note>
<para>
g_thread_init() must not be called directly or indirectly as a
-call-back from GLib. Also no mutexes may be currently locked, while
+callback from GLib. Also no mutexes may be currently locked, while
calling g_thread_init().
</para>
</note>
<para>
<informalexample>
<programlisting>
-if (!g_thread_supported ()) g_thread_init (NULL);
+if (!g_thread_supported (<!>)) g_thread_init (NULL);
</programlisting>
</informalexample>
</para>
<!-- ##### FUNCTION g_thread_join ##### -->
<para>
Waits until @thread finishes, i.e. the function @func, as given
-to g_thread_create, returns or g_thread_exit() is called by
+to g_thread_create(), returns or g_thread_exit() is called by
@thread. All resources of @thread including the #GThread struct are
released. @thread must have been created with @joinable=%TRUE in
g_thread_create(). The value returned by @func or given to
<!-- ##### FUNCTION g_thread_set_priority ##### -->
<para>
-Change the priority of @thread to @priority.
+Changes the priority of @thread to @priority.
</para>
<note>
<!-- ##### FUNCTION g_thread_yield ##### -->
<para>
-Give way to other threads waiting to be scheduled.
+Gives way to other threads waiting to be scheduled.
</para>
<para>
<!-- ##### FUNCTION g_thread_exit ##### -->
<para>
-Exit the current thread. If another thread is waiting for that thread
+Exits the current thread. If another thread is waiting for that thread
using g_thread_join() and the current thread is joinable, the waiting
thread will be woken up and getting @retval as the return value of
g_thread_join(). If the current thread is not joinable, @retval is
<note>
<para>
-Never call g_thread_exit from within a thread of a #GThreadPool, as
-that will mess up the bookkeeping and lead to funny and unwanted
-results.
+Never call g_thread_exit() from within a thread of a #GThreadPool, as
+that will mess up the bookkeeping and lead to funny and unwanted results.
</para>
</note>
<example>
<title>A function which will not work in a threaded environment</title>
<programlisting>
- int give_me_next_number ()
+ int give_me_next_number (<!>)
{
static int current_number = 0;
<example>
<title>The wrong way to write a thread-safe function</title>
<programlisting>
- int give_me_next_number ()
+ int give_me_next_number (<!>)
{
static int current_number = 0;
int ret_val;
/* 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 ()
+ 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 ()
+ int give_me_next_number (<!>)
{
static int current_number = 0;
int ret_val;
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:
+safer version of our <function>give_me_next_number()</function> example:
</para>
<para>
<example>
-<title>Using GStaticMutex to simplify thread-safe programming</title>
+<title>Using <structname>GStaticMutex</structname> to simplify thread-safe programming</title>
<programlisting>
- int give_me_next_number ()
+ int give_me_next_number (<!>)
{
static int current_number = 0;
int ret_val;
<para>
<example>
-<title>Using the G_LOCK_* convenience macros</title>
+<title>Using the %G_LOCK_* convenience macros</title>
<programlisting>
G_LOCK_DEFINE (current_number);
-int give_me_next_number ()
+int give_me_next_number (<!>)
{
static int current_number = 0;
int ret_val;
<!-- ##### SECTION Short_Description ##### -->
-Keep track of elapsed time.
+keep track of elapsed time.
<!-- ##### SECTION Long_Description ##### -->
<para>
Balanced Binary Trees
<!-- ##### SECTION Short_Description ##### -->
-a sorted collection of key/value pairs optimised for searching
+a sorted collection of key/value pairs optimized 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.
+of key/value pairs optimized for searching and traversing in order.
</para>
<para>
To create a new #GTree use g_tree_new().
<!-- ##### STRUCT GTree ##### -->
<para>
-The #GTree struct is an opaque data structure representing a
+The <structname>GTree</structname> 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>
<!-- ##### STRUCT GNode ##### -->
<para>
-The #GNode struct represents one node in a
+The <structname>GNode</structname> 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
+fields point to the node's siblings (a sibling is another <structname>GNode</structname> 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>parent</structfield> field points to the parent of the <structname>GNode</structname>,
+or is %NULL if the <structname>GNode</structname> 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
+<structname>GNode</structname>. The other children are accessed by using the
<structfield>next</structfield> pointer of each child.
</para>
<!-- ##### SECTION Short_Description ##### -->
-Portably storing integers in pointer variables.
+portably storing integers in pointer variables.
<!-- ##### SECTION Long_Description ##### -->
<para>
data" to a callback, in the form of a void pointer. From time to time
you want to pass an integer instead of a pointer. You could allocate
an integer, with something like:
-<programlisting>
+<informalexample><programlisting>
int *ip = g_new (int, 1);
*ip = 42;
-</programlisting>
+</programlisting></informalexample>
But this is inconvenient, and it's annoying to have to free the
memory at some later time.
</para>
Pointers are always at least 32 bits in size (on all platforms GLib
intends to support). Thus you can store at least 32-bit integer values
in a pointer value. Naively, you might try this, but it's incorrect:
-<programlisting>
+<informalexample><programlisting>
gpointer p;
int i;
p = (void*) 42;
i = (int) p;
-</programlisting>
+</programlisting></informalexample>
Again, that example was <emphasis>not</emphasis> correct, don't copy it.
The problem is that on some systems you need to do this:
-<programlisting>
+<informalexample><programlisting>
gpointer p;
int i;
p = (void*) (long) 42;
i = (int) (long) p;
-</programlisting>
+</programlisting></informalexample>
So GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. do the right thing
on the current platform.
</para>
<!-- ##### TYPEDEF gunichar ##### -->
<para>
-A type which can hold any UCS-4 character code.
+A type which can hold any UCS-4 character code.
</para>
<!-- ##### MACRO g_utf8_next_char ##### -->
<para>
Skips to the next character in a UTF-8 string. The string must be
-valid; this macro is as fast as possible, and has zero error-checking.
+valid; this macro is as fast as possible, and has no error-checking.
You would use this macro to iterate over a string character by
character. The macro returns the start of the next UTF-8 character.
Before using this macro, use g_utf8_validate() to validate strings
<!-- ##### ENUM GNormalizeMode ##### -->
<para>
-A #GNormalizeMode defines how a Unicode string is transformed in a canonical
+Defines how a Unicode string is transformed in a canonical
form, standardizing such issues as whether a character with an accent is
represented as a base character and combining accent or as a single precomposed
character. Unicode strings should generally be normalized before comparing them.
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
+By providing your own handler you can redirect the output, to a GTK+
widget or a log file for example.
</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
+By providing your own handler you can redirect the output, to a GTK+
widget or a log file for example.
</para>
If [P]roceed is selected, the function returns.
</para>
<para>
-This function may cause different actions on non-unix platforms.
+This function may cause different actions on non-Unix platforms.
</para>
@prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option.
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.
+This function may cause different actions on non-Unix platforms.
</para>
@prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option.
Windows Compatibility Functions
<!-- ##### SECTION Short_Description ##### -->
-Unix emulation on Windows
+Unix emulation on Windows.
<!-- ##### SECTION Long_Description ##### -->
<para>
<!-- ##### MACRO MAXPATHLEN ##### -->
<para>
-Provided for UNIX emulation on Windows; equivalent to UNIX
+Provided for Unix emulation on Windows; equivalent to Unix
macro %MAXPATHLEN, which is the maximum length of a filename
(including full path).
</para>
<!-- ##### TYPEDEF pid_t ##### -->
<para>
-Provided for UNIX emulation on Windows; process ID type.
+Provided for Unix emulation on Windows; process ID type.
</para>
<!-- ##### MACRO pipe ##### -->
<para>
-Provided for UNIX emulation on Windows; see documentation for <function>pipe()</function>
-in any UNIX manual.
+Provided for Unix emulation on Windows; see documentation for <function>pipe()</function>
+in any Unix manual.
</para>
@phandles:
<!-- ##### MACRO ftruncate ##### -->
<para>
-Provided for UNIX emulation on Windows; see documentation for <function>ftruncate()</function>
-in any UNIX manual.
+Provided for Unix emulation on Windows; see documentation for <function>ftruncate()</function>
+in any Unix manual.
</para>
@fd:
* @to_codeset: destination codeset
* @from_codeset: source codeset
*
- * Same as the standard UNIX routine iconv_open(), but
- * may be implemented via libiconv on UNIX flavors that lack
+ * Same as the standard Unix routine <function>iconv_open()</function>, but
+ * may be implemented via libiconv on Unix flavors that lack
* a native implementation.
*
- * GLib provides g_convert() and g_locale_to_utf8() which are likely
+ * &GLib; provides g_convert() and g_locale_to_utf8() which are likely
* more convenient than the raw iconv wrappers.
*
* Return value: a "conversion descriptor"
* @outbuf: converted output bytes
* @outbytes_left: inout parameter, bytes available to fill in @outbuf
*
- * Same as the standard UNIX routine iconv(), but
- * may be implemented via libiconv on UNIX flavors that lack
+ * Same as the standard Unix routine <function>iconv()</function>, but
+ * may be implemented via libiconv on Unix flavors that lack
* a native implementation.
*
- * GLib provides g_convert() and g_locale_to_utf8() which are likely
+ * &GLib; provides g_convert() and g_locale_to_utf8() which are likely
* more convenient than the raw iconv wrappers.
*
* Return value: count of non-reversible conversions, or -1 on error
* g_iconv_close:
* @converter: a conversion descriptor from g_iconv_open()
*
- * Same as the standard UNIX routine iconv_close(), but
- * may be implemented via libiconv on UNIX flavors that lack
+ * Same as the standard Unix routine <function>iconv_close()</function>, but
+ * may be implemented via libiconv on Unix flavors that lack
* a native implementation. Should be called to clean up
- * the conversion descriptor from iconv_open() when
+ * the conversion descriptor from g_iconv_open() when
* you are done converting things.
*
- * GLib provides g_convert() and g_locale_to_utf8() which are likely
+ * &GLib; provides g_convert() and g_locale_to_utf8() which are likely
* more convenient than the raw iconv wrappers.
*
* Return value: -1 on error, 0 on success
* stored will the byte offset after the last valid
* input sequence.
* @bytes_written: the number of bytes stored in the output buffer (not
- * including the terminating NULL).
+ * including the terminating nul).
* @error: location to store the error occuring, or %NULL to ignore
* errors. Any of the errors in #GConvertError may occur.
*
- * Convert a string from one character set to another.
+ * Converts a string from one character set to another.
*
* Return value: If the conversion was successful, a newly allocated
* nul-terminated string, which must be freed with
* @converter: conversion descriptor from g_iconv_open()
* @bytes_read: location to store the number of bytes in the
* input string that were successfully converted, or %NULL.
- * Even if the conversion was succesful, this may be
+ * Even if the conversion was successful, this may be
* less than @len if there were partial characters
* at the end of the input. If the error
* #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
* stored will the byte offset after the last valid
* input sequence.
* @bytes_written: the number of bytes stored in the output buffer (not
- * including the terminating NULL).
+ * including the terminating nul).
* @error: location to store the error occuring, or %NULL to ignore
* errors. Any of the errors in #GConvertError may occur.
*
- * Convert a string from one character set to another.
+ * Converts a string from one character set to another.
*
* Return value: If the conversion was successful, a newly allocated
* nul-terminated string, which must be freed with
* as Unicode escapes \x{XXXX} or \x{XXXXXX}.
* @bytes_read: location to store the number of bytes in the
* input string that were successfully converted, or %NULL.
- * Even if the conversion was succesful, this may be
+ * Even if the conversion was successful, this may be
* less than @len if there were partial characters
* at the end of the input.
* @bytes_written: the number of bytes stored in the output buffer (not
- * including the terminating NULL).
+ * including the terminating nul).
* @error: location to store the error occuring, or %NULL to ignore
* errors. Any of the errors in #GConvertError may occur.
*
- * Convert a string from one character set to another, possibly
+ * Converts a string from one character set to another, possibly
* including fallback sequences for characters not representable
* in the output. Note that it is not guaranteed that the specification
* for the fallback sequences in @fallback will be honored. Some
* systems may do a approximate conversion from @from_codeset
- * to @to_codeset in their iconv() functions, in which case GLib
- * will simply return that approximate conversion.
+ * to @to_codeset in their <function>iconv()</function> functions,
+ * in which case &GLib; will simply return that approximate conversion.
*
* Return value: If the conversion was successful, a newly allocated
* nul-terminated string, which must be freed with
* nul-terminated.
* @bytes_read: location to store the number of bytes in the
* input string that were successfully converted, or %NULL.
- * Even if the conversion was succesful, this may be
+ * Even if the conversion was successful, this may be
* less than @len if there were partial characters
* at the end of the input. If the error
* #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
* stored will the byte offset after the last valid
* input sequence.
* @bytes_written: the number of bytes stored in the output buffer (not
- * including the terminating NULL).
+ * including the terminating nul).
* @error: location to store the error occuring, or %NULL to ignore
* errors. Any of the errors in #GConvertError may occur.
*
* nul-terminated.
* @bytes_read: location to store the number of bytes in the
* input string that were successfully converted, or %NULL.
- * Even if the conversion was succesful, this may be
+ * Even if the conversion was successful, this may be
* less than @len if there were partial characters
* at the end of the input. If the error
* #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
* stored will the byte offset after the last valid
* input sequence.
* @bytes_written: the number of bytes stored in the output buffer (not
- * including the terminating NULL).
+ * including the terminating nul).
* @error: location to store the error occuring, or %NULL to ignore
* errors. Any of the errors in #GConvertError may occur.
*
* nul-terminated.
* @bytes_read: location to store the number of bytes in the
* input string that were successfully converted, or %NULL.
- * Even if the conversion was succesful, this may be
+ * Even if the conversion was successful, this may be
* less than @len if there were partial characters
* at the end of the input. If the error
* #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
* stored will the byte offset after the last valid
* input sequence.
* @bytes_written: the number of bytes stored in the output buffer (not
- * including the terminating NULL).
+ * including the terminating nul).
* @error: location to store the error occuring, or %NULL to ignore
* errors. Any of the errors in #GConvertError may occur.
*
* nul-terminated.
* @bytes_read: location to store the number of bytes in the
* input string that were successfully converted, or %NULL.
- * Even if the conversion was succesful, this may be
+ * Even if the conversion was successful, this may be
* less than @len if there were partial characters
* at the end of the input. If the error
* #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
* stored will the byte offset after the last valid
* input sequence.
* @bytes_written: the number of bytes stored in the output buffer (not
- * including the terminating NULL).
+ * including the terminating nul).
* @error: location to store the error occuring, or %NULL to ignore
* errors. Any of the errors in #GConvertError may occur.
*
* Converts an escaped UTF-8 encoded URI to a local filename in the
* encoding used for filenames.
*
- * Return value: a newly allocated string holding the resulting
+ * Return value: a newly-allocated string holding the resulting
* filename, or %NULL on an error.
**/
gchar *
*
* Converts an absolute filename to an escaped UTF-8 encoded URI.
*
- * Return value: a newly allocated string holding the resulting
+ * Return value: a newly-allocated string holding the resulting
* URI, or %NULL on an error.
**/
gchar *
* is useful if you need to free the memory allocated for the original key,
* for example before calling g_hash_table_remove().
*
- * Return value: #TRUE if the key was found in the #GHashTable.
+ * Return value: %TRUE if the key was found in the #GHashTable.
**/
gboolean
g_hash_table_lookup_extended (GHashTable *hash_table,
* you have to make sure that any dynamically allocated values are freed
* yourself.
*
- * Return value: #TRUE if the key was found and removed from the #GHashTable.
+ * Return value: %TRUE if the key was found and removed from the #GHashTable.
**/
gboolean
g_hash_table_remove (GHashTable *hash_table,
* Removes a key and its associated value from a #GHashTable without
* calling the key and value destroy functions.
*
- * Return value: #TRUE if the key was found and removed from the #GHashTable.
+ * Return value: %TRUE if the key was found and removed from the #GHashTable.
**/
gboolean
g_hash_table_steal (GHashTable *hash_table,
* g_rand_new:
*
* Creates a new random number generator initialized with a seed taken
- * either from /dev/urandom (if existing) or from the current time (as
- * a fallback).
+ * either from <filename>/dev/urandom</filename> (if existing) or from
+ * the current time (as a fallback).
*
* Return value: the new #GRand.
**/
* g_rand_int:
* @rand: a #GRand.
*
- * Return the next random #guint32 from @rand equaly distributed over
+ * Returns the next random #guint32 from @rand equally distributed over
* the range [0..2^32-1].
*
* Return value: A random number.
* @begin: lower closed bound of the interval.
* @end: upper open bound of the interval.
*
- * Return the next random #gint32 from @rand equaly distributed over
+ * Returns the next random #gint32 from @rand equally distributed over
* the range [@begin..@end-1].
*
* Return value: A random number.
* g_rand_double:
* @rand: a #GRand.
*
- * Return the next random #gdouble from @rand equaly distributed over
+ * Returns the next random #gdouble from @rand equally distributed over
* the range [0..1).
*
* Return value: A random number.
* @begin: lower closed bound of the interval.
* @end: upper open bound of the interval.
*
- * Return the next random #gdouble from @rand equaly distributed over
+ * Returns the next random #gdouble from @rand equally distributed over
* the range [@begin..@end).
*
* Return value: A random number.
/**
* g_random_int:
*
- * Return a random #guint32 equaly distributed over the range
+ * Return a random #guint32 equally distributed over the range
* [0..2^32-1].
*
* Return value: A random number.
* @begin: lower closed bound of the interval.
* @end: upper open bound of the interval.
*
- * Return a random #gint32 equaly distributed over the range
+ * Returns a random #gint32 equally distributed over the range
* [@begin..@end-1].
*
* Return value: A random number.
/**
* g_random_double:
*
- * Return a random #gdouble equaly distributed over the range [0..1).
+ * Returns a random #gdouble equally distributed over the range [0..1).
*
* Return value: A random number.
**/
* @begin: lower closed bound of the interval.
* @end: upper open bound of the interval.
*
- * Return a random #gdouble equaly distributed over the range [@begin..@end).
+ * Returns a random #gdouble equally distributed over the range [@begin..@end).
*
* Return value: A random number.
**/
* @seed: a value to reinitialize the global random number generator.
*
* Sets the seed for the global random number generator, which is used
- * by te g_random_* functions, to @seed.
+ * by the <function>g_random_*</function> functions, to @seed.
**/
void
g_random_set_seed (guint32 seed)
*
* The parameter @exclusive determines, whether the thread pool owns
* all threads exclusive or whether the threads are shared
- * globally. If @exclusive is @TRUE, @max_threads threads are started
+ * globally. If @exclusive is %TRUE, @max_threads threads are started
* immediately and they will run exclusively for this thread pool until
- * it is destroyed by g_thread_pool_free(). If @exclusive is @FALSE,
+ * it is destroyed by g_thread_pool_free(). If @exclusive is %FALSE,
* threads are created, when needed and shared between all
* non-exclusive thread pools. This implies that @max_threads may not
* be -1 for exclusive thread pools.
*
- * @error can be NULL to ignore errors, or non-NULL to report
- * errors. An error can only occur, when @exclusive is set to @TRUE and
+ * @error can be %NULL to ignore errors, or non-%NULL to report
+ * errors. An error can only occur when @exclusive is set to %TRUE and
* not all @max_threads threads could be created.
*
* Return value: the new #GThreadPool
* in the queue until a thread in this pool finishes its previous task
* and processes @data.
*
- * @error can be NULL to ignore errors, or non-NULL to report
- * errors. An error can only occur, when a new thread couldn't be
+ * @error can be %NULL to ignore errors, or non-%NULL to report
+ * errors. An error can only occur when a new thread couldn't be
* created. In that case @data is simply appended to the queue of work
* to do.
**/
*
* A thread is never terminated while calling @func, as supplied by
* g_thread_pool_new (). Instead the maximal number of threads only
- * has effect for the allocation of new threads in g_thread_pool_push
- * (). A new thread is allocated, whenever the number of currently
+ * has effect for the allocation of new threads in g_thread_pool_push().
+ * A new thread is allocated, whenever the number of currently
* running threads in @pool is smaller than the maximal number.
*
- * @error can be NULL to ignore errors, or non-NULL to report
- * errors. An error can only occur, when a new thread couldn't be
+ * @error can be %NULL to ignore errors, or non-%NULL to report
+ * errors. An error can only occur when a new thread couldn't be
* created.
**/
void
*
* Frees all resources allocated for @pool.
*
- * If @immediate is #TRUE, no new task is processed for
+ * If @immediate is %TRUE, no new task is processed for
* @pool. Otherwise @pool is not freed before the last task is
* processed. Note however, that no thread of this pool is
* interrupted, while processing a task. Instead at least all still
* running threads can finish their tasks before the @pool is freed.
*
- * If @wait is #TRUE, the functions does not return before all tasks
+ * If @wait is %TRUE, the functions does not return before all tasks
* to be processed (dependent on @immediate, whether all or only the
* currently running) are ready. Otherwise the function returns immediately.
*
* Inserts a key/value pair into a #GTree. If the given key already exists
* in the #GTree its corresponding value is set to the new value. If you
* supplied a value_destroy_func when creating the #GTree, the old value is
- * freed using that function. If you supplied a key_destroy_func when
+ * freed using that function. If you supplied a @key_destroy_func when
* creating the #GTree, the passed key is freed using that function.
*
* The tree is automatically 'balanced' as new key/value pairs are added,
*
* Inserts a new key and value into a #GTree similar to g_tree_insert().
* The difference is that if the key already exists in the #GTree, it gets
- * replaced by the new key. If you supplied a value_destroy_func when
+ * replaced by the new key. If you supplied a @value_destroy_func when
* creating the #GTree, the old value is freed using that function. If you
- * supplied a key_destroy_func when creating the #GTree, the old key is
+ * supplied a @key_destroy_func when creating the #GTree, the old key is
* freed using that function.
*
* The tree is automatically 'balanced' as new key/value pairs are added,
* Removes a key/value pair from a #GTree.
*
* If the #GTree was created using g_tree_new_full(), the key and value
- * are freed using the supplied destroy_functions, otherwise you have to
+ * are freed using the supplied @destroy_functions, otherwise you have to
* make sure that any dynamically allocated values are freed yourself.
**/
void
* @value: returns the value associated with the key.
*
* Looks up a key in the #GTree, returning the original key and the
- * associated value and a gboolean which is TRUE if the key was found. This
+ * associated value and a #gboolean which is %TRUE if the key was found. This
* is useful if you need to free the memory allocated for the original key,
* for example before calling g_tree_remove().
*
- * Return value: #TRUE if the key was found in the #GTree.
+ * Return value: %TRUE if the key was found in the #GTree.
**/
gboolean
g_tree_lookup_extended (GTree *tree,
* To search for a specific value, you can use g_tree_foreach() or
* g_tree_traverse().
*
- * Return value: the value corresponding to the found key, or NULL if the key
+ * Return value: the value corresponding to the found key, or %NULL if the key
* is not found.
**/
gpointer
projects / platform / upstream / glib.git / commitdiff