+2007-03-18 Matthias Clasen <mclasen@redhat.com>
+
+ * glib/tmpl/thread_pools.sgml:
+ * glib/tmpl/strings.sgml:
+ * glib/tmpl/string_chunks.sgml:
+ * glib/tmpl/spawn.sgml:
+ * glib/tmpl/patterns.sgml:
+ * glib/tmpl/modules.sgml:
+ * glib/tmpl/memory_slices.sgml:
+ * glib/tmpl/memory.sgml:
+ * glib/tmpl/gregex.sgml: Trivial cleanups
+
2007-03-16 Matthias Clasen <mclasen@redhat.com>
* === Released 2.13.0 ===
<!-- ##### MACRO ftruncate ##### -->
<para>
-Provided for UNIX emulation on Windows; see documentation for <function>ftruncate()</function>
+Provided for UNIX emulation on Windows; see documentation for ftruncate()
in any UNIX manual.
</para>
Error codes returned by regular expressions functions.
</para>
-@G_REGEX_ERROR_COMPILE: Compilation of the regular expression in <function>g_regex_new()</function> failed.
-@G_REGEX_ERROR_OPTIMIZE: Optimization of the regular expression in <function>g_regex_optimize()</function> failed.
+@G_REGEX_ERROR_COMPILE: Compilation of the regular expression in g_regex_new() failed.
+@G_REGEX_ERROR_OPTIMIZE: Optimization of the regular expression in g_regex_optimize() failed.
@G_REGEX_ERROR_REPLACE: Replacement failed due to an ill-formed replacement string.
@G_REGEX_ERROR_MATCH: The match process failed.
@Since: 2.14
<!-- ##### 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
-<function>alloca()</function> function present on most UNIX variants.
-Thus it provides the same advantages and pitfalls as <function>alloca()</function>:
+stack frame is cleaned up. This macro essentially just wraps the alloca()
+function present on most UNIX variants.
+Thus it provides the same advantages and pitfalls as alloca():
<variablelist>
<varlistentry><term></term><listitem><para>
- + <function>alloca()</function> is very fast, as on most systems it's implemented by just adjusting
+ + alloca() 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>
- + It doesn't cause any memory fragmentation, within its scope, separate <function>alloca()</function>
+ + It doesn't cause any memory fragmentation, within its scope, separate alloca()
blocks just build up and are released together at function end.
</para></listitem></varlistentry>
<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 <function>alloca()</function> uses.
+ so be sparse with alloca() 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 <function>malloc()</function>. Instead, most systems probably handle it the same
+ return like e.g. with malloc(). Instead, most systems probably handle it the same
way as out of stack space situations from infinite function recursion, i.e.
with a segmentation fault.
</para></listitem></varlistentry>
<varlistentry><term></term><listitem><para>
- - 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
+ - Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
+ Stack space allocated with alloca() in the same scope as a variable sized array
will be freed together with the variable sized array upon exit of that scope, and
not upon exit of the enclosing function scope.
</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. <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
-function has been called.
+custom memory allocation routines. <emphasis>This function must be called
+before using any other GLib functions.</emphasis> The @vtable only needs to
+provide malloc(), realloc(), and free() functions; GLib can provide default
+implementations of the others. The malloc() and realloc() implementations
+should return %NULL on failure, GLib will handle error-checking for you.
+@vtable is copied, so need not persist after this function has been called.
</para>
@vtable: table of memory allocation routines.
<para>
Allocates a block of memory from the slice allocator.
The block adress handed out is guaranteed to be aligned
-to at least 2 * sizeof (void*).
+to at least <literal>2 * sizeof (void*)</literal>.
Note that the underlying slice allocation mechanism can
be changed with the <link linkend="G_SLICE">G_SLICE=always-malloc</link>
environment variable.
<!-- ##### MACRO g_slice_new ##### -->
<para>
A convenience macro to allocate a block of memory from the slice allocator.
-It calls g_slice_alloc() with sizeof (@type) and casts the returned pointer
-to a pointer of the given type, avoiding a type cast in the source code.
+It calls g_slice_alloc() with <literal>sizeof (@type)</literal> and casts
+the returned pointer to a pointer of the given type, avoiding a type cast
+in the source code.
Note that the underlying slice allocation mechanism can
be changed with the <link linkend="G_SLICE">G_SLICE=always-malloc</link>
environment variable.
<!-- ##### MACRO g_slice_new0 ##### -->
<para>
A convenience macro to allocate a block of memory from the slice allocator
-and set the memory to 0. It calls g_slice_alloc0() with sizeof (@type) and
-casts the returned pointer to a pointer of the given type, avoiding a type
-cast in the source code.
+and set the memory to 0. It calls g_slice_alloc0() with
+<literal>sizeof (@type)</literal> and casts the returned pointer to a pointer
+of the given type, avoiding a type cast in the source code.
Note that the underlying slice allocation mechanism can
be changed with the <link linkend="G_SLICE">G_SLICE=always-malloc</link>
environment variable.
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 <function>dlopen()</function> (e.g. Linux/Sun), as well as HP-UX via its
-<function>shl_load()</function> mechanism, and Windows platforms via DLLs.
+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>
Note also that the reverse of a UTF-8 encoded string can in general
<emphasis>not</emphasis> be obtained by g_strreverse().
This works only if the string doesn't contain any multibyte characters.
-Glib offers the g_utf_strreverse() function to reverse UTF-8 encoded strings.
+Glib offers the g_utf8_strreverse() function to reverse UTF-8 encoded strings.
</para>
@pspec: a #GPatternSpec.
Spawning Processes
<!-- ##### SECTION Short_Description ##### -->
-process launching with <function>fork()</function>/<function>exec()</function>.
+process launching with fork()/exec().
<!-- ##### SECTION Long_Description ##### -->
<para>
@G_SPAWN_ERROR_FORK: Fork failed due to lack of memory.
@G_SPAWN_ERROR_READ: Read or select on pipes failed.
@G_SPAWN_ERROR_CHDIR: Changing to working directory failed.
-@G_SPAWN_ERROR_ACCES: <function>execv()</function> returned %EACCES.
-@G_SPAWN_ERROR_PERM: <function>execv()</function> returned %EPERM.
-@G_SPAWN_ERROR_2BIG: <function>execv()</function> returned %E2BIG.
-@G_SPAWN_ERROR_NOEXEC: <function>execv()</function> returned %ENOEXEC.
-@G_SPAWN_ERROR_NAMETOOLONG: <function>execv()</function> returned %ENAMETOOLONG.
-@G_SPAWN_ERROR_NOENT: <function>execv()</function> returned %ENOENT.
-@G_SPAWN_ERROR_NOMEM: <function>execv()</function> returned %ENOMEM.
-@G_SPAWN_ERROR_NOTDIR: <function>execv()</function> returned %ENOTDIR.
-@G_SPAWN_ERROR_LOOP: <function>execv()</function> returned %ELOOP.
-@G_SPAWN_ERROR_TXTBUSY: <function>execv()</function> returned %ETXTBUSY.
-@G_SPAWN_ERROR_IO: <function>execv()</function> returned %EIO.
-@G_SPAWN_ERROR_NFILE: <function>execv()</function> returned %ENFILE.
-@G_SPAWN_ERROR_MFILE: <function>execv()</function> returned %EMFILE.
-@G_SPAWN_ERROR_INVAL: <function>execv()</function> returned %EINVAL.
-@G_SPAWN_ERROR_ISDIR: <function>execv()</function> returned %EISDIR.
-@G_SPAWN_ERROR_LIBBAD: <function>execv()</function> returned %ELIBBAD.
+@G_SPAWN_ERROR_ACCES: execv() returned %EACCES.
+@G_SPAWN_ERROR_PERM: execv() returned %EPERM.
+@G_SPAWN_ERROR_2BIG: execv() returned %E2BIG.
+@G_SPAWN_ERROR_NOEXEC: execv() returned %ENOEXEC.
+@G_SPAWN_ERROR_NAMETOOLONG: execv() returned %ENAMETOOLONG.
+@G_SPAWN_ERROR_NOENT: execv() returned %ENOENT.
+@G_SPAWN_ERROR_NOMEM: execv() returned %ENOMEM.
+@G_SPAWN_ERROR_NOTDIR: execv() returned %ENOTDIR.
+@G_SPAWN_ERROR_LOOP: execv() returned %ELOOP.
+@G_SPAWN_ERROR_TXTBUSY: execv() returned %ETXTBUSY.
+@G_SPAWN_ERROR_IO: execv() returned %EIO.
+@G_SPAWN_ERROR_NFILE: execv() returned %ENFILE.
+@G_SPAWN_ERROR_MFILE: execv() returned %EMFILE.
+@G_SPAWN_ERROR_INVAL: execv() returned %EINVAL.
+@G_SPAWN_ERROR_ISDIR: execv() returned %EISDIR.
+@G_SPAWN_ERROR_LIBBAD: execv() returned %ELIBBAD.
@G_SPAWN_ERROR_FAILED: Some other fatal failure, <literal>error->message</literal> should explain.
<!-- ##### MACRO G_SPAWN_ERROR ##### -->
@G_SPAWN_LEAVE_DESCRIPTORS_OPEN: the parent's open file descriptors will be
inherited by the child; otherwise all descriptors except stdin/stdout/stderr
- will be closed before calling <function>exec()</function> in the child.
+ will be closed before calling exec() in the child.
@G_SPAWN_DO_NOT_REAP_CHILD: the child will not be automatically reaped; you
- must use g_child_watch_add() yourself (or call <function>waitpid()</function>
+ must use g_child_watch_add() yourself (or call waitpid()
or handle <literal>SIGCHLD</literal> yourself), or the child will become a zombie.
@G_SPAWN_SEARCH_PATH: <literal>argv[0]</literal> need not be an absolute path,
it will be looked for in the user's <envar>PATH</envar>.
Specifies the type of the setup function passed to g_spawn_async(),
g_spawn_sync() and g_spawn_async_with_pipes(). On POSIX platforms it
is called in the child after GLib has performed all the setup it plans
-to perform but before calling <function>exec()</function>. On POSIX
-actions taken in this function will thus only affect the child, not
-the parent.
+to perform but before calling exec(). On POSIX actions taken in this
+function will thus only affect the child, not the parent.
</para>
<para>
</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.
+than using g_strdup() since fewer calls to malloc() 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
access any of the strings which were contained within it.
</para>
-@chunk: a #GStringChunk.
-
+@chunk: a #GStringChunk
<!-- ##### FUNCTION g_printf_string_upper_bound ##### -->
<para>
-Calculates the maximum space needed to store the output of the sprintf() function.
+Calculates the maximum space needed to store the output of the sprintf()
+function.
</para>
@format: the format string. See the printf() documentation.
If the signal is unknown, it returns "unknown signal (<signum>)".
The string can only be used until the next call to g_strsignal().
-
<!-- ##### 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 nul byte.
-</para>
-<para>
-The <structfield>str</structfield> field is nul-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:
-@len:
+@str: points to the character data. It may move as text is added.
+The <structfield>str</structfield> field is nul-terminated and so
+can be used as an ordinary C string.
+@len: contains the length of the string, not including the terminating nul byte.
@allocated_len:
<!-- ##### FUNCTION g_string_new ##### -->
For use with #GHashTable.
</para>
-@v: a #GString.
-@v2: another #GString.
+@v: a #GString
+@v2: another #GString
@Returns: %TRUE if they strings are the same length and contain the same bytes.
<!-- ##### SECTION Long_Description ##### -->
<para>
-Sometimes you wish to asyncronously fork out the execution of work and
+Sometimes you wish to asynchronously fork out the execution of work and
continue working in your own thread. If that will happen often, the
-overhead of starting and destroying a thread each time might be to
+overhead of starting and destroying a thread each time might be too
high. In such cases reusing already started threads seems like a good
idea. And it indeed is, but implementing this can be tedious and
error-prone.
Tries to lock @mutex. If @mutex is already locked by another thread,
it immediately returns %FALSE. Otherwise it locks @mutex and returns
%TRUE. If @mutex is already locked by the calling thread, this
-functions increases the depth of @mutex and immediately returns %TRUE.
+functions increases the depth of @mutex and immediately returns %TRUE.
</para>
@mutex: a #GStaticRecMutex to lock.
if (!current_number)
{
- current_number = g_new (int,1);
+ current_number = g_new (int, 1);
*current_number = 0;
g_private_set (current_number_key, current_number);
}
<para>
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 <structname>GNode</structname> with the
-same parent).
-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
-<structname>GNode</structname>. The other children are accessed by using the
-<structfield>next</structfield> pointer of each child.
-</para>
-
-@data:
-@next:
-@prev:
-@parent:
-@children:
+fields
+</para>
+
+@data: contains the actual data of the node.
+@next: points to the node's next sibling (a sibling is another
+ <structname>GNode</structname> with the same parent).
+@prev: points to the node's previous sibling.
+@parent: points to the parent of the <structname>GNode</structname>,
+ or is %NULL if the <structname>GNode</structname> is the root of the tree.
+@children: The <structfield>children</structfield> field points to the first
+ child of the <structname>GNode</structname>. The other children are accessed
+ by using the <structfield>next</structfield> pointer of each child.
<!-- ##### FUNCTION g_node_new ##### -->
<para>
g_message(), g_warning() and g_error().
</para>
-@format: the message format. See the <function>printf()</function>
-documentation.
+@format: the message format. See the printf() documentation.
@Varargs: the parameters to insert into the format string.
be used, or the convenience functions g_message(), g_warning() and g_error().
</para>
-@format: the message format. See the <function>printf()</function>
-documentation.
+@format: the message format. See the printf() documentation.
@Varargs: the parameters to insert into the format string.
<!-- ##### MACRO pipe ##### -->
<para>
-Provided for UNIX emulation on Windows; see documentation for <function>pipe()</function>
+Provided for UNIX emulation on Windows; see documentation for pipe()
in any UNIX manual.
</para>
<!-- ##### MACRO G_WIN32_DLLMAIN_FOR_DLL_NAME ##### -->
<para>
-On Windows, this macro defines a <function>DllMain()</function> function
-that stores the actual DLL name that the code being compiled will be
-included in.
+On Windows, this macro defines a DllMain() function that stores the actual
+DLL name that the code being compiled will be included in.
</para>
<para>
On non-Windows platforms, expands to nothing.
projects / platform / upstream / glib.git / commitdiff