glib-man 2.0.1.24

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)

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)

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).

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.

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); };

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.

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..

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

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

This function calls g_mem_chunk_alloc and casts it to "type"

(gmem.c)

void g_chunk_free g_chunk_free (gpointer mem, GMemChunk* mem_chunk)

This function calls g_mem_chunk_alloc0 and casts it to "type"

(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)

This function calls g_mem_chunk_free - inverse order of arguments.

(gmem.c)

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)

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).

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.

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.

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.

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.

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))

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.

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)

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.

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)

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)

This function is called for open tags <foo bar="baz">

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)

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

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

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

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.

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

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