glib-man 2.0.1.24




README

The glib-man project is a helper project stemming from the apparent lack of man pages for glib/gtk/gnome functions. The usual programmer wants to have a quick look when using a function and in that process be warned of problems and hinted with tricks to follow. These pages have come to be from a code review of glib 2.0.1, so they tell you about it, frankly.

Just pick up the latest tarball and RPMs from the download section of http://freespace.sf.net

have fun, "guidod"



INSTALL

You need the "xmlto" package to create man pages. This one in turn will require you to install the latest docbook-xsl stylesheets and the gnome's xslt-proc from the libxml arena.

Theoretically, a number of html pages and other document types could be created as well but they are in fact not at the moment - it is just for the man pages.



COPYING

/*
 *    Author:
 *         Guido Draheim 
 *
 *    Copyright: (c) 2002 Guido Draheim
 *         All Rights Reserved.
 *         Reproduction Prohibited.
 *         Download Only From Project Home.
 *
 */

You are allowed to download the sources, to modify them, and recompile
them, but only on your local system. You can download premade RPMs
from the project home too. You can recompile the source RPM. 

You are not allowed to copy parts or the entire material into another
project, or even release it under your name or as part of any other
of your projects. After direct download from the internet, you may
not copy it elsewhere, do not put it on hard transport media, do not
copy it to any other internet place or website.

The glib/gnome doc guys seem to be "not competent enough" to do even
as simple thing as to produce usable man page for the programmers
in the world. Everyone needs it to write good glib software of course.

I did ask for man pages, there are none. I did ask for help in
creating some, there was no help. I did ask for guidelines to have
things started, there were no counsel. I had to make it all on
my own, making a code review from byte zero. I have done it for 
myself because I did need to memorize somehow the problems and 
tricks about glib functions.

I did it and published it so that other programmers can have a
chance to use man pages - and man pages which frankly tell you 
what to look out for. There are indeed some problems within glib
that some of you may not have known about. The docs are by far
not complete but helpful even in the state they are now.

I have created a lot of opensource software, and in general I would
have published this one under LGPL or FDL but not now. Not for this
one because I do not want the glib/gnome people to get hold of these 
man page documentation and take credit for it. They simply do not 
deserve it.

Still you are free to use this software and to modify it as you
wish - and I would be glad to hear of any parts where you did start
to memorize things about glib functions. Just send those parts to
me and I'll include them and publish them along. Be sure however
that I need the freedom to re-license this project later under an
LGPL or FDL as soon as this project has woken up some ignorant people 
in the glib/gnome world.

The message to them is: 
   WE NEED GOOD DOCUMENTATION.
   WE WANT PROPER MAN PAGES.
   STOP IGNORING THIS NEED.


DOCUMENTATION

glib-man -2.0.1.24

GHashTable*    g_hash_table_new   1000 (GHashFunc hash_func, GEqualFunc key_equal_func)
GHashTable*    g_hash_table_new_full   1000 (GHashFunc hash_func, GEqualFunc key_equal_func, GDestroyNotify key_destroy_func, GDestroyNotify value_destroy_func)
void    g_hash_table_destroy   g_hash_table_destroy (GHashTable *hash_table)
void    g_hash_table_foreach   g_hash_table_foreach (GHashTable *hash_table, GHFunc func, gpointer user_data)
guint    g_hash_table_foreach_remove   g_hash_table_foreach_remove (GHashTable *hash_table, GHRFunc func, gpointer user_data)
guint    g_hash_table_foreach_steal   g_hash_table_foreach_steal (GHashTable *hash_table, GHRFunc func, gpointer steal)
gboolean    g_hash_table_remove   g_hash_table_remove (GHashTable *hash_table, gconstpointer key)
gboolean    g_hash_table_steal   g_hash_table_steal (GHashTable *hash_table, gconstpointer key)
void    g_hash_table_freeze   g_hash_table_freeze (GHashTable *hash_table)
void    g_hash_table_thaw   g_hash_table_thaw (GHashTable *hash_table)
gboolean    g_str_equal   g_str_equal (gconstpointer v, gconstpointer v2)
guint    g_str_hash   g_str_hash (gconstpointer v)
gboolean    g_int_equal   g_int_equal (gconstpointer v, gconstpointer v2)
guint    g_int_hash   g_int_hash (gconstpointer v)
gboolean    g_direct_equal   g_direct_equal (gconstpointer v, gconstpointer v2)
guint    g_direct_hash   g_direct_hash (gconstpointer v)
guint    g_hash_table_size   g_hash_table_size (GHashTable *hash_table)
gpointer    g_hash_table_lookup   g_hash_table_lookup (GHashTable *hash_table, gconstpointer key)
gboolean    g_hash_table_lookup_extended   g_hash_table_lookup_extended (GHashTable *hash_table, gconstpointer lookup_key, gpointer *orig_key, gpointer *value)
void    g_hash_table_insert   g_hash_table_insert (GHashTable *hash_table, gpointer key, gpointer value)
void    g_hash_table_replace   g_hash_table_replace (GHashTable *hash_table, gpointer key, gpointer value)
GPtrArray*    g_ptr_array_new   g_ptr_array_new (void)
GPtrArray*    g_ptr_array_sized_new   g_ptr_array_sized_new (guint reserved_size)
gpointer*    g_ptr_array_free   g_ptr_array_free (GPtrArray *array, gboolean free_seg)
void    g_ptr_array_add   g_ptr_array_add (GPtrArray *array, gpointer data)
void    g_ptr_array_set_size   g_ptr_array_set_size (GPtrArray *array, gint length)
gpointer*    g_ptr_array_index   g_ptr_array_index (GPtrArray* array, gint index)
gpointer    g_ptr_array_remove_index   g_ptr_array_remove_index (GPtrArray *array, guint index)
gpointer    g_ptr_array_remove_index_fast   g_ptr_array_remove_index_fast (GPtrArray *array, guint index)
gboolean    g_ptr_array_remove   g_ptr_array_remove (GPtrArray *array, gpointer data)
gboolean    g_ptr_array_remove_fast   g_ptr_array_remove_fast (GPtrArray *array, gpointer data)
void    g_ptr_array_sort   g_ptr_array_sort (GPtrArray *array, GCompareFunc compare_func)
void    g_ptr_array_sort_with_data   g_ptr_array_sort_with_data (GPtrArray *array, GCompareDataFunc compare_func, gpointer user_data)
GString*    g_string_new   g_string_new (const gchar *init)
GString*    g_string_sized_new   g_string_sized_new (gsize dfl_size)
GString*    g_string_append_len   g_string_append_len (GString *string, const gchar *val, gssize len)
gchar*    g_string_free   g_string_free (GString *string, gboolean free_seg)
GIOError    g_io_channel_write   g_io_channel_write (GIOChannel *channel, const gchar *buf, gsize count, gsize *bytes_written)
GIOStatus    g_io_channel_write_chars   g_io_channel_write_chars (GIOChannel *channel, const gchar *buf, gssize count, gsize *bytes_written, GError **error)
GIOStatus    g_io_channel_write_unichar   g_io_channel_write_unichar (GIOChannel *channel, gunichar thechar, GError **error)
GIOStatus    g_io_channel_set_encoding   g_io_channel_set_encoding (GIOChannel *channel, const gchar *encoding, GError **error)
void*    g_alloca   g_alloca (size_t size)
type*    g_newa   g_newa (typename type, size_t factor)
gboolean    g_file_test   g_file_test (const gchar *filename, GFileTest test)
GFileError    g_file_error_from_errno   g_file_error_from_errno (gint err_no)
gboolean    g_file_get_contents   g_file_get_contents (const gchar *filename, gchar **contents, gsize *length, GError **error)
int    g_mkstemp   g_mkstemp (char *tmpl)
int    g_file_open_tmp   g_file_open_tmp (const char *tmpl, char **name_used, GError **error)
gchar *    g_build_path   g_build_path (const gchar *separator, const gchar *first_element, ...)
gchar *    g_build_filename   g_build_filename (const gchar *first_element, ...)
gpointer    g_malloc   g_malloc (gulong n_bytes)
gpointer    g_malloc0   g_malloc0 (gulong n_bytes)
gpointer    g_realloc   g_realloc (gpointer mem, gulong n_bytes)
void    g_free   g_free (gpointer mem)
gpointer    g_try_malloc   g_try_malloc (gulong n_bytes)
gpointer    g_try_realloc   g_try_realloc (gpointer mem, gulong n_bytes)
struct_type*    g_new   g_new (typename struct_type, gsize n_structs)
struct_type*    g_new0   g_new0 (typename struct_type, gsize n_structs)
struct_type*    g_renew0   g_renew0 (typename struct_type, gpointer mem, gsize n_structs)
void    g_mem_set_vtable   g_mem_set_vtable (GMemVTable *vtable)
gboolean    g_mem_is_system_malloc   g_mem_is_system_malloc (void)
void    g_mem_profile   g_mem_profile (void)
GMemChunk*    g_mem_chunk_new   g_mem_chunk_new (const gchar *name, gint atom_size, gulong area_size, gint type)
void    g_mem_chunk_destroy   g_mem_chunk_destroy (GMemChunk *mem_chunk)
gpointer    g_mem_chunk_alloc   g_mem_chunk_alloc (GMemChunk *mem_chunk)
gpointer    g_mem_chunk_alloc0   g_mem_chunk_alloc0 (GMemChunk *mem_chunk)
void    g_mem_chunk_free   g_mem_chunk_free (GMemChunk *mem_chunk, gpointer mem)
void    g_mem_chunk_clean   g_mem_chunk_clean (GMemChunk *mem_chunk)
void    g_mem_chunk_reset   g_mem_chunk_reset (GMemChunk *mem_chunk)
void    g_mem_chunk_print   g_mem_chunk_print (GMemChunk *mem_chunk)
void    g_mem_chunk_info   g_mem_chunk_info (void)
void    g_blow_chunks   g_blow_chunks (void)
GAllocator*    g_allocator_new   g_allocator_new (const gchar *name, guint n_preallocs)
void    g_allocator_free   g_allocator_free (GAllocator *allocator)
GMemChunk*    g_mem_chunk_create   g_mem_chunk_create (typename type, gsize pre_alloc, gint alloc_type)
type*    g_chunk_new   g_chunk_new (typename type, GMemChunk* chunk)
type*    g_chunk_new0   g_chunk_new0 (typename type, GMemChunk* chunk)
void    g_chunk_free   g_chunk_free (gpointer mem, GMemChunk* mem_chunk)
GError*    g_error_new   g_error_new (GQuark domain, gint code, const gchar *format, ...)
GError*    g_error_new_literal   g_error_new_literal (GQuark domain, gint code, const gchar *message)
void    g_error_free   g_error_free (GError *error)
GError*    g_error_copy   g_error_copy (const GError *error)
gboolean    g_error_matches   g_error_matches (const GError *error, GQuark domain, gint code)
void    g_set_error   g_set_error (GError **err, GQuark domain, gint code, const gchar *format, ...)
void    g_propagate_error   g_propagate_error (GError **dest, GError *src)
void    g_clear_error   g_clear_error (GError **err)
guint16    g_ascii_isalpha   g_ascii_isalpha (guchar c)
guint16    g_ascii_isalnum   g_ascii_isalnum (guchar c)
guint16    g_ascii_iscntrl   g_ascii_iscntrl (guchar c)
guint16    g_ascii_isdigit   g_ascii_isdigit (guchar c)
guint16    g_ascii_isgraph   g_ascii_isgraph (guchar c)
guint16    g_ascii_islower   g_ascii_islower (guchar c)
guint16    g_ascii_isprint   g_ascii_isprint (guchar c)
guint16    g_ascii_ispunct   g_ascii_ispunct (guchar c)
guint16    g_ascii_isspace   g_ascii_isspace (guchar c)
guint16    g_ascii_isupper   g_ascii_isupper (guchar c)
guint16    g_ascii_isxdigit   g_ascii_isxdigit (guchar c)
gchar    g_ascii_tolower   g_ascii_tolower (gchar c) G_GNUC_CONST
gchar    g_ascii_toupper   g_ascii_toupper (gchar c) G_GNUC_CONST
gint    g_ascii_digit_value   g_ascii_digit_value (gchar c) G_GNUC_CONST
gint    g_ascii_xdigit_value   g_ascii_xdigit_value (gchar c) G_GNUC_CONST
gchar*    g_strdelimit   g_strdelimit (gchar *string, const gchar *delimiters, gchar new_delimiter)
gchar*    g_strcanon   g_strcanon (gchar *string, const gchar *valid_chars, gchar substitutor)
const gchar*    g_strerror   g_strerror (gint errnum)
gchar*    g_strreverse   g_strreverse (gchar *string)
gsize    g_strlcpy   g_strlcpy (gchar *dest, const gchar *src, gsize dest_size)
gsize    g_strlcat   g_strlcat (gchar *dest, const gchar *src, gsize dest_size)
gchar *    g_strstr_len   g_strstr_len (const gchar *haystack, gssize haystack_len, const gchar *needle)
gchar *    g_strrstr   g_strrstr (const gchar *haystack, const gchar *needle)
gchar *    g_strrstr_len   g_strrstr_len (const gchar *haystack, gssize haystack_len, const gchar *needle)
gdouble    g_strtod   g_strtod (const gchar *nptr, gchar **endptr)
gdouble    g_ascii_strtod   g_ascii_strtod (const gchar *nptr, gchar **endptr)
#define G_ASCII_DTOSTR_BUF_SIZE (29 + 10) gchar *    g_ascii_dtostr   g_ascii_dtostr (gchar *buffer, gint buf_len, gdouble d)
gchar *    g_ascii_formatd   g_ascii_formatd (gchar *buffer, gint buf_len, const gchar *format, gdouble d)
gchar*    g_strchug   g_strchug (gchar *string)
gchar*    g_strstrip   g_strstrip (gchar *string)
gint    g_ascii_strcasecmp   g_ascii_strcasecmp (const gchar *s1, const gchar *s2)
gint    g_ascii_strncasecmp   g_ascii_strncasecmp (const gchar *s1, const gchar *s2, gsize n)
gchar*    g_ascii_strdown   g_ascii_strdown (const gchar *str, gssize len)
gchar*    g_ascii_strup   g_ascii_strup (const gchar *str, gssize len)
gint    g_strcasecmp   g_strcasecmp (const gchar *s1, const gchar *s2)
gint    g_strncasecmp   g_strncasecmp (const gchar *s1, const gchar *s2, guint n)
gchar*    g_strdown   g_strdown (gchar *string)
gchar*    g_strup   g_strup (gchar *string)
gchar*    g_strdup   g_strdup (const gchar *str)
gchar*    g_strdup_printf   g_strdup_printf (const gchar *format, ...)
gchar*    g_strdup_vprintf   g_strdup_vprintf (const gchar *format, va_list args)
gchar*    g_strndup   g_strndup (const gchar *str, gsize n)
gchar*    g_strnfill   g_strnfill (gsize length, gchar fill_char)
gchar*    g_strconcat   g_strconcat (const gchar *string1, ...)
gchar*    g_strjoin   g_strjoin (const gchar *separator, ...)
gchar*    g_strcompress   g_strcompress (const gchar *source)
gchar*    g_strescape   g_strescape (const gchar *source, const gchar *exceptions)
gpointer    g_memdup   g_memdup (gconstpointer mem, guint byte_size)
gchar**    g_strsplit   g_strsplit (const gchar *string, const gchar *delimiter, gint max_tokens)
gchar*    g_strjoinv   g_strjoinv (const gchar *separator, gchar **str_array)
void    g_strfreev   g_strfreev (gchar **str_array)
gchar**    g_strdupv   g_strdupv (gchar **str_array)
gchar*    g_stpcpy   g_stpcpy (gchar *dest, const char *src)
GDir *    g_dir_open   g_dir_open (const gchar *path, guint flags, GError **error)
const gchar *   g_dir_read_name   g_dir_read_name (GDir *dir)
void    g_dir_rewind   g_dir_rewind (GDir *dir)
void    g_dir_close   g_dir_close (GDir *dir)
GMarkupParseContext *    g_markup_parse_context_new   g_markup_parse_context_new (const GMarkupParser *parser, GMarkupParseFlags flags, gpointer user_data, GDestroyNotify user_data_dnotify)
void    g_markup_parse_context_free   g_markup_parse_context_free (GMarkupParseContext *context)
void    g_markup_parse_context_get_position   g_markup_parse_context_get_position (GMarkupParseContext *context, gint *line_number, gint *char_number)
gchar*    g_markup_escape_text   g_markup_escape_text (const gchar *text, gssize length)
void    g_markup_parser.text   g_markup_parser.text (GMarkupParseContext *context, const gchar *text, gsize text_len, gpointer user_data, GError **error)
void    g_markup_parser.start_element   g_markup_parser.start_element (GMarkupParseContext *context, const gchar *element_name, const gchar **attribute_names, const gchar **attribute_values, gpointer user_data, GError **error)
void    g_markup_parser.end_element   g_markup_parser.end_element (GMarkupParseContext *context, const gchar *element_name, gpointer user_data, GError **error)
void    g_markup_parser.passthrough   g_markup_parser.passthrough (GMarkupParseContext *context, const gchar *passthrough_text, gsize text_len, gpointer user_data, GError **error)
void    g_markup_parser.error   g_markup_parser.error (GMarkupParseContext *context, GError *error, gpointer user_data)

Documentation

GHashTable*
g_hash_table_new   1000 (GHashFunc hash_func, GEqualFunc key_equal_func)

GHashTable*
g_hash_table_new_full   1000 (GHashFunc hash_func, GEqualFunc key_equal_func, GDestroyNotify key_destroy_func, GDestroyNotify value_destroy_func)

void
g_hash_table_destroy   g_hash_table_destroy (GHashTable *hash_table)

  creates a new GHashTable.

Two function references are required, the GHashFunc is defined as
guint (*GHashFunc) (gconstpointer) and each element to be
inserted into the hash_table will be checked with this function for
a good choice of the hash-bucket to store the item into. It should
be a fast function, the returned integer is take modulo the current
bucket-size (a prime number). Hopefully this creates an even
distribution across the hash buckets. You will find a few of
predefined hash functions declared for your convenience (and used
within the lib too):
g_direct_hash g_int_hash g_str_hash

The other function is a GEqualFunc may take more execution time, the
gboolean (*GEqualFunc) (gconstpointer a, gconstpointer b)
shall report equality of keys which is used to test whether a given
key does already exist in the bucket chosen by the GHashFunc. The
next g_hash_table_replace will use it to look for existance just
g_hash_table_lookup uses this function stored in the GHashTable
handle.

(ghash.c)

void
g_hash_table_foreach   g_hash_table_foreach (GHashTable *hash_table, GHFunc func, gpointer user_data)

guint
g_hash_table_foreach_remove   g_hash_table_foreach_remove (GHashTable *hash_table, GHRFunc func, gpointer user_data)

guint
g_hash_table_foreach_steal   g_hash_table_foreach_steal (GHashTable *hash_table, GHRFunc func, gpointer steal)

  call the given function for each key/value pair.

This function calls the given GHFunc function being defined as
void (*GHFunc) (gpointer key, gpointer value, gpointer user_data)
for each key and value with the one user_data provided with the call.

(ghash.c)

gboolean
g_hash_table_remove   g_hash_table_remove (GHashTable *hash_table, gconstpointer key)

gboolean
g_hash_table_steal   g_hash_table_steal (GHashTable *hash_table, gconstpointer key)

  remove a key/value from a hash-table

The node identified by the key shall be destroyed. This includes
calls to the item-destroyers that one has possibly registered with
g_hash_table_new_full - otherwise be sure to handle allocated
data somewhere else. The return value describes whether the key
did in fact identify a node that was removed. If it is false, then
there was no such assoc item stored in the table and no action was taken.

(ghash.c)

void
g_hash_table_freeze   g_hash_table_freeze (GHashTable *hash_table)

void
g_hash_table_thaw   g_hash_table_thaw (GHashTable *hash_table)

  it does nothing

This function does nothing, it was used to optimize when the algorithm
for re-balancing of the hash-tree was inferior and too much consuming.
This is not needed anymore as each insert/delete does the right thing.

(ghash.c)

gboolean
g_str_equal   g_str_equal (gconstpointer v, gconstpointer v2)

guint
g_str_hash   g_str_hash (gconstpointer v)

gboolean
g_int_equal   g_int_equal (gconstpointer v, gconstpointer v2)

guint
g_int_hash   g_int_hash (gconstpointer v)

gboolean
g_direct_equal   g_direct_equal (gconstpointer v, gconstpointer v2)

guint
g_direct_hash   g_direct_hash (gconstpointer v)

  used in g_hash_table_new

It is very common to use strings as keys of a hash table, and
you can use this function as the equal-test func-argument to the
g_hash_table_new, it is just a simple wrapper around strcmp.

(ghash.c)

guint
g_hash_table_size   g_hash_table_size (GHashTable *hash_table)

  number of elements

This function returns the number of key/value pairs in the
hash-table. A
g_hash_table_foreach call will walk along
that number of items.

(ghash.c)

gpointer
g_hash_table_lookup   g_hash_table_lookup (GHashTable *hash_table, gconstpointer key)

gboolean
g_hash_table_lookup_extended   g_hash_table_lookup_extended (GHashTable *hash_table, gconstpointer lookup_key, gpointer *orig_key, gpointer *value)

  Looks up a value by key

Checks for an item matching the given key (see the equal-arg
during
g_hash_table_new), and it such a key is found then the
associated value is returned. If the key seems not to be present
then a NULL pointer is returned - which can be used also as a
presence-test.

(ghash.c)

void
g_hash_table_insert   g_hash_table_insert (GHashTable *hash_table, gpointer key, gpointer value)

void
g_hash_table_replace   g_hash_table_replace (GHashTable *hash_table, gpointer key, gpointer value)

  insert a key/value pair

This function inserts a new key/value pair into the hash-table.

It is safe to call this function with a key that does already
exist - in that case the old-value is unlinked (with the destroyer
supplied at
g_hash_table_new_full) and replaced with the new
value. And from the two keys, the old key is kept and the arg
key is unlinked. Therefore, many insert-operations will always
keep the key of the first succesfull insert-operation under that key.

No return argument informs about the two possibities. (design flaw).

(ghash.c)

GPtrArray*
g_ptr_array_new   g_ptr_array_new (void)

GPtrArray*
g_ptr_array_sized_new   g_ptr_array_sized_new (guint reserved_size)

gpointer*
g_ptr_array_free   g_ptr_array_free (GPtrArray *array, gboolean free_seg)

  make GPtrArray

This function is a lot simpler than g_array_new where the exported
GArray has only two fields but the internal GRealArray has six fields.
The GRealPtrArray has only three fields as opposed to the two exported
fields (the third fields is "gint alloc" for the currently allocated
size as opposed to the current length - to minimize the number of
reallocs while calling
g_ptr_array_set_size ). A call to this
function will only allocate the handle, all fields are zero including
the pdata-field that is initially left null.

The return value will never be null - the implementation does not
check for null-return of allocs either, and an OOM condition will
therefore result in an SIGSEGV before returning. (design flaw).

(garray.c)

void
g_ptr_array_add   g_ptr_array_add (GPtrArray *array, gpointer data)

void
g_ptr_array_set_size   g_ptr_array_set_size (GPtrArray *array, gint length)

gpointer*
g_ptr_array_index   g_ptr_array_index (GPtrArray* array, gint index)

  new entries

This function append the given item to the end of the internal
array. It will automatically increase the handle-len by one
and it does run a internal realloc on the ptr-array if that
is necessary.

Again, this function does not return anything, an implicit
realloc will make for SIGSEGV before returning anyway, and so
this function will always succeed or continue in a crash handler
elsewhere (design flaw).

(garray.c)

gpointer
g_ptr_array_remove_index   g_ptr_array_remove_index (GPtrArray *array, guint index)

  extract an item

This function removes the given index from the ptr-array. If it was
not the last element then all later pointers are moved down to fill
the place. Finally the len-field is decreased by one to match the
new length. No
g_realloc occurs internally, just a g_memmmove.

The return value of this function is the pointer that was found at
the given index. If the array-arg was bad or the index beyond the
current field-len then a fail-null is returned.

(garray.c)

gboolean
g_ptr_array_remove   g_ptr_array_remove (GPtrArray *array, gpointer data)

gpointer
g_ptr_array_remove_index_fast   g_ptr_array_remove_index_fast (GPtrArray *array, guint index)

gboolean
g_ptr_array_remove_fast   g_ptr_array_remove_fast (GPtrArray *array, gpointer data)

  removing items

This function searches into the ptr-array for the first occurence
of the arg-pointer. If it exists then it is removed and a TRUE
flag returned, otherwise FALSE will be returned.

(garray.c)

void
g_ptr_array_sort   g_ptr_array_sort (GPtrArray *array, GCompareFunc compare_func)

void
g_ptr_array_sort_with_data   g_ptr_array_sort_with_data (GPtrArray *array, GCompareDataFunc compare_func, gpointer user_data)

  sort it

It sorts the ptr-array - actually a thin wrapper around the
posix qsort().

(garray.c)

GString*
g_string_new   g_string_new (const gchar *init)

GString*
g_string_sized_new   g_string_sized_new (gsize dfl_size)

GString*
g_string_append_len   g_string_append_len (GString *string, const gchar *val, gssize len)

gchar*
g_string_free   g_string_free (GString *string, gboolean free_seg)

  make a string

This function will call first g_string_sized_new to reserve
enough memory that a following call to g_string_append can
use to initialize the new GString.

You can use an empty string as an argument to have atleast
the internal char-array allocated always. (Up to glib 2.0.1 there
is a bogus implementation using a strlen(init)+2 arg in the call
to g_string_sized_new where the length is chopped (coding flaw)).

(gstring.c)

GIOError
g_io_channel_write   g_io_channel_write (GIOChannel *channel, const gchar *buf, gsize count, gsize *bytes_written)

GIOStatus
g_io_channel_write_chars   g_io_channel_write_chars (GIOChannel *channel, const gchar *buf, gssize count, gsize *bytes_written, GError **error)

GIOStatus
g_io_channel_write_unichar   g_io_channel_write_unichar (GIOChannel *channel, gunichar thechar, GError **error)

  writing

The given buffer/count pair is written. The number of bytes_written
is returned - it is an output-arg and may not be left empty.

This function returns a GIOError status where the other two write
functions return a GIOStatus - a null means success here. Furthermore
this function has been called to be depracated in glib 2.0.x.

(giochannel.c)

GIOStatus
g_io_channel_set_encoding   g_io_channel_set_encoding (GIOChannel *channel, const gchar *encoding, GError **error)

 (giochannel.c)

The encoding-string will only get effective when the channel
is not in flux - it should not hold some temporary buffers or
be in the middle of a read-unichar-deencoding or writechar
encoding. There are number of occassions that apply to this
(like just after creation of the string), but it is generally
okay for seekable strings - as it is with null encoding (i.e.
data streams) and utf8 encoding (which is the glib internal
encoding).

If you wonder what encoding-strings should be used then have
a look at libiconv that provides standard unix98 iconv(3)
for systems that do not implement it yet. The strings are just
subject to iconv_open(3) as wrapped through g_iconv_open.

The lib itself has some convenience to handle locale_to_utf8
so one will mostly not need to run strings through iconv(3).
Some of the unicode encoding can be handled with shortcut
routines right here.

Here's a copy of glib/libcharset/config.charset of encoding-aliases:

 | # The table consists of lines of the form
| #    ALIAS  CANONICAL
| #
| # ALIAS is the (system dependent) result of "nl_langinfo (CODESET)".
| # ALIAS is compared in a case sensitive way.
| #
| # CANONICAL is the GNU canonical name for this character encoding.
| # It must be an encoding supported by libiconv. Support by GNU libc is
| # also desirable. CANONICAL is case insensitive. Usually an upper case
| # MIME charset name is preferred.
| # The current list of GNU canonical charset names is as follows.
| #
| #       name                         used by which systems         a MIME name?
| #   ASCII, ANSI_X3.4-1968     glibc solaris freebsd
| #   ISO-8859-1                glibc aix hpux irix osf solaris freebsd   yes
| #   ISO-8859-2                glibc aix hpux irix osf solaris freebsd   yes
| #   ISO-8859-3                glibc solaris                             yes
| #   ISO-8859-4                osf solaris freebsd                       yes
| #   ISO-8859-5                glibc aix hpux irix osf solaris freebsd   yes
| #   ISO-8859-6                glibc aix hpux solaris                    yes
| #   ISO-8859-7                glibc aix hpux irix osf solaris           yes
| #   ISO-8859-8                glibc aix hpux osf solaris                yes
| #   ISO-8859-9                glibc aix hpux irix osf solaris           yes
| #   ISO-8859-13               glibc
| #   ISO-8859-15               glibc aix osf solaris freebsd
| #   KOI8-R                    glibc solaris freebsd                     yes
| #   KOI8-U                    glibc freebsd                             yes
| #   CP437                     dos
| #   CP775                     dos
| #   CP850                     aix osf dos
| #   CP852                     dos
| #   CP855                     dos
| #   CP856                     aix
| #   CP857                     dos
| #   CP861                     dos
| #   CP862                     dos
| #   CP864                     dos
| #   CP865                     dos
| #   CP866                     freebsd dos
| #   CP869                     dos
| #   CP874                     win32 dos
| #   CP922                     aix
| #   CP932                     aix win32 dos
| #   CP943                     aix
| #   CP949                     osf win32 dos
| #   CP950                     win32 dos
| #   CP1046                    aix
| #   CP1124                    aix
| #   CP1129                    aix
| #   CP1250                    win32
| #   CP1251                    glibc win32
| #   CP1252                    aix win32
| #   CP1253                    win32
| #   CP1254                    win32
| #   CP1255                    win32
| #   CP1256                    win32
| #   CP1257                    win32
| #   GB2312                    glibc aix hpux irix solaris freebsd       yes
| #   EUC-JP                    glibc aix hpux irix osf solaris freebsd   yes
| #   EUC-KR                    glibc aix hpux irix osf solaris freebsd   yes
| #   EUC-TW                    glibc aix hpux irix osf solaris
| #   BIG5                      glibc aix hpux osf solaris freebsd        yes
| #   BIG5-HKSCS                glibc
| #   GBK                       aix osf win32 dos
| #   GB18030                   glibc
| #   SHIFT_JIS                 hpux osf solaris freebsd                  yes
| #   JOHAB                     glibc win32
| #   TIS-620                   glibc aix hpux osf solaris
| #   VISCII                    glibc                                     yes
| #   HP-ROMAN8                 hpux
| #   HP-ARABIC8                hpux
| #   HP-GREEK8                 hpux
| #   HP-HEBREW8                hpux
| #   HP-TURKISH8               hpux
| #   HP-KANA8                  hpux
| #   DEC-KANJI                 osf
| #   DEC-HANYU                 osf
| #   UTF-8                     glibc aix hpux osf solaris                yes
| #
| # Note: Names which are not marked as being a MIME name should not be used in
| # Internet protocols for information interchange (mail, news, etc.).
| #
| # Note: ASCII and ANSI_X3.4-1968 are synonymous canonical names. Applications
| # must understand both names and treat them as equivalent.
|  *
|   

(giochannel.c)

void*
g_alloca   g_alloca (size_t size)

type*
g_newa   g_newa (typename type, size_t factor)

  memory from runtime stack

alloca - carve space from the runtime stack that gets automatically
reclaimed at the end of a function body.

(galloca.h)

gboolean
g_file_test   g_file_test (const gchar *filename, GFileTest test)

 (gfileutils.c)

This function allows for various tests that normal unix people know
from the shell command `test`. The tests themselves are coded in
the bit-field being the second argument - however the developers
say that there is no need to combine more than one test per call.
If tests are combined then the result is a logical OR of each test.

The test bits are:

 | G_FILE_TEST_IS_REGULAR    = 1 << 0, = `test -f` .........
|    G_FILE_TEST_IS_SYMLINK    = 1 << 1, = `test -L` .........
|    G_FILE_TEST_IS_DIR        = 1 << 2, = `test -d` .........
|    G_FILE_TEST_IS_EXECUTABLE = 1 << 3, = `test -x` .........
|    G_FILE_TEST_EXISTS        = 1 << 4  = `test -e` .........
|  *
|  * All tests follow symbolic links, except the test for a symlink
|  * file itself. That makes it return the access() result of the
|  * target file. If you did hit a dangling symlink then all tests
|  * will naturally fail but the test for symblink itself.
|   

(gfileutils.c)

GFileError
g_file_error_from_errno   g_file_error_from_errno (gint err_no)

 (gfileutils.c)

This function gets a #GFileError constant that corresponds to
the errno-argument. As an example, an EEXIST errno-value
will be converted into a G_FILE_ERROR_EXIST.

Usually the return value will be put into a GError returned
from a function that manipulates files and wants to pass back
a GError as with
g_set_error.

(gfileutils.c)

gboolean
g_file_get_contents   g_file_get_contents (const gchar *filename, gchar **contents, gsize *length, GError **error)

 (gfileutils.c)

This function reads an entire file into newly allocated memory,
in hacker slang it `slurp`s a file.

On success, a true is returned and the two return-args "contents"
and "length" got filled with valid values. (while the error-return
is invalid).

On failure, false is returned, the return-args "contents" / "length"
are set to null (they are not left untouched!), and the error-return
is filled with a description in the G_FILE_ERROR domain. You will
usually see error-codes as mapped from errno with the call to
g_file_error_from_errno

(gfileutils.c)

int
g_mkstemp   g_mkstemp (char *tmpl)

int
g_file_open_tmp   g_file_open_tmp (const char *tmpl, char **name_used, GError **error)

 

This function has copied the implementation from the GNU C library
(glibc), and implements the standard unix mkstemp() function.
In fact, it will simply call the mkstemp() function of the
underlying operating system if such exists.

The call protocoll requires that a template arg is given that has
the six last letters be "XXXXXX". These are replaced with values to
for a unique filename (actually based on the current time() ).

The file is created and open()ed in mode 0666 (in binary mode on
windowish systems). You can close the file-handle with a normal
posix close(). Just like open(), a return value of -1 flags
an error.

Note: the input filename template buffer is modified - do not try to
hand over a string constant (learn about gcc -Wwrite-strings and use
it regularly. It will warn you about such an error). Remember that
the tempname is based on the time()-value - if a file exists under
the resulting name, this function will try again for the next 100
values, and fails then with EEXIST. (that's why a unix system should
be rebooted some of a time - so the /tmp directory can be cleaned
by the boot scripts).

(gfileutils.c)

gchar *
g_build_path   g_build_path (const gchar *separator, const gchar *first_element, ...)

gchar *
g_build_filename   g_build_filename (const gchar *first_element, ...)

 

It is hard to characterize this function - it is useless for
applications but can be abused for a lot of other stuff. The
vararg list of parts is joined together with the given separator
put in between. Unlike what the name suggests, you are totally
free to use whatever seperator and string parts you which -
consider g_build_path (",","a","b","c"); to create an output
list "a,b,c".

The return-value should be g_freed. There is again the
implementation flaw that the returnvalue is always nonnull
as a sigfault would occur before under OOM conditions.

(gfileutils.c)

gpointer
g_malloc   g_malloc (gulong n_bytes)

gpointer
g_malloc0   g_malloc0 (gulong n_bytes)

gpointer
g_realloc   g_realloc (gpointer mem, gulong n_bytes)

void
g_free   g_free (gpointer mem)

gpointer
g_try_malloc   g_try_malloc (gulong n_bytes)

gpointer
g_try_realloc   g_try_realloc (gpointer mem, gulong n_bytes)

struct_type*
g_new   g_new (typename struct_type, gsize n_structs)

struct_type*
g_new0   g_new0 (typename struct_type, gsize n_structs)

struct_type*
g_renew0   g_renew0 (typename struct_type, gpointer mem, gsize n_structs)

  Memory allocation functions

There is a global non-threaded glib_mem_vtable that has a set of
function handlers to implement the memory allocations - per default
these map to the alloc routines of the underlying operating system.
(well, they fix the realloc_0 bug presented in many environments).

This function does return a malloc(3) memory area. When OOM occurs
(out of memory) a g_error is shown to the user and NULL returned. If
the n_bytes arguments was null then NULL is returned too.

(gmem.c)

void
g_mem_set_vtable   g_mem_set_vtable (GMemVTable *vtable)

gboolean
g_mem_is_system_malloc   g_mem_is_system_malloc (void)

void
g_mem_profile   g_mem_profile (void)

  Memory allocation virtualization for debugging purposes

g_mem_set_vtable() has to be the very first GLib function called
if being used

struct _GMemVTable { gpointer (*malloc) (gsize n_bytes); gpointer (*realloc) (gpointer mem, gsize n_bytes); void (*free) (gpointer mem); // optional gpointer (*calloc) (gsize n_blocks, gsize n_block_bytes); gpointer (*try_malloc) (gsize n_bytes); gpointer (*try_realloc) (gpointer mem, gsize n_bytes); };

(gmem.c)

GMemChunk*
g_mem_chunk_new   g_mem_chunk_new (const gchar *name, gint atom_size, gulong area_size, gint type)

void
g_mem_chunk_destroy   g_mem_chunk_destroy (GMemChunk *mem_chunk)

gpointer
g_mem_chunk_alloc   g_mem_chunk_alloc (GMemChunk *mem_chunk)

gpointer
g_mem_chunk_alloc0   g_mem_chunk_alloc0 (GMemChunk *mem_chunk)

void
g_mem_chunk_free   g_mem_chunk_free (GMemChunk *mem_chunk, gpointer mem)

void
g_mem_chunk_clean   g_mem_chunk_clean (GMemChunk *mem_chunk)

void
g_mem_chunk_reset   g_mem_chunk_reset (GMemChunk *mem_chunk)

void
g_mem_chunk_print   g_mem_chunk_print (GMemChunk *mem_chunk)

void
g_mem_chunk_info   g_mem_chunk_info (void)

void
g_blow_chunks   g_blow_chunks (void)

GMemChunk*
g_mem_chunk_create   g_mem_chunk_create (typename type, gsize pre_alloc, gint alloc_type)

  chunked memory allocations

This function creates a new memory chunk instance - a pool manager.

Memory chunks are used to allocate pieces of memory which are
always the same size. Lists are a good example of such a data type.
The memory chunk allocates and frees blocks of memory as needed.

Just be sure to call "g_mem_chunk_free" and not "g_free" on data
allocated in a mem chunk. ("g_free" will most likely cause a seg
fault...somewhere).

Oh yeah, GMemChunk is an opaque data type. (You don't really
want to know what's going on inside do you?)

As for the "type" of the GMemChunk-Pool:

G_ALLOC_ONLY MemChunk's can only allocate memory. The free operation
is interpreted as a no op. G_ALLOC_ONLY MemChunk's save 4 bytes per
atom. (They are also useful for lists which use MemChunk to allocate
memory but are also part of the MemChunk implementation).
G_ALLOC_AND_FREE MemChunk's can allocate and free memory.

There is no G_ALLOC_POOL_ONLY to disallow any realloc operation when
the pool runs out of MemArea nodes. (design flaw). When the number of
memarea-nodes reaches the area_size then a new poolmem-block is allocated
and appended. Effectivly, the area_size designates the steps that a
real g_malloc is called, and appended as unused nodes to the pool.

(gmem.c)

GAllocator*
g_allocator_new   g_allocator_new (const gchar *name, guint n_preallocs)

void
g_allocator_free   g_allocator_free (GAllocator *allocator)

  Generic allocators

This function does..

(gmem.c)

type*
g_chunk_new   g_chunk_new (typename type, GMemChunk* chunk)

 (gmem.c)

This function calls g_mem_chunk_alloc and casts it to "type"

(gmem.c)

type*
g_chunk_new0   g_chunk_new0 (typename type, GMemChunk* chunk)

 (gmem.c)

This function calls g_mem_chunk_alloc0 and casts it to "type"

(gmem.c)

void
g_chunk_free   g_chunk_free (gpointer mem, GMemChunk* mem_chunk)

 (gmem.c)

This function calls g_mem_chunk_free - inverse order of arguments.

(gmem.c)

GError*
g_error_new   g_error_new (GQuark domain, gint code, const gchar *format, ...)

GError*
g_error_new_literal   g_error_new_literal (GQuark domain, gint code, const gchar *message)

void
g_error_free   g_error_free (GError *error)

GError*
g_error_copy   g_error_copy (const GError *error)

gboolean
g_error_matches   g_error_matches (const GError *error, GQuark domain, gint code)

  structured error reporting

This function creates a new error message. The GError itself just
contains three members: ->domain ->code and ->message
where the latter is simply string created by
g_strdup_vprintf
with the vararg arguments of this function.

(gerror.c)

void
g_set_error   g_set_error (GError **err, GQuark domain, gint code, const gchar *format, ...)

void
g_propagate_error   g_propagate_error (GError **dest, GError *src)

void
g_clear_error   g_clear_error (GError **err)

  setting an error

if the target-err-variable is null then nothing is done at all.
Otherwise this function assigns a new
g_error_new to it, and
if an old error-struct is there then an overwritten-warning is
created.

Unlike many would expect, the overwritten-warning does *not*
print the older message, it prints the current message, and it
does not free its resources making for a memory leak (flaw/bug).

(gerror.c)

guint16
g_ascii_isalpha   g_ascii_isalpha (guchar c)

guint16
g_ascii_isalnum   g_ascii_isalnum (guchar c)

guint16
g_ascii_iscntrl   g_ascii_iscntrl (guchar c)

guint16
g_ascii_isdigit   g_ascii_isdigit (guchar c)

guint16
g_ascii_isgraph   g_ascii_isgraph (guchar c)

guint16
g_ascii_islower   g_ascii_islower (guchar c)

guint16
g_ascii_isprint   g_ascii_isprint (guchar c)

guint16
g_ascii_ispunct   g_ascii_ispunct (guchar c)

guint16
g_ascii_isspace   g_ascii_isspace (guchar c)

guint16
g_ascii_isupper   g_ascii_isupper (guchar c)

guint16
g_ascii_isxdigit   g_ascii_isxdigit (guchar c)

gchar
g_ascii_tolower   g_ascii_tolower (gchar c) G_GNUC_CONST

gchar
g_ascii_toupper   g_ascii_toupper (gchar c) G_GNUC_CONST

gint
g_ascii_digit_value   g_ascii_digit_value (gchar c) G_GNUC_CONST

gint
g_ascii_xdigit_value   g_ascii_xdigit_value (gchar c) G_GNUC_CONST

  ctype functions

These functions match those in "ctype.h" but they are not affected
by locale settings (whereas posix would specify such).

This function checks (g_ascii_table[c] & G_ASCII_ALPHA).

(gstrfuncs.c)

gchar*
g_strcanon   g_strcanon (gchar *string, const gchar *valid_chars, gchar substitutor)

gchar*
g_strdelimit   g_strdelimit (gchar *string, const gchar *delimiters, gchar new_delimiter)

  modify in place

This function is basically the invers of g_strdelimit - all the
chars are checked whether it is within "valid_chars". If it is not
then the char is replaced the "substitutor" char. There is no
default for null-arguments so all these should be set.

The return value is the argument string (or NULL for invalid args).

(gstrfuncs.c)

const gchar*
g_strerror   g_strerror (gint errnum)

  names for sys enums

get the stringconstant for an errno constant - it returns a string
of glib origin for a lot of known constants, so that the error
messages will have a common name across all platforms covered.

(gstrfuncs.c)

gsize
g_strlcat   g_strlcat (gchar *dest, const gchar *src, gsize dest_size)

gsize
g_strlcpy   g_strlcpy (gchar *dest, const gchar *src, gsize dest_size)

  secure strcat

This function cats the string to the end of the other string and
the length tells of the maximum target (!!) buffer size.

(gstrfuncs.c)

gchar *
g_strrstr   g_strrstr (const gchar *haystack, const gchar *needle)

gchar *
g_strstr_len   g_strstr_len (const gchar *haystack, gssize haystack_len, const gchar *needle)

gchar *
g_strrstr_len   g_strrstr_len (const gchar *haystack, gssize haystack_len, const gchar *needle)

  find string

This function searches the string for the last occurence of the
substring. If it is found then the pointer to that occurence is
returned, otherwise just a null flagging failure.

(gstrfuncs.c)

gdouble
g_strtod   g_strtod (const gchar *nptr, gchar **endptr)

gdouble
g_ascii_strtod   g_ascii_strtod (const gchar *nptr, gchar **endptr)

#define G_ASCII_DTOSTR_BUF_SIZE (29 + 10) gchar *
g_ascii_dtostr   g_ascii_dtostr (gchar *buffer, gint buf_len, gdouble d)

gchar *
g_ascii_formatd   g_ascii_formatd (gchar *buffer, gint buf_len, const gchar *format, gdouble d)

 

String to double conversion function.

(gstrfuncs.c)

gchar*
g_strstrip   g_strstrip (gchar *string)

gchar*
g_strreverse   g_strreverse (gchar *string)

gchar*
g_strchug   g_strchug (gchar *string)

  modify in-place

removes leading & trailing spaces, i.e. (g_strchomp(g_strchug(string))

(gstrfuncs.c)

gint
g_ascii_strcasecmp   g_ascii_strcasecmp (const gchar *s1, const gchar *s2)

gint
g_ascii_strncasecmp   g_ascii_strncasecmp (const gchar *s1, const gchar *s2, gsize n)

gchar*
g_ascii_strdown   g_ascii_strdown (const gchar *str, gssize len)

gchar*
g_ascii_strup   g_ascii_strup (const gchar *str, gssize len)

  case-sensitive

This function compares case-insensitive - only the lower ascii
half is conserired as it is fully locale independent.

(gstrfuncs.c)

gint
g_strcasecmp   g_strcasecmp (const gchar *s1, const gchar *s2)

gint
g_strncasecmp   g_strncasecmp (const gchar *s1, const gchar *s2, guint n)

gchar*
g_strdown   g_strdown (gchar *string)

gchar*
g_strup   g_strup (gchar *string)

  case-senstitive

compare case-insenstive - locale-dependent and DEPRECATED, use
the ascii-only
g_ascii_strcasecmp instead.

(gstrfuncs.c)

gchar*
g_strdup   g_strdup (const gchar *str)

gchar*
g_strdup_printf   g_strdup_printf (const gchar *format, ...)

gchar*
g_strdup_vprintf   g_strdup_vprintf (const gchar *format, va_list args)

gchar*
g_strndup   g_strndup (const gchar *str, gsize n)

gchar*
g_strnfill   g_strnfill (gsize length, gchar fill_char)

gpointer
g_memdup   g_memdup (gconstpointer mem, guint byte_size)

gchar*
g_stpcpy   g_stpcpy (gchar *dest, const char *src)

  strdup functions

String utility functions that return a newly allocated string which
ought to be freed with g_free from the caller at some point.

This function makes a simple copy like strdup / free with g_free

(gstrfuncs.c)

gchar*
g_strjoin   g_strjoin (const gchar *separator, ...)

gchar*
g_strconcat   g_strconcat (const gchar *string1, ...)

gchar**
g_strsplit   g_strsplit (const gchar *string, const gchar *delimiter, gint max_tokens)

gchar*
g_strjoinv   g_strjoinv (const gchar *separator, gchar **str_array)

void
g_strfreev   g_strfreev (gchar **str_array)

gchar**
g_strdupv   g_strdupv (gchar **str_array)

  joining strings

This function does a similar thing as g_strconcat but it places
the given separator in between the partial strings. A null as the
seperator-string defaults to the empty string ("") being effectivly
what g_strconcat does.

(gstrfuncs.c)

gchar*
g_strescape   g_strescape (const gchar *source, const gchar *exceptions)

gchar*
g_strcompress   g_strcompress (const gchar *source)

 (gstrfuncs.c)

Copy a string escaping nonprintable characters like in C strings.
Inverse of g_strcompress. The exceptions parameter, if non-NULL, points
to a string containing characters that are not to be escaped.

Deprecated API: gchar* g_strescape (const gchar *source);
Luckily this function wasn't used much, using NULL as second parameter
provides mostly identical semantics.

(gstrfuncs.c)

GDir *
g_dir_open   g_dir_open (const gchar *path, guint flags, GError **error)

const gchar *
g_dir_read_name   g_dir_read_name (GDir *dir)

void
g_dir_rewind   g_dir_rewind (GDir *dir)

void
g_dir_close   g_dir_close (GDir *dir)

  dirent functions

This function returns a dirent-like handle for the path given.
The flags should be just null (unused at the moment). On failure
a NULL is returned and gerror set if you asked for that. The
returned dirent should be released later with
g_dir_close.

(gdir.c)

GMarkupParseContext *
g_markup_parse_context_new   g_markup_parse_context_new (const GMarkupParser *parser, GMarkupParseFlags flags, gpointer user_data, GDestroyNotify user_data_dnotify)

void
g_markup_parse_context_free   g_markup_parse_context_free (GMarkupParseContext *context)

void
g_markup_parse_context_get_position   g_markup_parse_context_get_position (GMarkupParseContext *context, gint *line_number, gint *char_number)

 

For this function the glib docs say:
Creates a new parse context. A parse context is used to parse
marked-up documents. You can feed any number of documents into
a context, as long as no errors occur; once an error occurs,
the parse context can't continue to parse text (you have to free it
and create a new parse context).

Sadly, there is not much told about the different flags that can
be pushed into it - and actually, there are none so far, it is just
a placeholder, so give it a "0" and let it be.

The user_data is given down into the various callbacks of the
GMarkupParser - actually, you can create a static-const Parser
infoblock an create multiple instances of it and each of them
has its own user_data.

The user_data_dnotify gets to be part of the returned context-block
and it will be called upon
g_markup_parse_context_free.

(gmarkup.c)

gchar*
g_markup_escape_text   g_markup_escape_text (const gchar *text, gssize length)

 (gmarkup.c)

For this function the glib docs say:
Escapes text so that the markup parser will parse it verbatim.
Less than, greater than, ampersand, etc. are replaced with the
corresponding entities. This function would typically be used
when writing out a file to be parsed with the markup parser.

If length=-1 then the strlen is taken of the argument text;
The escaping process uses internall a
g_string_new followed by a
series of g_string_append calls - that's not the fastest possible.

(gmarkup.c)

void
g_markup_parser.text   g_markup_parser.text (GMarkupParseContext *context, const gchar *text, gsize text_len, gpointer user_data, GError **error)

 

The GMarkupParser structures contains 5 callback structures.
The callbacks are in this order:

 | start_element, end_element, text, passthrough, error
|  * These will be run for each element found with an input text given to
|  * the GMarkupParseContext intance via <link>g_markup_parse_context_parse</link>
|  *
|  * 
|  * This function is called for character data - that is text with
|  * no markup at all. Note that the text is not nul-terminated, it
|  * is actually a reference into the buffer given by to the current
|  * call of <link>g_markup_parse</link>-context_parse - if you set an error
|  * from your callback it will be <link>g_propagate_error</link>'d to the caller
|  * of <link>g_markup_parse_context_parse</link>
|   

(gmarkup.c)

void
g_markup_parser.start_element   g_markup_parser.start_element (GMarkupParseContext *context, const gchar *element_name, const gchar **attribute_names, const gchar **attribute_values, gpointer user_data, GError **error)

  g_markup_parser.text

This function is called for open tags &lt;foo bar="baz"&gt;

The element_name string is part of the tag-stack, it is nul-terminated
and may not be modified. The attribute_names/attribute_values pair of
fields is a NULL-terminated pointer-array. The current implementation
will always return an array-reference even if no attributes have been
seen - in the form of two arrays containing a NULL in the first entry.
The attribute-fields may not be modified either - they'll be freed
about immediately after returning from this callback function, so
copy the arrays to your user_data-referenced structures. The strings
in the two fields themselves are also zero-terminated, so that a
simple
g_strdup might be want you want to do about each.

Reading over the implementation: it is actually possible to steal the
attribute strings by placing a NULL in the place. However, this may get
invalid in the next generation of this library, but perhaps it could be
standardized - it is a great performance boost (and spec flaw now).

(gmarkup.c)

void
g_markup_parser.end_element   g_markup_parser.end_element (GMarkupParseContext *context, const gchar *element_name, gpointer user_data, GError **error)

  g_markup_parser.text

This function is called for close tags &lt:/foo&gt;

Again the element_name is part of the tag-stack, it is nul-terminated
and may not be modified.

(gmarkup.c)

void
g_markup_parser.passthrough   g_markup_parser.passthrough (GMarkupParseContext *context, const gchar *passthrough_text, gsize text_len, gpointer user_data, GError **error)

  g_markup_parser.text

This function is called for strings that should be re-saved
verbatim in this same position, but are not otherwise interpretable.
At the moment this includes comments and processing instructions.

Again, the text/len pair is a reference into the textbuffer given to
g_markup_parse_context_parse that this callback is called within,
well with one exception: if the the passthrough-text was handed down
in two calls to _parse. In that case some left_over must be considered
which has resulted into a temporary allocation of a GString buffer to
concatenate all the parts and put them down to this callback in one.

(gmarkup.c)

void
g_markup_parser.error   g_markup_parser.error (GMarkupParseContext *context, GError *error, gpointer user_data)

  g_markup_parser.text

This function is called on error, including one set by other
methods in the vtable. The GError should not be freed.

(gmarkup.c)