mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-03-03 06:32:10 +01:00
consistently refer to GTK+.
* glib/tmpl/caches.sgml, glib/tmpl/datalist.sgml, glib/tmpl/hash_tables.sgml, glib/tmpl/messages.sgml, glib/tmpl/misc_utils.sgml: consistently refer to GTK+. * glib/tmpl/error_reporting.sgml, glib/tmpl/fileutils.sgml, glib/tmpl/windows.sgml, glib/tmpl/modules.sgml, glib/tmpl/linked_lists_single.sgml, glib/tmpl/trees-nary.sgml, glib/tmpl/trees-binary.sgml, glib/tmpl/timers.sgml: Markup fixes.
This commit is contained in:
Matthias Clasen
parent
7282810dd9
commit
a6e1fafdc9
@ -1,3 +1,14 @@
|
||||
2001-10-01 Matthias Clasen <matthiasc@poet.de>
|
||||
|
||||
* glib/tmpl/caches.sgml, glib/tmpl/datalist.sgml,
|
||||
glib/tmpl/hash_tables.sgml, glib/tmpl/messages.sgml,
|
||||
glib/tmpl/misc_utils.sgml: consistently refer to GTK+.
|
||||
|
||||
* glib/tmpl/error_reporting.sgml, glib/tmpl/fileutils.sgml,
|
||||
glib/tmpl/windows.sgml, glib/tmpl/modules.sgml,
|
||||
glib/tmpl/linked_lists_single.sgml, glib/tmpl/trees-nary.sgml,
|
||||
glib/tmpl/trees-binary.sgml, glib/tmpl/timers.sgml: Markup fixes.
|
||||
|
||||
2001-09-30 Matthias Clasen <matthiasc@poet.de>
|
||||
|
||||
* glib/tmpl/arrays.sgml,glib/tmpl/arrays_byte.sgml
|
||||
|
||||
@ -10,7 +10,7 @@ A #GCache allows sharing of complex data structures, in order to save
|
||||
system resources.
|
||||
</para>
|
||||
<para>
|
||||
GTK uses a #GCache for both GtkStyles and GdkGCs. These consume a lot of
|
||||
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
|
||||
required properties already exists. If it does, then the existing
|
||||
GtkStyle or GdkGC is used instead of creating a new one.
|
||||
|
||||
@ -14,7 +14,7 @@ The #GQuark methods are quicker, since the strings have to be converted to
|
||||
#GQuarks anyway.
|
||||
</para>
|
||||
<para>
|
||||
Data lists are used in GTK for associating arbitrary data with
|
||||
Data lists are used in GTK+ for associating arbitrary data with
|
||||
GtkObjects, using gtk_object_set_data() and related functions.
|
||||
</para>
|
||||
|
||||
|
||||
@ -42,7 +42,7 @@ For example:
|
||||
<programlisting>
|
||||
gchar* g_file_get_contents (const gchar *filename, GError **error);
|
||||
</programlisting>
|
||||
If you pass a non-NULL value for the <literal>error</literal> argument, it should
|
||||
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>
|
||||
gchar *contents;
|
||||
@ -65,14 +65,14 @@ else
|
||||
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
|
||||
convention that a NULL return value means an error occurred (but not
|
||||
convention that a %NULL return value means an error occurred (but not
|
||||
all functions use this convention).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Because g_file_get_contents() returns NULL on failure, if you are only
|
||||
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:
|
||||
can pass %NULL for the <literal>error</literal> argument:
|
||||
<programlisting>
|
||||
contents = g_file_get_contents ("foo.txt", NULL); /* ignore errors */
|
||||
if (contents != NULL)
|
||||
@ -88,10 +88,10 @@ the module the error-reporting function is located in, <literal>code</literal>
|
||||
indicates the specific error that occurred, and <literal>message</literal> is a
|
||||
user-readable error message with as many details as possible. Several functions
|
||||
are provided to deal with an error received from a called function:
|
||||
g_error_matches() returns TRUE if the error matches a given domain and code,
|
||||
g_error_matches() returns %TRUE if the error matches a given domain and code,
|
||||
g_propagate_error() copies an error into an error location (so the calling
|
||||
function will receive it), and g_clear_error() clears an error location by
|
||||
freeing the error and resetting the location to NULL. To display an error to the
|
||||
freeing the error and resetting the location to %NULL. To display an error to the
|
||||
user, simply display <literal>error->message</literal>, perhaps along with
|
||||
additional context known only to the calling function (the file being opened, or
|
||||
whatever -- though in the g_file_get_contents() case,
|
||||
@ -102,7 +102,7 @@ whatever -- though in the g_file_get_contents() case,
|
||||
When implementing a function that can report errors, the basic tool is
|
||||
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:
|
||||
to it is %NULL. Here's an example:
|
||||
<programlisting>
|
||||
gint
|
||||
foo_open_file (GError **error)
|
||||
@ -129,7 +129,7 @@ foo_open_file (GError **error)
|
||||
<para>
|
||||
Things are somewhat more complicated if you yourself call another function that
|
||||
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
|
||||
other than reporting a #GError, such as by returning %TRUE on success, you can
|
||||
simply do the following:
|
||||
<programlisting>
|
||||
gboolean
|
||||
@ -152,7 +152,7 @@ my_function_that_can_fail (GError **err)
|
||||
|
||||
<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.
|
||||
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>
|
||||
gboolean
|
||||
@ -201,12 +201,12 @@ my_function_that_can_fail (GError **err)
|
||||
}
|
||||
</programlisting>
|
||||
<literal>tmp_error</literal> should be checked immediately after
|
||||
sub_function_that_can_fail(), and either cleared or propagated upward. The rule
|
||||
<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
|
||||
calling function</emphasis>. Note that passing NULL for the error location is the
|
||||
calling function</emphasis>. Note that passing %NULL for the error location is the
|
||||
equivalent of handling an error by always doing nothing about it. So the
|
||||
following code is fine, assuming errors in sub_function_that_can_fail() are not
|
||||
fatal to my_function_that_can_fail():
|
||||
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>
|
||||
gboolean
|
||||
my_function_that_can_fail (GError **err)
|
||||
@ -230,7 +230,7 @@ my_function_that_can_fail (GError **err)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Note that passing NULL for the error location <emphasis>ignores</emphasis>
|
||||
Note that passing %NULL for the error location <emphasis>ignores</emphasis>
|
||||
errors; it's equivalent to <literal>try { sub_function_that_can_fail (); } catch
|
||||
(...) {}</literal> in C++. It does <emphasis>not</emphasis> mean to leave errors
|
||||
unhandled; it means to handle them by doing nothing.
|
||||
@ -289,17 +289,17 @@ Summary of rules for use of #GError:
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
The caller may pass NULL for the #GError** if they are not interested
|
||||
The caller may pass %NULL for the #GError** if they are not interested
|
||||
in details of the exact error that occurred.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
If NULL is passed for the #GError** argument, then errors should
|
||||
If %NULL is passed for the #GError** argument, then errors should
|
||||
not be returned to the caller, but your function should still
|
||||
abort and return if an error occurs. That is, control flow should
|
||||
not be affected by whether the caller wants to get a #GError.
|
||||
not be affected by whether the caller wants to get a #GError.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
@ -315,7 +315,7 @@ Summary of rules for use of #GError:
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
A #GError* must be initialized to NULL before passing its address to
|
||||
A #GError* must be initialized to %NULL before passing its address to
|
||||
a function that can report errors.
|
||||
</para>
|
||||
</listitem>
|
||||
@ -323,7 +323,7 @@ Summary of rules for use of #GError:
|
||||
<listitem>
|
||||
<para>
|
||||
"Piling up" errors is always a bug. That is, if you assign a new
|
||||
#GError to a #GError* that is non-NULL, thus overwriting the previous
|
||||
#GError to a #GError* that is non-%NULL, thus overwriting the previous
|
||||
error, it indicates that you should have aborted the operation instead
|
||||
of continuing. If you were able to continue, you should have cleared
|
||||
the previous error with g_clear_error(). g_set_error() will complain
|
||||
@ -335,17 +335,17 @@ Summary of rules for use of #GError:
|
||||
<listitem>
|
||||
<para>
|
||||
By convention, if you return a boolean value indicating success
|
||||
then TRUE means success and FALSE means failure. If FALSE is returned,
|
||||
the error <emphasis>must</emphasis> be set to a non-NULL value.
|
||||
then %TRUE means success and %FALSE means failure. If %FALSE is returned,
|
||||
the error <emphasis>must</emphasis> be set to a non-%NULL value.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
A NULL return value is also frequently used to mean that an error
|
||||
occurred. You should make clear in your documentation whether NULL is
|
||||
a valid return value in non-error cases; if NULL is a valid value,
|
||||
A %NULL return value is also frequently used to mean that an error
|
||||
occurred. You should make clear in your documentation whether %NULL is
|
||||
a valid return value in non-error cases; if %NULL is a valid value,
|
||||
then users must check whether an error was returned to see if the
|
||||
function succeeded.
|
||||
</para>
|
||||
@ -355,7 +355,7 @@ Summary of rules for use of #GError:
|
||||
<para>
|
||||
When implementing a function that can report errors, you may want to
|
||||
add a check at the top of your function that the error return location
|
||||
is either NULL or contains a NULL error
|
||||
is either %NULL or contains a %NULL error
|
||||
(e.g. <literal>g_return_if_fail (error == NULL || *error ==
|
||||
NULL);</literal>).
|
||||
</para>
|
||||
@ -375,9 +375,9 @@ Summary of rules for use of #GError:
|
||||
|
||||
</para>
|
||||
|
||||
@domain: error domain, e.g. #G_FILE_ERROR
|
||||
@code: error code, e.g. %G_FILE_ERROR_NOENT
|
||||
@message: human-readable informative error message
|
||||
@domain: error domain, e.g. #G_FILE_ERROR.
|
||||
@code: error code, e.g. %G_FILE_ERROR_NOENT.
|
||||
@message: human-readable informative error message.
|
||||
|
||||
<!-- ##### FUNCTION g_error_new ##### -->
|
||||
<para>
|
||||
|
||||
@ -16,9 +16,9 @@ File Utilities
|
||||
|
||||
<!-- ##### ENUM GFileError ##### -->
|
||||
<para>
|
||||
Values corresponding to "errno" codes returned from file operations on
|
||||
UNIX. Unlike errno codes, #GFileError values are available on all
|
||||
systems, even Windows. The exact meaning of each code depends on what
|
||||
Values corresponding to <literal>errno</literal> codes returned from file operations
|
||||
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
|
||||
gives more details. The following error code descriptions come
|
||||
from the GNU C Library manual, and are under the copyright
|
||||
|
||||
@ -15,7 +15,7 @@ very quickly.
|
||||
Note that neither keys nor values are copied when inserted into the
|
||||
#GHashTable, so they must exist for the lifetime of the #GHashTable.
|
||||
This means that the use of static strings is OK, but temporary
|
||||
strings (i.e. those created in buffers and those returned by GTK widgets)
|
||||
strings (i.e. those created in buffers and those returned by GTK+ widgets)
|
||||
should be copied with g_strdup() before being inserted.
|
||||
</para>
|
||||
<para>
|
||||
|
||||
@ -34,8 +34,8 @@ the first element in the list. The functions which insert elements return
|
||||
the new start of the list, which may have changed.
|
||||
</para>
|
||||
<para>
|
||||
There is no function to create a #GSList. NULL is considered to be the empty
|
||||
list so you simply set a #GSList* to NULL.
|
||||
There is no function to create a #GSList. %NULL is considered to be the empty
|
||||
list so you simply set a #GSList* to %NULL.
|
||||
</para>
|
||||
<para>
|
||||
To add elements, use g_slist_append(), g_slist_prepend(), g_slist_insert()
|
||||
@ -155,10 +155,10 @@ to the end of the list.
|
||||
Inserts a node before @sibling containing @data. Returns the new head of the list.
|
||||
</para>
|
||||
|
||||
@slist: a #GSList
|
||||
@sibling: node to insert @data before
|
||||
@data: data to put in the newly-inserted node
|
||||
@Returns: new head of the list
|
||||
@slist: a #GSList.
|
||||
@sibling: node to insert @data before.
|
||||
@data: data to put in the newly-inserted node.
|
||||
@Returns: new head of the list.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_slist_insert_sorted ##### -->
|
||||
@ -190,7 +190,7 @@ If none of the elements contain the data, the #GSList is unchanged.
|
||||
<!-- ##### FUNCTION g_slist_remove_link ##### -->
|
||||
<para>
|
||||
Removes an element from a #GSList, without freeing the element.
|
||||
The removed element's next link is set to NULL, so that it becomes a
|
||||
The removed element's next link is set to %NULL, so that it becomes a
|
||||
self-contained list with one element.
|
||||
</para>
|
||||
|
||||
@ -204,9 +204,9 @@ self-contained list with one element.
|
||||
Deletes a node of @list. Returns the new list head.
|
||||
</para>
|
||||
|
||||
@list: a #GSList
|
||||
@link: node to delete
|
||||
@Returns: new head of @list
|
||||
@list: a #GSList.
|
||||
@link: node to delete.
|
||||
@Returns: new head of @list.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_slist_remove_all ##### -->
|
||||
@ -216,9 +216,9 @@ head of the list. Contrast with g_slist_remove() which removes only
|
||||
the first node matching the given data.
|
||||
</para>
|
||||
|
||||
@list: a #GSList
|
||||
@data: data to remove
|
||||
@Returns: new head of @list
|
||||
@list: a #GSList.
|
||||
@data: data to remove.
|
||||
@Returns: new head of @list.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_slist_free ##### -->
|
||||
@ -276,10 +276,7 @@ Sorts a #GSList using the given comparison function.
|
||||
</para>
|
||||
|
||||
@list: a #GSList.
|
||||
@compare_func: the comparison function used to sort the #GSList. This function
|
||||
is passed 2 elements of the #GSList and should return 0 if they are equal,
|
||||
a negative value if the first element comes before the second, or a positive
|
||||
value if the first element comes after the second.
|
||||
@compare_func: <function>qsort()</function>-style comparison function.
|
||||
@Returns: the start of the sorted #GList.
|
||||
|
||||
|
||||
@ -289,9 +286,9 @@ Like g_slist_sort(), but the sort function accepts a user data argument.
|
||||
</para>
|
||||
|
||||
@list: a #GSList
|
||||
@compare_func: qsort()-style comparison function
|
||||
@user_data: data to pass to comparison function
|
||||
@Returns: new head of the list
|
||||
@compare_func: comparison function.
|
||||
@user_data: data to pass to comparison function.
|
||||
@Returns: new head of the list.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_slist_concat ##### -->
|
||||
@ -322,7 +319,7 @@ Gets the last element in a #GSList.
|
||||
</para>
|
||||
|
||||
@list: a #GSList.
|
||||
@Returns: the last element in the #GSList, or NULL if the #GSList has no
|
||||
@Returns: the last element in the #GSList, or %NULL if the #GSList has no
|
||||
elements.
|
||||
|
||||
|
||||
@ -332,7 +329,7 @@ A convenience macro to gets the next element in a #GSList.
|
||||
</para>
|
||||
|
||||
@slist: an element in a #GSList.
|
||||
@Returns: the next element, or NULL if there are no more elements.
|
||||
@Returns: the next element, or %NULL if there are no more elements.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_slist_nth ##### -->
|
||||
@ -342,7 +339,7 @@ Gets the element at the given position in a #GSList.
|
||||
|
||||
@list: a #GSList.
|
||||
@n: the position of the element, counting from 0.
|
||||
@Returns: the element, or NULL if the position is off the end of the #GSList.
|
||||
@Returns: the element, or %NULL if the position is off the end of the #GSList.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_slist_nth_data ##### -->
|
||||
@ -352,7 +349,7 @@ Gets the data of the element at the given position.
|
||||
|
||||
@list: a #GSList.
|
||||
@n: the position of the element.
|
||||
@Returns: the element's data, or NULL if the position is off the end of the
|
||||
@Returns: the element's data, or %NULL if the position is off the end of the
|
||||
#GSList.
|
||||
|
||||
|
||||
@ -363,7 +360,7 @@ Finds the element in a #GSList which contains the given data.
|
||||
|
||||
@list: a #GSList.
|
||||
@data: the element data to find.
|
||||
@Returns: the found #GSList element, or NULL if it is not found.
|
||||
@Returns: the found #GSList element, or %NULL if it is not found.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_slist_find_custom ##### -->
|
||||
@ -380,7 +377,7 @@ and the given user data.
|
||||
@data: user data passed to the function.
|
||||
@func: the function to call for each element. It should return 0 when the
|
||||
desired element is found.
|
||||
@Returns: the found #GSList element, or NULL if it is not found.
|
||||
@Returns: the found #GSList element, or %NULL if it is not found.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_slist_position ##### -->
|
||||
|
||||
@ -29,7 +29,7 @@ be differentiated from messages from other libraries and application code.
|
||||
But be careful not to define it in any public header files.
|
||||
</para>
|
||||
<para>
|
||||
For example, GTK uses this in its Makefile.am:
|
||||
For example, GTK+ uses this in its Makefile.am:
|
||||
</para>
|
||||
<informalexample><programlisting>
|
||||
INCLUDES = \
|
||||
|
||||
@ -17,9 +17,9 @@ These are portable utility functions.
|
||||
<!-- ##### FUNCTION g_get_prgname ##### -->
|
||||
<para>
|
||||
Gets the name of the program.
|
||||
(If you are using GDK or GTK the program name is set in gdk_init(), which
|
||||
(If you are using GDK or GTK+ the program name is set in gdk_init(), which
|
||||
is called by gtk_init(). The program name is found by taking the last
|
||||
component of argv[0].)
|
||||
component of <literal>argv[0]</literal>.)
|
||||
</para>
|
||||
|
||||
@Returns: the name of the program.
|
||||
@ -39,7 +39,7 @@ Returns an environment variable.
|
||||
</para>
|
||||
|
||||
@variable: the environment variable to get.
|
||||
@Returns: the value of the environment variable, or NULL if the environment
|
||||
@Returns: the value of the environment variable, or %NULL if the environment
|
||||
variable is not found.
|
||||
|
||||
|
||||
@ -54,7 +54,7 @@ Gets the user name of the current user.
|
||||
<!-- ##### FUNCTION g_get_real_name ##### -->
|
||||
<para>
|
||||
Gets the real name of the user. This comes from the user's entry in the
|
||||
passwd file.
|
||||
<filename>passwd</filename> file.
|
||||
</para>
|
||||
|
||||
@Returns: the user's real name.
|
||||
@ -71,7 +71,8 @@ Gets the current user's home directory.
|
||||
<!-- ##### FUNCTION g_get_tmp_dir ##### -->
|
||||
<para>
|
||||
Gets the directory to use for temporary files.
|
||||
This is found from inspecting the environment variables TMPDIR, TMP, and TEMP
|
||||
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.
|
||||
</para>
|
||||
|
||||
@ -120,7 +121,7 @@ The returned string should be freed when no longer needed.
|
||||
|
||||
<!-- ##### FUNCTION g_path_is_absolute ##### -->
|
||||
<para>
|
||||
Returns TRUE if the given @file_name is an absolute file name,
|
||||
Returns %TRUE if the given @file_name is an absolute file name,
|
||||
i.e. it contains a full path from the root directory such as '/usr/local'
|
||||
or 'C:/windows' on windows systems.
|
||||
</para>
|
||||
@ -133,7 +134,7 @@ or 'C:/windows' on windows systems.
|
||||
<para>
|
||||
Returns a pointer into @file_name after the root component, i.e. after
|
||||
the '/' in Unix or 'C:/' under Windows. If @file_name is not an absolute
|
||||
path it returns NULL.
|
||||
path it returns %NULL.
|
||||
</para>
|
||||
|
||||
@file_name: a file name.
|
||||
@ -261,7 +262,7 @@ Specifies a function to be called at normal program termination.
|
||||
<para>
|
||||
Parses a string containing debugging options separated by ':' into a guint
|
||||
containing bit flags.
|
||||
This is used within GDK and GTK to parse the debug options passed on the
|
||||
This is used within GDK and GTK+ to parse the debug options passed on the
|
||||
command line or through environment variables.
|
||||
</para>
|
||||
|
||||
@ -295,7 +296,7 @@ Declares a type of function which takes an arbitrary data pointer argument
|
||||
and has no return value. It is not currently used in GLib or GTK+.
|
||||
</para>
|
||||
|
||||
@data:
|
||||
@data: a data pointer.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_qsort_with_data ##### -->
|
||||
|
||||
@ -9,13 +9,13 @@ portable method for dynamically loading 'plug-ins'.
|
||||
These functions provide a portable way to dynamically load object files
|
||||
(commonly known as 'plug-ins').
|
||||
The current implementation supports all systems that provide
|
||||
an implementation of dlopen() (e.g. Linux/Sun), as well as HP-UX via its
|
||||
shl_load() mechanism, and Windows platforms via DLLs.
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A program, which wants to use these functions must be linked to the
|
||||
libraries output by the command "glib-config --libs gmodule".
|
||||
libraries output by the command <command>glib-config --libs gmodule</command>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -37,7 +37,7 @@ module is loaded and unloaded (see #GModuleCheckInit and #GModuleUnload).
|
||||
</para>
|
||||
<para>
|
||||
If your module introduces static data to common subsystems in the running
|
||||
program, e.g. through calling g_quark_from_static_string ("my-module-stuff"),
|
||||
program, e.g. through calling <literal>g_quark_from_static_string ("my-module-stuff")</literal>,
|
||||
it must ensure that it is never unloaded, by calling g_module_make_resident().
|
||||
</para>
|
||||
|
||||
@ -59,7 +59,7 @@ It should only be accessed via the following functions.
|
||||
Checks if modules are supported on the current platform.
|
||||
</para>
|
||||
|
||||
@Returns: TRUE if modules are supported.
|
||||
@Returns: %TRUE if modules are supported.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_module_build_path ##### -->
|
||||
@ -70,18 +70,18 @@ added to the directory, using the correct separator character.
|
||||
</para>
|
||||
<para>
|
||||
The directory should specify the directory where the module can be found.
|
||||
It can be NULL or an empty string to indicate that the module is in a standard
|
||||
It can be %NULL or an empty string to indicate that the module is in a standard
|
||||
operating-system specific directory, though this is not recommended since the
|
||||
wrong module may be found.
|
||||
</para>
|
||||
<para>
|
||||
For example, calling g_module_build_path() on a Linux system with a directory
|
||||
of "/lib" and a module_name of "mylibrary" will return "/lib/libmylibrary.so".
|
||||
On a Windows system, using "\Windows" as the directory it will return
|
||||
"\Windows\mylibrary.dll".
|
||||
of <filename>/lib</filename> and a module_name of "mylibrary" will return <filename>/lib/libmylibrary.so</filename>.
|
||||
On a Windows system, using <filename>\Windows</filename> as the directory it will return
|
||||
<filename>\Windows\mylibrary.dll</filename>.
|
||||
</para>
|
||||
|
||||
@directory: the directory where the module is. This can be NULL or the empty
|
||||
@directory: the directory where the module is. This can be %NULL or the empty
|
||||
string to indicate that the standard operating system-specific directories
|
||||
will be used, though that is not recommended.
|
||||
@module_name: the name of the module.
|
||||
@ -97,28 +97,27 @@ count is incremented.
|
||||
|
||||
<para>
|
||||
First of all g_module_open() tries to open @file_name as a module. If
|
||||
that fails and @file_name has the ".la"-suffix (and is a libtool
|
||||
archive) it tries to open the corresponding module. If that fails and
|
||||
it doesn't have the proper module suffix for that plaform
|
||||
(#G_MODULE_SUFFIX,) this suffix will be appended and the coresponding
|
||||
module will be opended. If that fails and @file_name doesn't have the
|
||||
".la"-suffix, this suffix is appended and g_module_open() tries to
|
||||
open the corresponding module. If eventually that fails as well, NULL
|
||||
is returned.
|
||||
that fails and @file_name has the ".la"-suffix (and is a libtool archive)
|
||||
it tries to open the corresponding module. If that fails and it doesn't
|
||||
have the proper module suffix for that platform (#G_MODULE_SUFFIX), this
|
||||
suffix will be appended and the corresponding module will be opended. If
|
||||
that fails and @file_name doesn't have the ".la"-suffix, this suffix is
|
||||
appended and g_module_open() tries to open the corresponding module. If
|
||||
eventually that fails as well, %NULL is returned.
|
||||
</para>
|
||||
|
||||
@file_name: the name of the file containing the module.
|
||||
@flags: the flags used for opening the module. Currently this can be 0 or
|
||||
G_MODULE_BIND_LAZY for lazy binding, where symbols are only bound when needed.
|
||||
@Returns: a #GModule on success, or NULL on failure.
|
||||
#G_MODULE_BIND_LAZY for lazy binding, where symbols are only bound when needed.
|
||||
@Returns: a #GModule on success, or %NULL on failure.
|
||||
|
||||
|
||||
<!-- ##### ENUM GModuleFlags ##### -->
|
||||
<para>
|
||||
Flags passed to g_module_open().
|
||||
G_MODULE_BIND_LAZY specifies that symbols are only resolved when needed.
|
||||
#G_MODULE_BIND_LAZY specifies that symbols are only resolved when needed.
|
||||
The default action is to bind all symbols when the module is loaded.
|
||||
(G_MODULE_BIND_LAZY is not supported on all platforms.)
|
||||
(#G_MODULE_BIND_LAZY is not supported on all platforms.)
|
||||
</para>
|
||||
|
||||
@G_MODULE_BIND_LAZY:
|
||||
@ -132,7 +131,7 @@ Gets a symbol pointer from a module.
|
||||
@module: the module.
|
||||
@symbol_name: the name of the symbol to find.
|
||||
@symbol: returns the pointer to the symbol value.
|
||||
@Returns: TRUE on success.
|
||||
@Returns: %TRUE on success.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_module_name ##### -->
|
||||
@ -160,7 +159,7 @@ Closes a module.
|
||||
</para>
|
||||
|
||||
@module: the module to close.
|
||||
@Returns: TRUE on success.
|
||||
@Returns: %TRUE on success.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_module_error ##### -->
|
||||
@ -176,12 +175,12 @@ Gets a string describing the last module error.
|
||||
Specifies the type of the module initialization function.
|
||||
If a module contains a function named g_module_check_init() it is called
|
||||
automatically when the module is loaded. It is passed the #GModule structure
|
||||
and should return NULL on success or a string describing the initialization
|
||||
and should return %NULL on success or a string describing the initialization
|
||||
error.
|
||||
</para>
|
||||
|
||||
@module: the #GModule corresponding to the module which has just been loaded.
|
||||
@Returns: NULL on success, or a string describing the initialization error.
|
||||
@Returns: %NULL on success, or a string describing the initialization error.
|
||||
|
||||
|
||||
<!-- ##### USER_FUNCTION GModuleUnload ##### -->
|
||||
|
||||
@ -29,7 +29,7 @@ Creates a new timer, and starts timing (i.e. g_timer_start() is implicitly
|
||||
called for you).
|
||||
</para>
|
||||
|
||||
@Returns: a new #GTimer
|
||||
@Returns: a new #GTimer.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_timer_start ##### -->
|
||||
@ -40,7 +40,7 @@ start time, so no need to call g_timer_start() immediately after creating the
|
||||
timer.
|
||||
</para>
|
||||
|
||||
@timer: a #GTimer
|
||||
@timer: a #GTimer.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_timer_stop ##### -->
|
||||
@ -49,7 +49,7 @@ Marks an end time, so calls to g_timer_elapsed() will return the difference
|
||||
between this end time and the start time.
|
||||
</para>
|
||||
|
||||
@timer: a #GTimer
|
||||
@timer: a #GTimer.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_timer_elapsed ##### -->
|
||||
@ -61,9 +61,9 @@ seconds elapsed, and the @microseconds argument allows you to get the number of
|
||||
microseconds.
|
||||
</para>
|
||||
|
||||
@timer: a #GTimer
|
||||
@microseconds: return location for microseconds elapsed, or %NULL
|
||||
@Returns: seconds elapsed
|
||||
@timer: a #GTimer.
|
||||
@microseconds: return location for microseconds elapsed, or %NULL.
|
||||
@Returns: seconds elapsed.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_timer_reset ##### -->
|
||||
@ -73,7 +73,7 @@ already-started timer to reset the start time, so g_timer_reset() serves no
|
||||
purpose.
|
||||
</para>
|
||||
|
||||
@timer: a #GTimer
|
||||
@timer: a #GTimer.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_timer_destroy ##### -->
|
||||
@ -81,6 +81,6 @@ purpose.
|
||||
Destroys a timer, freeing associated resources.
|
||||
</para>
|
||||
|
||||
@timer: a #GTimer to destroy
|
||||
@timer: a #GTimer to destroy.
|
||||
|
||||
|
||||
|
||||
@ -174,13 +174,13 @@ It should be accessed only by using the following functions.
|
||||
Specifies the type of function passed to g_tree_traverse().
|
||||
It is passed the key and value of each node, together with
|
||||
the @user_data parameter passed to g_tree_traverse().
|
||||
If the function returns TRUE, the traversal is stopped.
|
||||
If the function returns %TRUE, the traversal is stopped.
|
||||
</para>
|
||||
|
||||
@key: a key of a #GTree node.
|
||||
@value: the value corresponding to the key.
|
||||
@data: user data passed to g_tree_traverse().
|
||||
@Returns: TRUE to stop the traversal.
|
||||
@Returns: %TRUE to stop the traversal.
|
||||
|
||||
|
||||
<!-- ##### ENUM GTraverseType ##### -->
|
||||
|
||||
@ -86,8 +86,8 @@ Recursively copies a #GNode (but does not deep-copy the data inside the nodes,
|
||||
since there's no way for GLib to know how to do that).
|
||||
</para>
|
||||
|
||||
@node: a #GNode
|
||||
@Returns: a new #GNode containing the same data pointers
|
||||
@node: a #GNode.
|
||||
@Returns: a new #GNode containing the same data pointers.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_node_insert ##### -->
|
||||
@ -108,7 +108,7 @@ Inserts a #GNode beneath the parent before the given sibling.
|
||||
</para>
|
||||
|
||||
@parent: the #GNode to place @node under.
|
||||
@sibling: the sibling #GNode to place @node before. If sibling is NULL,
|
||||
@sibling: the sibling #GNode to place @node before. If sibling is %NULL,
|
||||
the node is inserted as the last child of @parent.
|
||||
@node: the #GNode to insert.
|
||||
@Returns: the inserted #GNode.
|
||||
@ -120,7 +120,7 @@ Inserts a #GNode beneath the parent after the given sibling.
|
||||
</para>
|
||||
|
||||
@parent: the #GNode to place @node under.
|
||||
@sibling: the sibling #GNode to place @node after. If sibling is NULL,
|
||||
@sibling: the sibling #GNode to place @node after. If sibling is %NULL,
|
||||
the node is inserted as the first child of @parent.
|
||||
@node: the #GNode to insert.
|
||||
@Returns: the inserted #GNode.
|
||||
@ -202,7 +202,7 @@ Reverses the order of the children of a #GNode.
|
||||
<para>
|
||||
Traverses a tree starting at the given root #GNode.
|
||||
It calls the given function for each node visited.
|
||||
The traversal can be halted at any point by returning TRUE from @func.
|
||||
The traversal can be halted at any point by returning %TRUE from @func.
|
||||
</para>
|
||||
|
||||
@root: the root #GNode of the tree to traverse.
|
||||
@ -245,12 +245,12 @@ including g_node_traverse() and g_node_find().
|
||||
Specifies the type of function passed to g_node_traverse().
|
||||
The function is called with each of the nodes visited, together with the
|
||||
user data passed to g_node_traverse().
|
||||
If the function returns TRUE, then the traversal is stopped.
|
||||
If the function returns %TRUE, then the traversal is stopped.
|
||||
</para>
|
||||
|
||||
@node: a #GNode.
|
||||
@data: user data passed to g_node_traverse().
|
||||
@Returns: TRUE to stop the traversal.
|
||||
@Returns: %TRUE to stop the traversal.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_node_children_foreach ##### -->
|
||||
@ -297,7 +297,7 @@ Finds a #GNode in a tree.
|
||||
@flags: which types of children are to be searched, one of %G_TRAVERSE_ALL,
|
||||
%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS.
|
||||
@data: the data to find.
|
||||
@Returns: the found #GNode, or NULL if the data is not found.
|
||||
@Returns: the found #GNode, or %NULL if the data is not found.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_node_find_child ##### -->
|
||||
@ -309,7 +309,7 @@ Finds the first child of a #GNode with the given data.
|
||||
@flags: which types of children are to be searched, one of %G_TRAVERSE_ALL,
|
||||
%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS.
|
||||
@data: the data to find.
|
||||
@Returns: the found child #GNode, or NULL if the data is not found.
|
||||
@Returns: the found child #GNode, or %NULL if the data is not found.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_node_child_index ##### -->
|
||||
@ -341,7 +341,7 @@ Gets the first child of a #GNode.
|
||||
</para>
|
||||
|
||||
@node: a #GNode.
|
||||
@Returns: the last child of @node, or NULL if @node is NULL or has no children.
|
||||
@Returns: the last child of @node, or %NULL if @node is %NULL or has no children.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_node_last_child ##### -->
|
||||
@ -349,14 +349,14 @@ Gets the first child of a #GNode.
|
||||
Gets the last child of a #GNode.
|
||||
</para>
|
||||
|
||||
@node: a #GNode (must not be NULL).
|
||||
@Returns: the last child of @node, or NULL if @node has no children.
|
||||
@node: a #GNode (must not be %NULL).
|
||||
@Returns: the last child of @node, or %NULL if @node has no children.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_node_nth_child ##### -->
|
||||
<para>
|
||||
Gets a child of a #GNode, using the given index.
|
||||
The first child is at index 0. If the index is too big, NULL is returned.
|
||||
The first child is at index 0. If the index is too big, %NULL is returned.
|
||||
</para>
|
||||
|
||||
@node: a #GNode.
|
||||
@ -380,7 +380,7 @@ Gets the next sibling of a #GNode.
|
||||
</para>
|
||||
|
||||
@node: a #GNode.
|
||||
@Returns: the next sibling of @node, or NULL if @node is NULL.
|
||||
@Returns: the next sibling of @node, or %NULL if @node is %NULL.
|
||||
|
||||
|
||||
<!-- ##### MACRO g_node_prev_sibling ##### -->
|
||||
@ -389,7 +389,7 @@ Gets the previous sibling of a #GNode.
|
||||
</para>
|
||||
|
||||
@node: a #GNode.
|
||||
@Returns: the previous sibling of @node, or NULL if @node is NULL.
|
||||
@Returns: the previous sibling of @node, or %NULL if @node is %NULL.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_node_last_sibling ##### -->
|
||||
@ -404,20 +404,20 @@ This could possibly be the node itself.
|
||||
|
||||
<!-- ##### MACRO G_NODE_IS_LEAF ##### -->
|
||||
<para>
|
||||
Returns TRUE if a #GNode is a leaf node.
|
||||
Returns %TRUE if a #GNode is a leaf node.
|
||||
</para>
|
||||
|
||||
@node: a #GNode.
|
||||
@Returns: TRUE if the #GNode is a leaf node (i.e. it has no children).
|
||||
@Returns: %TRUE if the #GNode is a leaf node (i.e. it has no children).
|
||||
|
||||
|
||||
<!-- ##### MACRO G_NODE_IS_ROOT ##### -->
|
||||
<para>
|
||||
Returns TRUE if a #GNode is the root of a tree.
|
||||
Returns %TRUE if a #GNode is the root of a tree.
|
||||
</para>
|
||||
|
||||
@node: a #GNode.
|
||||
@Returns: TRUE if the #GNode is the root of a tree (i.e. it has no parent
|
||||
@Returns: %TRUE if the #GNode is the root of a tree (i.e. it has no parent
|
||||
or siblings).
|
||||
|
||||
|
||||
@ -426,7 +426,7 @@ or siblings).
|
||||
Gets the depth of a #GNode.
|
||||
</para>
|
||||
<para>
|
||||
If @node is NULL the depth is 0.
|
||||
If @node is %NULL the depth is 0.
|
||||
The root node has a depth of 1.
|
||||
For the children of the root node the depth is 2. And so on.
|
||||
</para>
|
||||
@ -457,14 +457,14 @@ Gets the number of children of a #GNode.
|
||||
|
||||
<!-- ##### FUNCTION g_node_is_ancestor ##### -->
|
||||
<para>
|
||||
Returns TRUE if @node is an ancestor of @descendant.
|
||||
This is true if node is the parent of descendant, or if node is the
|
||||
grandparent of descendant etc.
|
||||
Returns %TRUE if @node is an ancestor of @descendant.
|
||||
This is true if node is the parent of @descendant, or if node is the
|
||||
grandparent of @descendant etc.
|
||||
</para>
|
||||
|
||||
@node: a #GNode.
|
||||
@descendant: a #GNode.
|
||||
@Returns: TRUE if @node is an ancestor of @descendant.
|
||||
@Returns: %TRUE if @node is an ancestor of @descendant.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_node_max_height ##### -->
|
||||
@ -473,7 +473,7 @@ Gets the maximum height of all branches beneath a #GNode.
|
||||
This is the maximum distance from the #GNode to all leaf nodes.
|
||||
</para>
|
||||
<para>
|
||||
If @root is NULL, 0 is returned. If @root has no children, 1 is returned.
|
||||
If @root is %NULL, 0 is returned. If @root has no children, 1 is returned.
|
||||
If @root has children, 2 is returned. And so on.
|
||||
</para>
|
||||
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!-- ##### SECTION Title ##### -->
|
||||
Windows Compatability Functions
|
||||
Windows Compatibility Functions
|
||||
|
||||
<!-- ##### SECTION Short_Description ##### -->
|
||||
|
||||
@ -17,7 +17,7 @@ Windows Compatability Functions
|
||||
<!-- ##### MACRO MAXPATHLEN ##### -->
|
||||
<para>
|
||||
Provided for UNIX emulation on Windows; equivalent to UNIX
|
||||
macro MAXPATHLEN, which is the maximum length of a filename
|
||||
macro %MAXPATHLEN, which is the maximum length of a filename
|
||||
(including full path).
|
||||
</para>
|
||||
|
||||
@ -26,8 +26,8 @@ macro MAXPATHLEN, which is the maximum length of a filename
|
||||
<!-- ##### MACRO NAME_MAX ##### -->
|
||||
<para>
|
||||
Provided for UNIX emulation on Windows; equivalent to UNIX macro
|
||||
NAME_MAX, which is the maximum length of a single path component.
|
||||
i.e. just the "foo" in "/usr/bin/foo".
|
||||
%NAME_MAX, which is the maximum length of a single path component.
|
||||
i.e. just the <filename>foo</filename> in <filename>/usr/bin/foo</filename>.
|
||||
</para>
|
||||
|
||||
|
||||
@ -40,7 +40,7 @@ Provided for UNIX emulation on Windows; process ID type.
|
||||
|
||||
<!-- ##### MACRO pipe ##### -->
|
||||
<para>
|
||||
Provided for UNIX emulation on Windows; see documentation for pipe()
|
||||
Provided for UNIX emulation on Windows; see documentation for <function>pipe()</function>
|
||||
in any UNIX manual.
|
||||
</para>
|
||||
|
||||
@ -49,7 +49,7 @@ in any UNIX manual.
|
||||
|
||||
<!-- ##### MACRO ftruncate ##### -->
|
||||
<para>
|
||||
Provided for UNIX emulation on Windows; see documentation for ftruncate()
|
||||
Provided for UNIX emulation on Windows; see documentation for <function>ftruncate()</function>
|
||||
in any UNIX manual.
|
||||
</para>
|
||||
|
||||
@ -59,7 +59,7 @@ in any UNIX manual.
|
||||
|
||||
<!-- ##### MACRO opendir ##### -->
|
||||
<para>
|
||||
Provided for UNIX emulation on Windows; see documentation for opendir()
|
||||
Provided for UNIX emulation on Windows; see documentation for <function>opendir()</function>
|
||||
in any UNIX manual.
|
||||
</para>
|
||||
|
||||
@ -67,7 +67,7 @@ in any UNIX manual.
|
||||
|
||||
<!-- ##### MACRO readdir ##### -->
|
||||
<para>
|
||||
Provided for UNIX emulation on Windows; see documentation for readdir()
|
||||
Provided for UNIX emulation on Windows; see documentation for <function>readdir()</function>
|
||||
in any UNIX manual.
|
||||
</para>
|
||||
|
||||
@ -75,7 +75,7 @@ in any UNIX manual.
|
||||
|
||||
<!-- ##### MACRO rewinddir ##### -->
|
||||
<para>
|
||||
Provided for UNIX emulation on Windows; see documentation for rewinddir()
|
||||
Provided for UNIX emulation on Windows; see documentation for <function>rewinddir()</function>
|
||||
in any UNIX manual.
|
||||
</para>
|
||||
|
||||
@ -83,7 +83,7 @@ in any UNIX manual.
|
||||
|
||||
<!-- ##### MACRO closedir ##### -->
|
||||
<para>
|
||||
Provided for UNIX emulation on Windows; see documentation for closedir()
|
||||
Provided for UNIX emulation on Windows; see documentation for <function>closedir()</function>
|
||||
in any UNIX manual.
|
||||
</para>
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user