From 92314620894caea5c092cb53bbb77f6bc3d0811d Mon Sep 17 00:00:00 2001 From: Owen Taylor Date: Mon, 16 Aug 1999 17:58:30 +0000 Subject: [PATCH] Initial revision --- docs/reference/AUTHORS | 7 + docs/reference/COPYING | 30 + docs/reference/ChangeLog | 6 + docs/reference/NEWS | 0 docs/reference/README | 14 + docs/reference/README.cvs-commits | 22 + docs/reference/glib/Makefile.am | 46 + docs/reference/glib/autogen.sh | 52 + docs/reference/glib/configure.in | 21 + docs/reference/glib/glib-decl.txt | 4544 +++++++++++++++++ docs/reference/glib/glib-docs.sgml | 99 + docs/reference/glib/glib-sections.txt | 1277 +++++ docs/reference/glib/glib/AUTHORS | 7 + docs/reference/glib/glib/COPYING | 30 + docs/reference/glib/glib/ChangeLog | 6 + docs/reference/glib/glib/Makefile.am | 46 + docs/reference/glib/glib/NEWS | 0 docs/reference/glib/glib/README | 14 + docs/reference/glib/glib/README.cvs-commits | 22 + docs/reference/glib/tmpl/allocators.sgml | 65 + docs/reference/glib/tmpl/arrays.sgml | 224 + docs/reference/glib/tmpl/arrays_byte.sgml | 135 + docs/reference/glib/tmpl/arrays_pointer.sgml | 182 + docs/reference/glib/tmpl/byte_order.sgml | 545 ++ docs/reference/glib/tmpl/caches.sgml | 152 + docs/reference/glib/tmpl/completion.sgml | 121 + docs/reference/glib/tmpl/datalist.sgml | 197 + docs/reference/glib/tmpl/datasets.sgml | 204 + docs/reference/glib/tmpl/date.sgml | 655 +++ docs/reference/glib/tmpl/glib-unused.sgml | 0 docs/reference/glib/tmpl/hash_tables.sgml | 358 ++ docs/reference/glib/tmpl/hooks.sgml | 524 ++ docs/reference/glib/tmpl/iochannels.sgml | 319 ++ docs/reference/glib/tmpl/limits.sgml | 87 + .../glib/tmpl/linked_lists_double.sgml | 406 ++ .../glib/tmpl/linked_lists_single.sgml | 370 ++ docs/reference/glib/tmpl/macros.sgml | 207 + docs/reference/glib/tmpl/macros_misc.sgml | 158 + docs/reference/glib/tmpl/main.sgml | 496 ++ docs/reference/glib/tmpl/memory.sgml | 156 + docs/reference/glib/tmpl/memory_chunks.sgml | 303 ++ docs/reference/glib/tmpl/messages.sgml | 262 + docs/reference/glib/tmpl/misc_utils.sgml | 226 + docs/reference/glib/tmpl/modules.sgml | 176 + docs/reference/glib/tmpl/quarks.sgml | 91 + docs/reference/glib/tmpl/relations.sgml | 201 + docs/reference/glib/tmpl/scanner.sgml | 490 ++ docs/reference/glib/tmpl/string_chunks.sgml | 110 + docs/reference/glib/tmpl/string_utils.sgml | 354 ++ docs/reference/glib/tmpl/strings.sgml | 209 + docs/reference/glib/tmpl/threads.sgml | 939 ++++ docs/reference/glib/tmpl/timers.sgml | 75 + docs/reference/glib/tmpl/trees-binary.sgml | 228 + docs/reference/glib/tmpl/trees-nary.sgml | 493 ++ docs/reference/glib/tmpl/type_conversion.sgml | 78 + docs/reference/glib/tmpl/types.sgml | 216 + docs/reference/glib/tmpl/warnings.sgml | 187 + docs/reference/glib/tmpl/windows.sgml | 170 + 58 files changed, 16612 insertions(+) create mode 100644 docs/reference/AUTHORS create mode 100644 docs/reference/COPYING create mode 100644 docs/reference/ChangeLog create mode 100644 docs/reference/NEWS create mode 100644 docs/reference/README create mode 100644 docs/reference/README.cvs-commits create mode 100644 docs/reference/glib/Makefile.am create mode 100755 docs/reference/glib/autogen.sh create mode 100644 docs/reference/glib/configure.in create mode 100644 docs/reference/glib/glib-decl.txt create mode 100644 docs/reference/glib/glib-docs.sgml create mode 100644 docs/reference/glib/glib-sections.txt create mode 100644 docs/reference/glib/glib/AUTHORS create mode 100644 docs/reference/glib/glib/COPYING create mode 100644 docs/reference/glib/glib/ChangeLog create mode 100644 docs/reference/glib/glib/Makefile.am create mode 100644 docs/reference/glib/glib/NEWS create mode 100644 docs/reference/glib/glib/README create mode 100644 docs/reference/glib/glib/README.cvs-commits create mode 100644 docs/reference/glib/tmpl/allocators.sgml create mode 100644 docs/reference/glib/tmpl/arrays.sgml create mode 100644 docs/reference/glib/tmpl/arrays_byte.sgml create mode 100644 docs/reference/glib/tmpl/arrays_pointer.sgml create mode 100644 docs/reference/glib/tmpl/byte_order.sgml create mode 100644 docs/reference/glib/tmpl/caches.sgml create mode 100644 docs/reference/glib/tmpl/completion.sgml create mode 100644 docs/reference/glib/tmpl/datalist.sgml create mode 100644 docs/reference/glib/tmpl/datasets.sgml create mode 100644 docs/reference/glib/tmpl/date.sgml create mode 100644 docs/reference/glib/tmpl/glib-unused.sgml create mode 100644 docs/reference/glib/tmpl/hash_tables.sgml create mode 100644 docs/reference/glib/tmpl/hooks.sgml create mode 100644 docs/reference/glib/tmpl/iochannels.sgml create mode 100644 docs/reference/glib/tmpl/limits.sgml create mode 100644 docs/reference/glib/tmpl/linked_lists_double.sgml create mode 100644 docs/reference/glib/tmpl/linked_lists_single.sgml create mode 100644 docs/reference/glib/tmpl/macros.sgml create mode 100644 docs/reference/glib/tmpl/macros_misc.sgml create mode 100644 docs/reference/glib/tmpl/main.sgml create mode 100644 docs/reference/glib/tmpl/memory.sgml create mode 100644 docs/reference/glib/tmpl/memory_chunks.sgml create mode 100644 docs/reference/glib/tmpl/messages.sgml create mode 100644 docs/reference/glib/tmpl/misc_utils.sgml create mode 100644 docs/reference/glib/tmpl/modules.sgml create mode 100644 docs/reference/glib/tmpl/quarks.sgml create mode 100644 docs/reference/glib/tmpl/relations.sgml create mode 100644 docs/reference/glib/tmpl/scanner.sgml create mode 100644 docs/reference/glib/tmpl/string_chunks.sgml create mode 100644 docs/reference/glib/tmpl/string_utils.sgml create mode 100644 docs/reference/glib/tmpl/strings.sgml create mode 100644 docs/reference/glib/tmpl/threads.sgml create mode 100644 docs/reference/glib/tmpl/timers.sgml create mode 100644 docs/reference/glib/tmpl/trees-binary.sgml create mode 100644 docs/reference/glib/tmpl/trees-nary.sgml create mode 100644 docs/reference/glib/tmpl/type_conversion.sgml create mode 100644 docs/reference/glib/tmpl/types.sgml create mode 100644 docs/reference/glib/tmpl/warnings.sgml create mode 100644 docs/reference/glib/tmpl/windows.sgml diff --git a/docs/reference/AUTHORS b/docs/reference/AUTHORS new file mode 100644 index 00000000..64f46b74 --- /dev/null +++ b/docs/reference/AUTHORS @@ -0,0 +1,7 @@ +Damon Chaplin and others. + +See: + + http://www.gtk.org/rdp/status.html + +for a complete list. diff --git a/docs/reference/COPYING b/docs/reference/COPYING new file mode 100644 index 00000000..df952d3c --- /dev/null +++ b/docs/reference/COPYING @@ -0,0 +1,30 @@ +This work may be reproduced and distributed in whole or in part, in +any medium, physical or electronic, so as long as this copyright +notice remains intact and unchanged on all copies. Commercial +redistribution is permitted and encouraged, but you may not +redistribute, in whole or in part, under terms more restrictive than +those under which you received it. If you redistribute a modified or +translated version of this work, you must also make the source code to +the modified or translated version available in electronic form +without charge. However, mere aggregation as part of a larger work +shall not count as a modification for this purpose. + +All code examples in this work are placed into the public domain, +and may be used, modified and redistributed without restriction. + +BECAUSE THIS WORK IS LICENSED FREE OF CHARGE, THERE IS NO +WARRANTY FOR THE WORK, TO THE EXTENT PERMITTED BY APPLICABLE LAW. +EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR +OTHER PARTIES PROVIDE THE WORK "AS IS" WITHOUT WARRANTY OF ANY +KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. SHOULD THE WORK PROVE DEFECTIVE, YOU ASSUME +THE COST OF ALL NECESSARY REPAIR OR CORRECTION. + +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY +AND/OR REDISTRIBUTE THE WORK AS PERMITTED ABOVE, BE LIABLE TO YOU +FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR +CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE +WORK, EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog new file mode 100644 index 00000000..081e1b25 --- /dev/null +++ b/docs/reference/ChangeLog @@ -0,0 +1,6 @@ +Wed Aug 18 23:11:28 1999 Owen Taylor + + * Import into CVS of glib-reference-1.1.3 + Filled in some basic contents for AUTHORS + README, and README.cvs + diff --git a/docs/reference/NEWS b/docs/reference/NEWS new file mode 100644 index 00000000..e69de29b diff --git a/docs/reference/README b/docs/reference/README new file mode 100644 index 00000000..d0aa5981 --- /dev/null +++ b/docs/reference/README @@ -0,0 +1,14 @@ +This package contains the reference documentation +for GLib. For more information about Glib, +see: + + http://www.gtk.org + +For information about contributing to the +GLib/GTK+ reference documentation project, see: + + http://www.gtk.org/rdp/ + +The GLib reference documentation is freely redistributable, +see the file COPYING for details. + diff --git a/docs/reference/README.cvs-commits b/docs/reference/README.cvs-commits new file mode 100644 index 00000000..38e8735b --- /dev/null +++ b/docs/reference/README.cvs-commits @@ -0,0 +1,22 @@ +Before making any changes to this module, please +contact: + + Damon Chaplin + +This will ensure that duplicate work does not occur, +and also make sure we know who has written what +parts of the documentation. See + + http://www.gtk.org/rdp/ + +for more information. + +By contributing work to the Reference Documentation +Project, you agree that it will be covered under the +license terms described in the file COPYING +included in this directory. + + + + + diff --git a/docs/reference/glib/Makefile.am b/docs/reference/glib/Makefile.am new file mode 100644 index 00000000..9ba90e06 --- /dev/null +++ b/docs/reference/glib/Makefile.am @@ -0,0 +1,46 @@ +## Process this file with automake to produce Makefile.in + +# The name of the module. +DOC_MODULE=glib + +# The top-level SGML file. +DOC_MAIN_SGML_FILE=glib-docs.sgml + + +TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) + +scan: + gtkdoc-scan --module=$(DOC_MODULE) `glib-config --prefix`/include/glib.h `glib-config --prefix`/include/gmodule.h `glib-config --prefix`/lib/glib/include/glibconfig.h + +templates: scan + gtkdoc-mktmpl --module=$(DOC_MODULE) + +sgml: + gtkdoc-mkdb --module=$(DOC_MODULE) + +html: + if ! test -d html ; then mkdir html ; fi + -cd html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) + +clean-local: + rm -f *~ *.bak *.hierarchy *.signals *.args *-unused.txt + +maintainer-clean-local: clean + rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt + +install-data-local: + install -d -m 0755 $(TARGET_DIR) + install -m 0644 html/*.html $(TARGET_DIR) + install -m 0644 html/index.sgml $(TARGET_DIR) + gtkdoc-fixxref --module=$(DOC_MODULE) --html-dir=$(HTML_DIR) + +EXTRA_DIST = \ + $(DOC_MAIN_SGML_FILE) \ + $(DOC_MODULE)-sections.txt \ + glib-decl.txt + +dist-hook: + mkdir $(distdir)/tmpl + cp -p tmpl/*.sgml $(distdir)/tmpl + +.PHONY : html sgml templates scan diff --git a/docs/reference/glib/autogen.sh b/docs/reference/glib/autogen.sh new file mode 100755 index 00000000..02d68603 --- /dev/null +++ b/docs/reference/glib/autogen.sh @@ -0,0 +1,52 @@ +#!/bin/sh +# Run this to generate all the initial makefiles, etc. + +srcdir=`dirname $0` +test -z "$srcdir" && srcdir=. + +ORIGDIR=`pwd` +cd $srcdir +PROJECT=GLib-Reference +TEST_TYPE=-f +FILE=glib-sections.txt + +DIE=0 + +(autoconf --version) < /dev/null > /dev/null 2>&1 || { + echo + echo "You must have autoconf installed to compile $PROJECT." + echo "Download the appropriate package for your distribution," + echo "or get the source tarball at ftp://ftp.gnu.org/pub/gnu/" + DIE=1 +} + +(automake --version) < /dev/null > /dev/null 2>&1 || { + echo + echo "You must have automake installed to compile $PROJECT." + echo "Get ftp://sourceware.cygnus.com/pub/automake/automake-1.4.tar.gz" + echo "(or a newer version if it is available)" + DIE=1 +} + +if test "$DIE" -eq 1; then + exit 1 +fi + +test $TEST_TYPE $FILE || { + echo "You must run this script in the top-level $PROJECT directory" + exit 1 +} + +if test -z "$*"; then + echo "I am going to run ./configure with no arguments - if you wish " + echo "to pass any to it, please specify them on the $0 command line." +fi + +automake -a $am_opt +autoconf +cd $ORIGDIR + +$srcdir/configure --enable-maintainer-mode "$@" + +echo +echo "Now type 'make' to compile $PROJECT." diff --git a/docs/reference/glib/configure.in b/docs/reference/glib/configure.in new file mode 100644 index 00000000..009e1862 --- /dev/null +++ b/docs/reference/glib/configure.in @@ -0,0 +1,21 @@ +dnl Process this file with autoconf to produce a configure script. + +AC_INIT(glib-sections.txt) + +AM_INIT_AUTOMAKE(glib-reference, 1.1.3) + +AC_ARG_WITH(html-dir, [ --with-html-dir=PATH path to installed docs ]) + +AC_ISC_POSIX +AC_PROG_CC + +if test "x$with_html_dir" = "x" ; then + HTML_DIR='${datadir}/gtk-doc/html' +else + HTML_DIR=$with_html_dir +fi + +AC_SUBST(HTML_DIR) + +AC_OUTPUT([Makefile]) + diff --git a/docs/reference/glib/glib-decl.txt b/docs/reference/glib/glib-decl.txt new file mode 100644 index 00000000..4a57bf92 --- /dev/null +++ b/docs/reference/glib/glib-decl.txt @@ -0,0 +1,4544 @@ + +G_DIR_SEPARATOR +#define G_DIR_SEPARATOR '\\' + + +G_DIR_SEPARATOR_S +#define G_DIR_SEPARATOR_S "\\" + + +G_SEARCHPATH_SEPARATOR +#define G_SEARCHPATH_SEPARATOR ';' + + +G_SEARCHPATH_SEPARATOR_S +#define G_SEARCHPATH_SEPARATOR_S ";" + + +G_DIR_SEPARATOR +#define G_DIR_SEPARATOR '/' + + +G_DIR_SEPARATOR_S +#define G_DIR_SEPARATOR_S "/" + + +G_SEARCHPATH_SEPARATOR +#define G_SEARCHPATH_SEPARATOR ':' + + +G_SEARCHPATH_SEPARATOR_S +#define G_SEARCHPATH_SEPARATOR_S ":" + + +NULL +#define NULL ((void*) 0) + + +FALSE +#define FALSE (0) + + +TRUE +#define TRUE (!FALSE) + + +MAX +#define MAX(a, b) (((a) > (b)) ? (a) : (b)) + + +MIN +#define MIN(a, b) (((a) < (b)) ? (a) : (b)) + + +ABS +#define ABS(a) (((a) < 0) ? -(a) : (a)) + + +CLAMP +#define CLAMP(x, low, high) (((x) > (high)) ? (high) : (((x) < (low)) ? (low) : (x))) + + +G_VA_COPY +# define G_VA_COPY(ap1, ap2) (*(ap1) = *(ap2)) + + +G_VA_COPY +# define G_VA_COPY(ap1, ap2) g_memmove ((ap1), (ap2), sizeof (va_list)) + + +G_VA_COPY +# define G_VA_COPY(ap1, ap2) ((ap1) = (ap2)) + + +G_STRUCT_OFFSET +#define G_STRUCT_OFFSET(struct_type, member) \ + ((gulong) ((gchar*) &((struct_type*) 0)->member)) + + +G_STRUCT_MEMBER_P +#define G_STRUCT_MEMBER_P(struct_p, struct_offset) \ + ((gpointer) ((gchar*) (struct_p) + (gulong) (struct_offset))) + + +G_STRUCT_MEMBER +#define G_STRUCT_MEMBER(member_type, struct_p, struct_offset) \ + (*(member_type*) G_STRUCT_MEMBER_P ((struct_p), (struct_offset))) + + +G_CAN_INLINE +# define G_CAN_INLINE 1 + + +inline +# define inline __inline__ + + +inline +# define inline __inline__ + + +inline +# define inline __inline + + +inline +# define inline /* don't inline, then */ + + +G_INLINE_FUNC +# define G_INLINE_FUNC extern inline + + +G_INLINE_FUNC +# define G_INLINE_FUNC extern + + +G_INLINE_FUNC +# define G_INLINE_FUNC static inline + + +G_INLINE_FUNC +# define G_INLINE_FUNC extern + + +G_STMT_START +# define G_STMT_START (void)( + + +G_STMT_END +# define G_STMT_END ) + + +G_STMT_START +# define G_STMT_START if (1) + + +G_STMT_END +# define G_STMT_END else (void)0 + + +G_STMT_START +# define G_STMT_START do + + +G_STMT_END +# define G_STMT_END while (0) + + +G_GNUC_PRINTF +#define G_GNUC_PRINTF( format_idx, arg_idx ) \ + __attribute__((format (printf, format_idx, arg_idx))) + + +G_GNUC_SCANF +#define G_GNUC_SCANF( format_idx, arg_idx ) \ + __attribute__((format (scanf, format_idx, arg_idx))) + + +G_GNUC_FORMAT +#define G_GNUC_FORMAT( arg_idx ) \ + __attribute__((format_arg (arg_idx))) + + +G_GNUC_NORETURN +#define G_GNUC_NORETURN \ + __attribute__((noreturn)) + + +G_GNUC_CONST +#define G_GNUC_CONST \ + __attribute__((const)) + + +G_GNUC_UNUSED +#define G_GNUC_UNUSED \ + __attribute__((unused)) + + +G_GNUC_PRINTF +#define G_GNUC_PRINTF( format_idx, arg_idx ) + + +G_GNUC_SCANF +#define G_GNUC_SCANF( format_idx, arg_idx ) + + +G_GNUC_FORMAT +#define G_GNUC_FORMAT( arg_idx ) + + +G_GNUC_NORETURN +#define G_GNUC_NORETURN + + +G_GNUC_CONST +#define G_GNUC_CONST + + +G_GNUC_UNUSED +#define G_GNUC_UNUSED + + +G_GNUC_FUNCTION +#define G_GNUC_FUNCTION __FUNCTION__ + + +G_GNUC_PRETTY_FUNCTION +#define G_GNUC_PRETTY_FUNCTION __PRETTY_FUNCTION__ + + +G_GNUC_FUNCTION +#define G_GNUC_FUNCTION "" + + +G_GNUC_PRETTY_FUNCTION +#define G_GNUC_PRETTY_FUNCTION "" + + +ATEXIT +# define ATEXIT(proc) g_ATEXIT(proc) + + +G_NATIVE_ATEXIT +# define G_NATIVE_ATEXIT + + +G_BREAKPOINT +#define G_BREAKPOINT() G_STMT_START{ __asm__ __volatile__ ("int $03"); }G_STMT_END + + +G_BREAKPOINT +#define G_BREAKPOINT() G_STMT_START{ __asm__ __volatile__ ("bpt"); }G_STMT_END + + +G_BREAKPOINT +#define G_BREAKPOINT() + + +g_new +# define g_new(type, count) (ALLOC (type, count)) + + +g_new0 +# define g_new0(type, count) (CALLOC (type, count)) + + +g_renew +# define g_renew(type, mem, count) (REALLOC (mem, type, count)) + + +g_new +# define g_new(type, count) \ + ((type *) g_malloc ((unsigned) sizeof (type) * (count))) + + +g_new0 +# define g_new0(type, count) \ + ((type *) g_malloc0 ((unsigned) sizeof (type) * (count))) + + +g_renew +# define g_renew(type, mem, count) \ + ((type *) g_realloc (mem, (unsigned) sizeof (type) * (count))) + + +g_mem_chunk_create +#define g_mem_chunk_create(type, pre_alloc, alloc_type) ( \ + g_mem_chunk_new (#type " mem chunks (" #pre_alloc ")", \ + sizeof (type), \ + sizeof (type) * (pre_alloc), \ + (alloc_type)) \ +) + + +g_chunk_new +#define g_chunk_new(type, chunk) ( \ + (type *) g_mem_chunk_alloc (chunk) \ +) + + +g_chunk_new0 +#define g_chunk_new0(type, chunk) ( \ + (type *) g_mem_chunk_alloc0 (chunk) \ +) + + +g_chunk_free +#define g_chunk_free(mem, mem_chunk) G_STMT_START { \ + g_mem_chunk_free ((mem_chunk), (mem)); \ +} G_STMT_END + + +g_string +#define g_string(x) #x + + +g_assert +#define g_assert(expr) + + +g_assert_not_reached +#define g_assert_not_reached() + + +g_assert +#define g_assert(expr) G_STMT_START{ \ + if (!(expr)) \ + g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_ERROR, \ + "file %s: line %d (%s): assertion failed: (%s)", \ + __FILE__, \ + __LINE__, \ + __PRETTY_FUNCTION__, \ + #expr); }G_STMT_END + + +g_assert_not_reached +#define g_assert_not_reached() G_STMT_START{ \ + g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_ERROR, \ + "file %s: line %d (%s): should not be reached", \ + __FILE__, \ + __LINE__, \ + __PRETTY_FUNCTION__); }G_STMT_END + + +g_assert +#define g_assert(expr) G_STMT_START{ \ + if (!(expr)) \ + g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_ERROR, \ + "file %s: line %d: assertion failed: (%s)", \ + __FILE__, \ + __LINE__, \ + #expr); }G_STMT_END + + +g_assert_not_reached +#define g_assert_not_reached() G_STMT_START{ \ + g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_ERROR, \ + "file %s: line %d: should not be reached", \ + __FILE__, \ + __LINE__); }G_STMT_END + + +g_return_if_fail +#define g_return_if_fail(expr) + + +g_return_val_if_fail +#define g_return_val_if_fail(expr,val) + + +g_return_if_fail +#define g_return_if_fail(expr) G_STMT_START{ \ + if (!(expr)) \ + { \ + g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_CRITICAL, \ + "file %s: line %d (%s): assertion `%s' failed.", \ + __FILE__, \ + __LINE__, \ + __PRETTY_FUNCTION__, \ + #expr); \ + return; \ + }; }G_STMT_END + + +g_return_val_if_fail +#define g_return_val_if_fail(expr,val) G_STMT_START{ \ + if (!(expr)) \ + { \ + g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_CRITICAL, \ + "file %s: line %d (%s): assertion `%s' failed.", \ + __FILE__, \ + __LINE__, \ + __PRETTY_FUNCTION__, \ + #expr); \ + return val; \ + }; }G_STMT_END + + +g_return_if_fail +#define g_return_if_fail(expr) G_STMT_START{ \ + if (!(expr)) \ + { \ + g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_CRITICAL, \ + "file %s: line %d: assertion `%s' failed.", \ + __FILE__, \ + __LINE__, \ + #expr); \ + return; \ + }; }G_STMT_END + + +g_return_val_if_fail +#define g_return_val_if_fail(expr, val) G_STMT_START{ \ + if (!(expr)) \ + { \ + g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_CRITICAL, \ + "file %s: line %d: assertion `%s' failed.", \ + __FILE__, \ + __LINE__, \ + #expr); \ + return val; \ + }; }G_STMT_END + + +gchar +typedef char gchar; + + +gshort +typedef short gshort; + + +glong +typedef long glong; + + +gint +typedef int gint; + + +gboolean +typedef gint gboolean; + + +guchar +typedef unsigned char guchar; + + +gushort +typedef unsigned short gushort; + + +gulong +typedef unsigned long gulong; + + +guint +typedef unsigned int guint; + + +gfloat +typedef float gfloat; + + +gdouble +typedef double gdouble; + + +gldouble +typedef long double gldouble; + + +gldouble +typedef double gldouble; + + +gpointer +typedef void* gpointer; + + +gconstpointer +typedef const void *gconstpointer; + + +gssize +typedef gint32 gssize; + + +gsize +typedef guint32 gsize; + + +GQuark +typedef guint32 GQuark; + + +GTime +typedef gint32 GTime; + + +G_LITTLE_ENDIAN +#define G_LITTLE_ENDIAN 1234 + + +G_BIG_ENDIAN +#define G_BIG_ENDIAN 4321 + + +G_PDP_ENDIAN +#define G_PDP_ENDIAN 3412 /* unused, need specific PDP check */ + + +GUINT16_SWAP_LE_BE_CONSTANT +#define GUINT16_SWAP_LE_BE_CONSTANT(val) ((guint16) ( \ + (((guint16) (val) & (guint16) 0x00ffU) << 8) | \ + (((guint16) (val) & (guint16) 0xff00U) >> 8))) + + +GUINT32_SWAP_LE_BE_CONSTANT +#define GUINT32_SWAP_LE_BE_CONSTANT(val) ((guint32) ( \ + (((guint32) (val) & (guint32) 0x000000ffU) << 24) | \ + (((guint32) (val) & (guint32) 0x0000ff00U) << 8) | \ + (((guint32) (val) & (guint32) 0x00ff0000U) >> 8) | \ + (((guint32) (val) & (guint32) 0xff000000U) >> 24))) + + +GUINT16_SWAP_LE_BE_X86 +# define GUINT16_SWAP_LE_BE_X86(val) \ + (__extension__ \ + ({ register guint16 __v; \ + if (__builtin_constant_p (val)) \ + __v = GUINT16_SWAP_LE_BE_CONSTANT (val); \ + else \ + __asm__ __const__ ("rorw $8, %w0" \ + : "=r" (__v) \ + : "0" ((guint16) (val))); \ + __v; })) + + +GUINT16_SWAP_LE_BE +# define GUINT16_SWAP_LE_BE(val) (GUINT16_SWAP_LE_BE_X86 (val)) + + +GUINT32_SWAP_LE_BE_X86 +# define GUINT32_SWAP_LE_BE_X86(val) \ + (__extension__ \ + ({ register guint32 __v; \ + if (__builtin_constant_p (val)) \ + __v = GUINT32_SWAP_LE_BE_CONSTANT (val); \ + else \ + __asm__ __const__ ("rorw $8, %w0\n\t" \ + "rorl $16, %0\n\t" \ + "rorw $8, %w0" \ + : "=r" (__v) \ + : "0" ((guint32) (val))); \ + __v; })) + + +GUINT32_SWAP_LE_BE_X86 +# define GUINT32_SWAP_LE_BE_X86(val) \ + (__extension__ \ + ({ register guint32 __v; \ + if (__builtin_constant_p (val)) \ + __v = GUINT32_SWAP_LE_BE_CONSTANT (val); \ + else \ + __asm__ __const__ ("bswap %0" \ + : "=r" (__v) \ + : "0" ((guint32) (val))); \ + __v; })) + + +GUINT32_SWAP_LE_BE +# define GUINT32_SWAP_LE_BE(val) (GUINT32_SWAP_LE_BE_X86 (val)) + + +GUINT16_SWAP_LE_BE +# define GUINT16_SWAP_LE_BE(val) (GUINT16_SWAP_LE_BE_CONSTANT (val)) + + +GUINT32_SWAP_LE_BE +# define GUINT32_SWAP_LE_BE(val) (GUINT32_SWAP_LE_BE_CONSTANT (val)) + + +GUINT64_SWAP_LE_BE_CONSTANT +# define GUINT64_SWAP_LE_BE_CONSTANT(val) ((guint64) ( \ + (((guint64) (val) & \ + (guint64) G_GINT64_CONSTANT(0x00000000000000ffU)) << 56) | \ + (((guint64) (val) & \ + (guint64) G_GINT64_CONSTANT(0x000000000000ff00U)) << 40) | \ + (((guint64) (val) & \ + (guint64) G_GINT64_CONSTANT(0x0000000000ff0000U)) << 24) | \ + (((guint64) (val) & \ + (guint64) G_GINT64_CONSTANT(0x00000000ff000000U)) << 8) | \ + (((guint64) (val) & \ + (guint64) G_GINT64_CONSTANT(0x000000ff00000000U)) >> 8) | \ + (((guint64) (val) & \ + (guint64) G_GINT64_CONSTANT(0x0000ff0000000000U)) >> 24) | \ + (((guint64) (val) & \ + (guint64) G_GINT64_CONSTANT(0x00ff000000000000U)) >> 40) | \ + (((guint64) (val) & \ + (guint64) G_GINT64_CONSTANT(0xff00000000000000U)) >> 56))) + + +GUINT64_SWAP_LE_BE_X86 +# define GUINT64_SWAP_LE_BE_X86(val) \ + (__extension__ \ + ({ union { guint64 __ll; \ + guint32 __l[2]; } __r; \ + if (__builtin_constant_p (val)) \ + __r.__ll = GUINT64_SWAP_LE_BE_CONSTANT (val); \ + else \ + { \ + union { guint64 __ll; \ + guint32 __l[2]; } __w; \ + __w.__ll = ((guint64) val); \ + __r.__l[0] = GUINT32_SWAP_LE_BE (__w.__l[1]); \ + __r.__l[1] = GUINT32_SWAP_LE_BE (__w.__l[0]); \ + } \ + __r.__ll; })) + + +GUINT64_SWAP_LE_BE +# define GUINT64_SWAP_LE_BE(val) (GUINT64_SWAP_LE_BE_X86 (val)) + + +GUINT64_SWAP_LE_BE +# define GUINT64_SWAP_LE_BE(val) (GUINT64_SWAP_LE_BE_CONSTANT(val)) + + +GUINT16_SWAP_LE_PDP +#define GUINT16_SWAP_LE_PDP(val) ((guint16) (val)) + + +GUINT16_SWAP_BE_PDP +#define GUINT16_SWAP_BE_PDP(val) (GUINT16_SWAP_LE_BE (val)) + + +GUINT32_SWAP_LE_PDP +#define GUINT32_SWAP_LE_PDP(val) ((guint32) ( \ + (((guint32) (val) & (guint32) 0x0000ffffU) << 16) | \ + (((guint32) (val) & (guint32) 0xffff0000U) >> 16))) + + +GUINT32_SWAP_BE_PDP +#define GUINT32_SWAP_BE_PDP(val) ((guint32) ( \ + (((guint32) (val) & (guint32) 0x00ff00ffU) << 8) | \ + (((guint32) (val) & (guint32) 0xff00ff00U) >> 8))) + + +GINT16_FROM_LE +#define GINT16_FROM_LE(val) (GINT16_TO_LE (val)) + + +GUINT16_FROM_LE +#define GUINT16_FROM_LE(val) (GUINT16_TO_LE (val)) + + +GINT16_FROM_BE +#define GINT16_FROM_BE(val) (GINT16_TO_BE (val)) + + +GUINT16_FROM_BE +#define GUINT16_FROM_BE(val) (GUINT16_TO_BE (val)) + + +GINT32_FROM_LE +#define GINT32_FROM_LE(val) (GINT32_TO_LE (val)) + + +GUINT32_FROM_LE +#define GUINT32_FROM_LE(val) (GUINT32_TO_LE (val)) + + +GINT32_FROM_BE +#define GINT32_FROM_BE(val) (GINT32_TO_BE (val)) + + +GUINT32_FROM_BE +#define GUINT32_FROM_BE(val) (GUINT32_TO_BE (val)) + + +GINT64_FROM_LE +#define GINT64_FROM_LE(val) (GINT64_TO_LE (val)) + + +GUINT64_FROM_LE +#define GUINT64_FROM_LE(val) (GUINT64_TO_LE (val)) + + +GINT64_FROM_BE +#define GINT64_FROM_BE(val) (GINT64_TO_BE (val)) + + +GUINT64_FROM_BE +#define GUINT64_FROM_BE(val) (GUINT64_TO_BE (val)) + + +GLONG_FROM_LE +#define GLONG_FROM_LE(val) (GLONG_TO_LE (val)) + + +GULONG_FROM_LE +#define GULONG_FROM_LE(val) (GULONG_TO_LE (val)) + + +GLONG_FROM_BE +#define GLONG_FROM_BE(val) (GLONG_TO_BE (val)) + + +GULONG_FROM_BE +#define GULONG_FROM_BE(val) (GULONG_TO_BE (val)) + + +GINT_FROM_LE +#define GINT_FROM_LE(val) (GINT_TO_LE (val)) + + +GUINT_FROM_LE +#define GUINT_FROM_LE(val) (GUINT_TO_LE (val)) + + +GINT_FROM_BE +#define GINT_FROM_BE(val) (GINT_TO_BE (val)) + + +GUINT_FROM_BE +#define GUINT_FROM_BE(val) (GUINT_TO_BE (val)) + + +g_ntohl +#define g_ntohl(val) (GUINT32_FROM_BE (val)) + + +g_ntohs +#define g_ntohs(val) (GUINT16_FROM_BE (val)) + + +g_htonl +#define g_htonl(val) (GUINT32_TO_BE (val)) + + +g_htons +#define g_htons(val) (GUINT16_TO_BE (val)) + + +GUTILS_C_VAR +# define GUTILS_C_VAR __declspec(dllexport) + + +GUTILS_C_VAR +# define GUTILS_C_VAR extern __declspec(dllimport) + + +GUTILS_C_VAR +# define GUTILS_C_VAR extern + + +GLIB_CHECK_VERSION +#define GLIB_CHECK_VERSION(major,minor,micro) \ + (GLIB_MAJOR_VERSION > (major) || \ + (GLIB_MAJOR_VERSION == (major) && GLIB_MINOR_VERSION > (minor)) || \ + (GLIB_MAJOR_VERSION == (major) && GLIB_MINOR_VERSION == (minor) && \ + GLIB_MICRO_VERSION >= (micro))) + + +GAllocator + + +GArray + + +GByteArray + + +GCache + + +GCompletion + + +GData + + +GDebugKey + + +GHashTable + + +GHook + + +GHookList + + +GList + + +GMemChunk + + +GNode + + +GPtrArray + + +GRelation + + +GScanner + + +GScannerConfig + + +GSList + + +GString + + +GStringChunk + + +GTimer + + +GTree + + +GTuples + + +GIOChannel + + +GTraverseFlags +typedef enum +{ + G_TRAVERSE_LEAFS = 1 << 0, + G_TRAVERSE_NON_LEAFS = 1 << 1, + G_TRAVERSE_ALL = G_TRAVERSE_LEAFS | G_TRAVERSE_NON_LEAFS, + G_TRAVERSE_MASK = 0x03 +} GTraverseFlags; + + +GTraverseType +typedef enum +{ + G_IN_ORDER, + G_PRE_ORDER, + G_POST_ORDER, + G_LEVEL_ORDER +} GTraverseType; + + +G_LOG_LEVEL_USER_SHIFT +#define G_LOG_LEVEL_USER_SHIFT (8) + + +GLogLevelFlags +typedef enum +{ + /* log flags */ + G_LOG_FLAG_RECURSION = 1 << 0, + G_LOG_FLAG_FATAL = 1 << 1, + + /* GLib log levels */ + G_LOG_LEVEL_ERROR = 1 << 2, /* always fatal */ + G_LOG_LEVEL_CRITICAL = 1 << 3, + G_LOG_LEVEL_WARNING = 1 << 4, + G_LOG_LEVEL_MESSAGE = 1 << 5, + G_LOG_LEVEL_INFO = 1 << 6, + G_LOG_LEVEL_DEBUG = 1 << 7, + + G_LOG_LEVEL_MASK = ~(G_LOG_FLAG_RECURSION | G_LOG_FLAG_FATAL) +} GLogLevelFlags; + + +G_LOG_FATAL_MASK +#define G_LOG_FATAL_MASK (G_LOG_FLAG_RECURSION | G_LOG_LEVEL_ERROR) + + +GCacheNewFunc +gpointer +gpointer key + + +GCacheDupFunc +gpointer +gpointer value + + +GCacheDestroyFunc +void +gpointer value + + +GCompareFunc +gint +gconstpointer a, + gconstpointer b + + +GCompletionFunc +gchar * +gpointer + + +GDestroyNotify +void +gpointer data + + +GDataForeachFunc +void +GQuark key_id, + gpointer data, + gpointer user_data + + +GFunc +void +gpointer data, + gpointer user_data + + +GHashFunc +guint +gconstpointer key + + +GFreeFunc +void +gpointer data + + +GHFunc +void +gpointer key, + gpointer value, + gpointer user_data + + +GHRFunc +gboolean +gpointer key, + gpointer value, + gpointer user_data + + +GHookCompareFunc +gint +GHook *new_hook, + GHook *sibling + + +GHookFindFunc +gboolean +GHook *hook, + gpointer data + + +GHookMarshaller +void +GHook *hook, + gpointer data + + +GHookCheckMarshaller +gboolean +GHook *hook, + gpointer data + + +GHookFunc +void +gpointer data + + +GHookCheckFunc +gboolean +gpointer data + + +GHookFreeFunc +void +GHookList *hook_list, + GHook *hook + + +GLogFunc +void +const gchar *log_domain, + GLogLevelFlags log_level, + const gchar *message, + gpointer user_data + + +GNodeTraverseFunc +gboolean +GNode *node, + gpointer data + + +GNodeForeachFunc +void +GNode *node, + gpointer data + + +GSearchFunc +gint +gpointer key, + gpointer data + + +GScannerMsgFunc +void +GScanner *scanner, + gchar *message, + gint error + + +GTraverseFunc +gint +gpointer key, + gpointer value, + gpointer data + + +GVoidFunc +void +void + + +GList +struct GList +{ + gpointer data; + GList *next; + GList *prev; +}; + + +GSList +struct GSList +{ + gpointer data; + GSList *next; +}; + + +GString +struct GString +{ + gchar *str; + gint len; +}; + + +GArray +struct GArray +{ + gchar *data; + guint len; +}; + + +GByteArray +struct GByteArray +{ + guint8 *data; + guint len; +}; + + +GPtrArray +struct GPtrArray +{ + gpointer *pdata; + guint len; +}; + + +GTuples +struct GTuples +{ + guint len; +}; + + +GDebugKey +struct GDebugKey +{ + gchar *key; + guint value; +}; + + +g_list_push_allocator +void +GAllocator *allocator + + +g_list_pop_allocator +void +void + + +g_list_alloc +GList * +void + + +g_list_free +void +GList *list + + +g_list_free_1 +void +GList *list + + +g_list_append +GList * +GList *list,gpointer data + + +g_list_prepend +GList * +GList *list,gpointer data + + +g_list_insert +GList * +GList *list,gpointer data,gint position + + +g_list_insert_sorted +GList * +GList *list,gpointer data,GCompareFunc func + + +g_list_concat +GList * +GList *list1,GList *list2 + + +g_list_remove +GList * +GList *list,gpointer data + + +g_list_remove_link +GList * +GList *list,GList *llink + + +g_list_reverse +GList * +GList *list + + +g_list_copy +GList * +GList *list + + +g_list_nth +GList * +GList *list,guint n + + +g_list_find +GList * +GList *list,gpointer data + + +g_list_find_custom +GList * +GList *list,gpointer data,GCompareFunc func + + +g_list_position +gint +GList *list,GList *llink + + +g_list_index +gint +GList *list,gpointer data + + +g_list_last +GList * +GList *list + + +g_list_first +GList * +GList *list + + +g_list_length +guint +GList *list + + +g_list_foreach +void +GList *list,GFunc func,gpointer user_data + + +g_list_sort +GList * +GList *list,GCompareFunc compare_func + + +g_list_nth_data +gpointer +GList *list,guint n + + +g_list_previous +#define g_list_previous(list) ((list) ? (((GList *)(list))->prev) : NULL) + + +g_list_next +#define g_list_next(list) ((list) ? (((GList *)(list))->next) : NULL) + + +g_slist_push_allocator +void +GAllocator *allocator + + +g_slist_pop_allocator +void +void + + +g_slist_alloc +GSList * +void + + +g_slist_free +void +GSList *list + + +g_slist_free_1 +void +GSList *list + + +g_slist_append +GSList * +GSList *list,gpointer data + + +g_slist_prepend +GSList * +GSList *list,gpointer data + + +g_slist_insert +GSList * +GSList *list,gpointer data,gint position + + +g_slist_insert_sorted +GSList * +GSList *list,gpointer data,GCompareFunc func + + +g_slist_concat +GSList * +GSList *list1,GSList *list2 + + +g_slist_remove +GSList * +GSList *list,gpointer data + + +g_slist_remove_link +GSList * +GSList *list,GSList *llink + + +g_slist_reverse +GSList * +GSList *list + + +g_slist_copy +GSList * +GSList *list + + +g_slist_nth +GSList * +GSList *list,guint n + + +g_slist_find +GSList * +GSList *list,gpointer data + + +g_slist_find_custom +GSList * +GSList *list,gpointer data,GCompareFunc func + + +g_slist_position +gint +GSList *list,GSList *llink + + +g_slist_index +gint +GSList *list,gpointer data + + +g_slist_last +GSList * +GSList *list + + +g_slist_length +guint +GSList *list + + +g_slist_foreach +void +GSList *list,GFunc func,gpointer user_data + + +g_slist_sort +GSList * +GSList *list,GCompareFunc compare_func + + +g_slist_nth_data +gpointer +GSList *list,guint n + + +g_slist_next +#define g_slist_next(slist) ((slist) ? (((GSList *)(slist))->next) : NULL) + + +g_hash_table_new +GHashTable * +GHashFunc hash_func,GCompareFunc key_compare_func + + +g_hash_table_destroy +void +GHashTable *hash_table + + +g_hash_table_insert +void +GHashTable *hash_table,gpointer key,gpointer value + + +g_hash_table_remove +void +GHashTable *hash_table,gconstpointer key + + +g_hash_table_lookup +gpointer +GHashTable *hash_table,gconstpointer key + + +g_hash_table_lookup_extended +gboolean +GHashTable *hash_table,gconstpointer lookup_key,gpointer *orig_key,gpointer *value + + +g_hash_table_freeze +void +GHashTable *hash_table + + +g_hash_table_thaw +void +GHashTable *hash_table + + +g_hash_table_foreach +void +GHashTable *hash_table,GHFunc func,gpointer user_data + + +g_hash_table_foreach_remove +guint +GHashTable *hash_table,GHRFunc func,gpointer user_data + + +g_hash_table_size +guint +GHashTable *hash_table + + +g_cache_new +GCache * +GCacheNewFunc value_new_func,GCacheDestroyFunc value_destroy_func,GCacheDupFunc key_dup_func,GCacheDestroyFunc key_destroy_func,GHashFunc hash_key_func,GHashFunc hash_value_func,GCompareFunc key_compare_func + + +g_cache_destroy +void +GCache *cache + + +g_cache_insert +gpointer +GCache *cache,gpointer key + + +g_cache_remove +void +GCache *cache,gpointer value + + +g_cache_key_foreach +void +GCache *cache,GHFunc func,gpointer user_data + + +g_cache_value_foreach +void +GCache *cache,GHFunc func,gpointer user_data + + +g_tree_new +GTree * +GCompareFunc key_compare_func + + +g_tree_destroy +void +GTree *tree + + +g_tree_insert +void +GTree *tree,gpointer key,gpointer value + + +g_tree_remove +void +GTree *tree,gpointer key + + +g_tree_lookup +gpointer +GTree *tree,gpointer key + + +g_tree_traverse +void +GTree *tree,GTraverseFunc traverse_func,GTraverseType traverse_type,gpointer data + + +g_tree_search +gpointer +GTree *tree,GSearchFunc search_func,gpointer data + + +g_tree_height +gint +GTree *tree + + +g_tree_nnodes +gint +GTree *tree + + +GNode +struct GNode +{ + gpointer data; + GNode *next; + GNode *prev; + GNode *parent; + GNode *children; +}; + + +G_NODE_IS_ROOT +#define G_NODE_IS_ROOT(node) (((GNode*) (node))->parent == NULL && \ + ((GNode*) (node))->prev == NULL && \ + ((GNode*) (node))->next == NULL) + + +G_NODE_IS_LEAF +#define G_NODE_IS_LEAF(node) (((GNode*) (node))->children == NULL) + + +g_node_push_allocator +void +GAllocator *allocator + + +g_node_pop_allocator +void +void + + +g_node_new +GNode * +gpointer data + + +g_node_destroy +void +GNode *root + + +g_node_unlink +void +GNode *node + + +g_node_insert +GNode * +GNode *parent,gint position,GNode *node + + +g_node_insert_before +GNode * +GNode *parent,GNode *sibling,GNode *node + + +g_node_prepend +GNode * +GNode *parent,GNode *node + + +g_node_n_nodes +guint +GNode *root,GTraverseFlags flags + + +g_node_get_root +GNode * +GNode *node + + +g_node_is_ancestor +gboolean +GNode *node,GNode *descendant + + +g_node_depth +guint +GNode *node + + +g_node_find +GNode * +GNode *root,GTraverseType order,GTraverseFlags flags,gpointer data + + +g_node_append +#define g_node_append(parent, node) \ + g_node_insert_before ((parent), NULL, (node)) + + +g_node_insert_data +#define g_node_insert_data(parent, position, data) \ + g_node_insert ((parent), (position), g_node_new (data)) + + +g_node_insert_data_before +#define g_node_insert_data_before(parent, sibling, data) \ + g_node_insert_before ((parent), (sibling), g_node_new (data)) + + +g_node_prepend_data +#define g_node_prepend_data(parent, data) \ + g_node_prepend ((parent), g_node_new (data)) + + +g_node_append_data +#define g_node_append_data(parent, data) \ + g_node_insert_before ((parent), NULL, g_node_new (data)) + + +g_node_traverse +void +GNode *root,GTraverseType order,GTraverseFlags flags,gint max_depth,GNodeTraverseFunc func,gpointer data + + +g_node_max_height +guint +GNode *root + + +g_node_children_foreach +void +GNode *node,GTraverseFlags flags,GNodeForeachFunc func,gpointer data + + +g_node_reverse_children +void +GNode *node + + +g_node_n_children +guint +GNode *node + + +g_node_nth_child +GNode * +GNode *node,guint n + + +g_node_last_child +GNode * +GNode *node + + +g_node_find_child +GNode * +GNode *node,GTraverseFlags flags,gpointer data + + +g_node_child_position +gint +GNode *node,GNode *child + + +g_node_child_index +gint +GNode *node,gpointer data + + +g_node_first_sibling +GNode * +GNode *node + + +g_node_last_sibling +GNode * +GNode *node + + +g_node_prev_sibling +#define g_node_prev_sibling(node) ((node) ? \ + ((GNode*) (node))->prev : NULL) + + +g_node_next_sibling +#define g_node_next_sibling(node) ((node) ? \ + ((GNode*) (node))->next : NULL) + + +g_node_first_child +#define g_node_first_child(node) ((node) ? \ + ((GNode*) (node))->children : NULL) + + +G_HOOK_FLAG_USER_SHIFT +#define G_HOOK_FLAG_USER_SHIFT (4) + + +GHookFlagMask +typedef enum +{ + G_HOOK_FLAG_ACTIVE = 1 << 0, + G_HOOK_FLAG_IN_CALL = 1 << 1, + G_HOOK_FLAG_MASK = 0x0f +} GHookFlagMask; + + +G_HOOK_DEFERRED_DESTROY +#define G_HOOK_DEFERRED_DESTROY ((GHookFreeFunc) 0x01) + + +GHookList +struct GHookList +{ + guint seq_id; + guint hook_size; + guint is_setup : 1; + GHook *hooks; + GMemChunk *hook_memchunk; + GHookFreeFunc hook_free; /* virtual function */ + GHookFreeFunc hook_destroy; /* virtual function */ +}; + + +GHook +struct GHook +{ + gpointer data; + GHook *next; + GHook *prev; + guint ref_count; + guint hook_id; + guint flags; + gpointer func; + GDestroyNotify destroy; +}; + + +G_HOOK_ACTIVE +#define G_HOOK_ACTIVE(hook) ((((GHook*) hook)->flags & \ + G_HOOK_FLAG_ACTIVE) != 0) + + +G_HOOK_IN_CALL +#define G_HOOK_IN_CALL(hook) ((((GHook*) hook)->flags & \ + G_HOOK_FLAG_IN_CALL) != 0) + + +G_HOOK_IS_VALID +#define G_HOOK_IS_VALID(hook) (((GHook*) hook)->hook_id != 0 && \ + G_HOOK_ACTIVE (hook)) + + +G_HOOK_IS_UNLINKED +#define G_HOOK_IS_UNLINKED(hook) (((GHook*) hook)->next == NULL && \ + ((GHook*) hook)->prev == NULL && \ + ((GHook*) hook)->hook_id == 0 && \ + ((GHook*) hook)->ref_count == 0) + + +g_hook_list_init +void +GHookList *hook_list,guint hook_size + + +g_hook_list_clear +void +GHookList *hook_list + + +g_hook_alloc +GHook * +GHookList *hook_list + + +g_hook_free +void +GHookList *hook_list,GHook *hook + + +g_hook_ref +void +GHookList *hook_list,GHook *hook + + +g_hook_unref +void +GHookList *hook_list,GHook *hook + + +g_hook_destroy +gboolean +GHookList *hook_list,guint hook_id + + +g_hook_destroy_link +void +GHookList *hook_list,GHook *hook + + +g_hook_prepend +void +GHookList *hook_list,GHook *hook + + +g_hook_insert_before +void +GHookList *hook_list,GHook *sibling,GHook *hook + + +g_hook_insert_sorted +void +GHookList *hook_list,GHook *hook,GHookCompareFunc func + + +g_hook_get +GHook * +GHookList *hook_list,guint hook_id + + +g_hook_find +GHook * +GHookList *hook_list,gboolean need_valids,GHookFindFunc func,gpointer data + + +g_hook_find_data +GHook * +GHookList *hook_list,gboolean need_valids,gpointer data + + +g_hook_find_func +GHook * +GHookList *hook_list,gboolean need_valids,gpointer func + + +g_hook_find_func_data +GHook * +GHookList *hook_list,gboolean need_valids,gpointer func,gpointer data + + +g_hook_first_valid +GHook * +GHookList *hook_list,gboolean may_be_in_call + + +g_hook_next_valid +GHook * +GHookList *hook_list,GHook *hook,gboolean may_be_in_call + + +g_hook_compare_ids +gint +GHook *new_hook,GHook *sibling + + +g_hook_append +#define g_hook_append( hook_list, hook ) \ + g_hook_insert_before ((hook_list), NULL, (hook)) + + +g_hook_list_invoke +void +GHookList *hook_list,gboolean may_recurse + + +g_hook_list_invoke_check +void +GHookList *hook_list,gboolean may_recurse + + +g_hook_list_marshal +void +GHookList *hook_list,gboolean may_recurse,GHookMarshaller marshaller,gpointer data + + +g_hook_list_marshal_check +void +GHookList *hook_list,gboolean may_recurse,GHookCheckMarshaller marshaller,gpointer data + + +g_on_error_query +void +const gchar *prg_name + + +g_on_error_stack_trace +void +const gchar *prg_name + + +g_log_domain_glib +extern const gchar *g_log_domain_glib; + + +g_log_set_handler +guint +const gchar *log_domain,GLogLevelFlags log_levels,GLogFunc log_func,gpointer user_data + + +g_log_remove_handler +void +const gchar *log_domain,guint handler_id + + +g_log_default_handler +void +const gchar *log_domain,GLogLevelFlags log_level,const gchar *message,gpointer unused_data + + +g_log +void +const gchar *log_domain,GLogLevelFlags log_level,const gchar *format,... + + +g_logv +void +const gchar *log_domain,GLogLevelFlags log_level,const gchar *format,va_list args + + +g_log_set_fatal_mask +GLogLevelFlags +const gchar *log_domain,GLogLevelFlags fatal_mask + + +g_log_set_always_fatal +GLogLevelFlags +GLogLevelFlags fatal_mask + + +G_LOG_DOMAIN +#define G_LOG_DOMAIN ((gchar*) 0) + + +g_error +#define g_error(format, args...) g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_ERROR, \ + format, ##args) + + +g_message +#define g_message(format, args...) g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_MESSAGE, \ + format, ##args) + + +g_warning +#define g_warning(format, args...) g_log (G_LOG_DOMAIN, \ + G_LOG_LEVEL_WARNING, \ + format, ##args) + + +GPrintFunc +void +const gchar *string + + +g_print +void +const gchar *format,... + + +g_set_print_handler +GPrintFunc +GPrintFunc func + + +g_printerr +void +const gchar *format,... + + +g_set_printerr_handler +GPrintFunc +GPrintFunc func + + +GErrorFunc +void +const gchar *str + + +GWarningFunc +void +const gchar *str + + +g_set_error_handler +GErrorFunc +GErrorFunc func + + +g_set_warning_handler +GWarningFunc +GWarningFunc func + + +g_set_message_handler +GPrintFunc +GPrintFunc func + + +g_malloc +#define g_malloc(size) ((gpointer) MALLOC (size)) + + +g_malloc0 +#define g_malloc0(size) ((gpointer) CALLOC (char, size)) + + +g_realloc +#define g_realloc(mem,size) ((gpointer) REALLOC (mem, char, size)) + + +g_free +#define g_free(mem) FREE (mem) + + +g_malloc +gpointer +gulong size + + +g_malloc0 +gpointer +gulong size + + +g_realloc +gpointer +gpointer mem,gulong size + + +g_free +void +gpointer mem + + +g_mem_profile +void +void + + +g_mem_check +void +gpointer mem + + +g_allocator_new +GAllocator * +const gchar *name,guint n_preallocs + + +g_allocator_free +void +GAllocator *allocator + + +G_ALLOCATOR_LIST +#define G_ALLOCATOR_LIST (1) + + +G_ALLOCATOR_SLIST +#define G_ALLOCATOR_SLIST (2) + + +G_ALLOCATOR_NODE +#define G_ALLOCATOR_NODE (3) + + +G_ALLOC_ONLY +#define G_ALLOC_ONLY 1 + + +G_ALLOC_AND_FREE +#define G_ALLOC_AND_FREE 2 + + +g_mem_chunk_new +GMemChunk * +gchar *name,gint atom_size,gulong area_size,gint type + + +g_mem_chunk_destroy +void +GMemChunk *mem_chunk + + +g_mem_chunk_alloc +gpointer +GMemChunk *mem_chunk + + +g_mem_chunk_alloc0 +gpointer +GMemChunk *mem_chunk + + +g_mem_chunk_free +void +GMemChunk *mem_chunk,gpointer mem + + +g_mem_chunk_clean +void +GMemChunk *mem_chunk + + +g_mem_chunk_reset +void +GMemChunk *mem_chunk + + +g_mem_chunk_print +void +GMemChunk *mem_chunk + + +g_mem_chunk_info +void +void + + +g_blow_chunks +void +void + + +g_timer_new +GTimer * +void + + +g_timer_destroy +void +GTimer *timer + + +g_timer_start +void +GTimer *timer + + +g_timer_stop +void +GTimer *timer + + +g_timer_reset +void +GTimer *timer + + +g_timer_elapsed +gdouble +GTimer *timer,gulong *microseconds + + +G_STR_DELIMITERS +#define G_STR_DELIMITERS "_-|> <." + + +g_strdelimit +gchar * +gchar *string,const gchar *delimiters,gchar new_delimiter + + +g_strtod +gdouble +const gchar *nptr,gchar **endptr + + +g_strerror +gchar * +gint errnum + + +g_strsignal +gchar * +gint signum + + +g_strcasecmp +gint +const gchar *s1,const gchar *s2 + + +g_strncasecmp +gint +const gchar *s1,const gchar *s2,guint n + + +g_strdown +void +gchar *string + + +g_strup +void +gchar *string + + +g_strreverse +void +gchar *string + + +g_strchug +gchar * +gchar *string + + +g_strchomp +gchar * +gchar *string + + +g_strstrip +#define g_strstrip( string ) g_strchomp (g_strchug (string)) + + +g_strdup +gchar * +const gchar *str + + +g_strdup_printf +gchar * +const gchar *format,... + + +g_strdup_vprintf +gchar * +const gchar *format,va_list args + + +g_strndup +gchar * +const gchar *str,guint n + + +g_strnfill +gchar * +guint length,gchar fill_char + + +g_strconcat +gchar * +const gchar *string1,... + + +g_strjoin +gchar * +const gchar *separator,... + + +g_strescape +gchar * +gchar *string + + +g_memdup +gpointer +gconstpointer mem,guint byte_size + + +g_strsplit +gchar ** +const gchar *string,const gchar *delimiter,gint max_tokens + + +g_strjoinv +gchar * +const gchar *separator,gchar **str_array + + +g_strfreev +void +gchar **str_array + + +g_printf_string_upper_bound +guint +const gchar* format,va_list args + + +g_get_user_name +gchar * +void + + +g_get_real_name +gchar * +void + + +g_get_home_dir +gchar * +void + + +g_get_tmp_dir +gchar * +void + + +g_get_prgname +gchar * +void + + +g_set_prgname +void +const gchar *prgname + + +g_parse_debug_string +guint +const gchar *string,GDebugKey *keys,guint nkeys + + +g_snprintf +gint +gchar *string,gulong n,gchar const *format,... + + +g_vsnprintf +gint +gchar *string,gulong n,gchar const *format,va_list args + + +g_basename +gchar * +const gchar *file_name + + +g_path_is_absolute +gboolean +const gchar *file_name + + +g_path_skip_root +gchar * +gchar *file_name + + +g_dirname +gchar * +const gchar *file_name + + +g_get_current_dir +gchar * +void + + +g_getenv +gchar * +const gchar *variable + + +g_atexit +void +GVoidFunc func + + +g_bit_nth_lsf +gint +guint32 mask,gint nth_bit + + +g_bit_nth_msf +gint +guint32 mask,gint nth_bit + + +g_bit_storage +guint +guint number + + +g_string_chunk_new +GStringChunk * +gint size + + +g_string_chunk_free +void +GStringChunk *chunk + + +g_string_chunk_insert +gchar * +GStringChunk *chunk,const gchar *string + + +g_string_chunk_insert_const +gchar * +GStringChunk *chunk,const gchar *string + + +g_string_new +GString * +const gchar *init + + +g_string_sized_new +GString * +guint dfl_size + + +g_string_free +void +GString *string,gint free_segment + + +g_string_assign +GString * +GString *lval,const gchar *rval + + +g_string_truncate +GString * +GString *string,gint len + + +g_string_append +GString * +GString *string,const gchar *val + + +g_string_append_c +GString * +GString *string,gchar c + + +g_string_prepend +GString * +GString *string,const gchar *val + + +g_string_prepend_c +GString * +GString *string,gchar c + + +g_string_insert +GString * +GString *string,gint pos,const gchar *val + + +g_string_insert_c +GString * +GString *string,gint pos,gchar c + + +g_string_erase +GString * +GString *string,gint pos,gint len + + +g_string_down +GString * +GString *string + + +g_string_up +GString * +GString *string + + +g_string_sprintf +void +GString *string,const gchar *format,... + + +g_string_sprintfa +void +GString *string,const gchar *format,... + + +g_array_append_val +#define g_array_append_val(a,v) g_array_append_vals (a, &v, 1) + + +g_array_prepend_val +#define g_array_prepend_val(a,v) g_array_prepend_vals (a, &v, 1) + + +g_array_insert_val +#define g_array_insert_val(a,i,v) g_array_insert_vals (a, i, &v, 1) + + +g_array_index +#define g_array_index(a,t,i) (((t*) (a)->data) [(i)]) + + +g_array_new +GArray * +gboolean zero_terminated,gboolean clear,guint element_size + + +g_array_free +void +GArray *array,gboolean free_segment + + +g_array_append_vals +GArray * +GArray *array,gconstpointer data,guint len + + +g_array_prepend_vals +GArray * +GArray *array,gconstpointer data,guint len + + +g_array_insert_vals +GArray * +GArray *array,guint index,gconstpointer data,guint len + + +g_array_set_size +GArray * +GArray *array,guint length + + +g_array_remove_index +GArray * +GArray *array,guint index + + +g_array_remove_index_fast +GArray * +GArray *array,guint index + + +g_ptr_array_index +#define g_ptr_array_index(array,index) (array->pdata)[index] + + +g_ptr_array_new +GPtrArray * +void + + +g_ptr_array_free +void +GPtrArray *array,gboolean free_seg + + +g_ptr_array_set_size +void +GPtrArray *array,gint length + + +g_ptr_array_remove_index +gpointer +GPtrArray *array,guint index + + +g_ptr_array_remove_index_fast +gpointer +GPtrArray *array,guint index + + +g_ptr_array_remove +gboolean +GPtrArray *array,gpointer data + + +g_ptr_array_remove_fast +gboolean +GPtrArray *array,gpointer data + + +g_ptr_array_add +void +GPtrArray *array,gpointer data + + +g_byte_array_new +GByteArray * +void + + +g_byte_array_free +void +GByteArray *array,gboolean free_segment + + +g_byte_array_append +GByteArray * +GByteArray *array,const guint8 *data,guint len + + +g_byte_array_prepend +GByteArray * +GByteArray *array,const guint8 *data,guint len + + +g_byte_array_set_size +GByteArray * +GByteArray *array,guint length + + +g_byte_array_remove_index +GByteArray * +GByteArray *array,guint index + + +g_byte_array_remove_index_fast +GByteArray * +GByteArray *array,guint index + + +g_str_equal +gint +gconstpointer v,gconstpointer v2 + + +g_str_hash +guint +gconstpointer v + + +g_int_equal +gint +gconstpointer v,gconstpointer v2 + + +g_int_hash +guint +gconstpointer v + + +g_direct_hash +guint +gconstpointer v + + +g_direct_equal +gint +gconstpointer v,gconstpointer v2 + + +g_quark_try_string +GQuark +const gchar *string + + +g_quark_from_static_string +GQuark +const gchar *string + + +g_quark_from_string +GQuark +const gchar *string + + +g_quark_to_string +gchar * +GQuark quark + + +g_datalist_init +void +GData **datalist + + +g_datalist_clear +void +GData **datalist + + +g_datalist_id_get_data +gpointer +GData **datalist,GQuark key_id + + +g_datalist_id_set_data_full +void +GData **datalist,GQuark key_id,gpointer data,GDestroyNotify destroy_func + + +g_datalist_id_remove_no_notify +void +GData **datalist,GQuark key_id + + +g_datalist_foreach +void +GData **datalist,GDataForeachFunc func,gpointer user_data + + +g_datalist_id_set_data +#define g_datalist_id_set_data(dl, q, d) \ + g_datalist_id_set_data_full ((dl), (q), (d), NULL) + + +g_datalist_id_remove_data +#define g_datalist_id_remove_data(dl, q) \ + g_datalist_id_set_data ((dl), (q), NULL) + + +g_datalist_get_data +#define g_datalist_get_data(dl, k) \ + (g_datalist_id_get_data ((dl), g_quark_try_string (k))) + + +g_datalist_set_data_full +#define g_datalist_set_data_full(dl, k, d, f) \ + g_datalist_id_set_data_full ((dl), g_quark_from_string (k), (d), (f)) + + +g_datalist_remove_no_notify +#define g_datalist_remove_no_notify(dl, k) \ + g_datalist_id_remove_no_notify ((dl), g_quark_try_string (k)) + + +g_datalist_set_data +#define g_datalist_set_data(dl, k, d) \ + g_datalist_set_data_full ((dl), (k), (d), NULL) + + +g_datalist_remove_data +#define g_datalist_remove_data(dl, k) \ + g_datalist_id_set_data ((dl), g_quark_try_string (k), NULL) + + +g_dataset_destroy +void +gconstpointer dataset_location + + +g_dataset_id_get_data +gpointer +gconstpointer dataset_location,GQuark key_id + + +g_dataset_id_set_data_full +void +gconstpointer dataset_location,GQuark key_id,gpointer data,GDestroyNotify destroy_func + + +g_dataset_id_remove_no_notify +void +gconstpointer dataset_location,GQuark key_id + + +g_dataset_foreach +void +gconstpointer dataset_location,GDataForeachFunc func,gpointer user_data + + +g_dataset_id_set_data +#define g_dataset_id_set_data(l, k, d) \ + g_dataset_id_set_data_full ((l), (k), (d), NULL) + + +g_dataset_id_remove_data +#define g_dataset_id_remove_data(l, k) \ + g_dataset_id_set_data ((l), (k), NULL) + + +g_dataset_get_data +#define g_dataset_get_data(l, k) \ + (g_dataset_id_get_data ((l), g_quark_try_string (k))) + + +g_dataset_set_data_full +#define g_dataset_set_data_full(l, k, d, f) \ + g_dataset_id_set_data_full ((l), g_quark_from_string (k), (d), (f)) + + +g_dataset_remove_no_notify +#define g_dataset_remove_no_notify(l, k) \ + g_dataset_id_remove_no_notify ((l), g_quark_try_string (k)) + + +g_dataset_set_data +#define g_dataset_set_data(l, k, d) \ + g_dataset_set_data_full ((l), (k), (d), NULL) + + +g_dataset_remove_data +#define g_dataset_remove_data(l, k) \ + g_dataset_id_set_data ((l), g_quark_try_string (k), NULL) + + +G_CSET_A_2_Z +#define G_CSET_A_2_Z "ABCDEFGHIJKLMNOPQRSTUVWXYZ" + + +G_CSET_a_2_z +#define G_CSET_a_2_z "abcdefghijklmnopqrstuvwxyz" + + +G_CSET_LATINC +#define G_CSET_LATINC "\300\301\302\303\304\305\306"\ + "\307\310\311\312\313\314\315\316\317\320"\ + "\321\322\323\324\325\326"\ + "\330\331\332\333\334\335\336" + + +G_CSET_LATINS +#define G_CSET_LATINS "\337\340\341\342\343\344\345\346"\ + "\347\350\351\352\353\354\355\356\357\360"\ + "\361\362\363\364\365\366"\ + "\370\371\372\373\374\375\376\377" + + +GErrorType +typedef enum +{ + G_ERR_UNKNOWN, + G_ERR_UNEXP_EOF, + G_ERR_UNEXP_EOF_IN_STRING, + G_ERR_UNEXP_EOF_IN_COMMENT, + G_ERR_NON_DIGIT_IN_CONST, + G_ERR_DIGIT_RADIX, + G_ERR_FLOAT_RADIX, + G_ERR_FLOAT_MALFORMED +} GErrorType; + + +GTokenType +typedef enum +{ + G_TOKEN_EOF = 0, + + G_TOKEN_LEFT_PAREN = '(', + G_TOKEN_RIGHT_PAREN = ')', + G_TOKEN_LEFT_CURLY = '{', + G_TOKEN_RIGHT_CURLY = '}', + G_TOKEN_LEFT_BRACE = '[', + G_TOKEN_RIGHT_BRACE = ']', + G_TOKEN_EQUAL_SIGN = '=', + G_TOKEN_COMMA = ',', + + G_TOKEN_NONE = 256, + + G_TOKEN_ERROR, + + G_TOKEN_CHAR, + G_TOKEN_BINARY, + G_TOKEN_OCTAL, + G_TOKEN_INT, + G_TOKEN_HEX, + G_TOKEN_FLOAT, + G_TOKEN_STRING, + + G_TOKEN_SYMBOL, + G_TOKEN_IDENTIFIER, + G_TOKEN_IDENTIFIER_NULL, + + G_TOKEN_COMMENT_SINGLE, + G_TOKEN_COMMENT_MULTI, + G_TOKEN_LAST +} GTokenType; + + +GTokenValue +union GTokenValue +{ + gpointer v_symbol; + gchar *v_identifier; + gulong v_binary; + gulong v_octal; + gulong v_int; + gdouble v_float; + gulong v_hex; + gchar *v_string; + gchar *v_comment; + guchar v_char; + guint v_error; +}; + + +GScannerConfig +struct GScannerConfig +{ + /* Character sets + */ + gchar *cset_skip_characters; /* default: " \t\n" */ + gchar *cset_identifier_first; + gchar *cset_identifier_nth; + gchar *cpair_comment_single; /* default: "#\n" */ + + /* Should symbol lookup work case sensitive? + */ + guint case_sensitive : 1; + + /* Boolean values to be adjusted "on the fly" + * to configure scanning behaviour. + */ + guint skip_comment_multi : 1; /* C like comment */ + guint skip_comment_single : 1; /* single line comment */ + guint scan_comment_multi : 1; /* scan multi line comments? */ + guint scan_identifier : 1; + guint scan_identifier_1char : 1; + guint scan_identifier_NULL : 1; + guint scan_symbols : 1; + guint scan_binary : 1; + guint scan_octal : 1; + guint scan_float : 1; + guint scan_hex : 1; /* `0x0ff0' */ + guint scan_hex_dollar : 1; /* `$0ff0' */ + guint scan_string_sq : 1; /* string: 'anything' */ + guint scan_string_dq : 1; /* string: "\\-escapes!\n" */ + guint numbers_2_int : 1; /* bin, octal, hex => int */ + guint int_2_float : 1; /* int => G_TOKEN_FLOAT? */ + guint identifier_2_string : 1; + guint char_2_token : 1; /* return G_TOKEN_CHAR? */ + guint symbol_2_token : 1; + guint scope_0_fallback : 1; /* try scope 0 on lookups? */ +}; + + +GScanner +struct GScanner +{ + /* unused fields */ + gpointer user_data; + guint max_parse_errors; + + /* g_scanner_error() increments this field */ + guint parse_errors; + + /* name of input stream, featured by the default message handler */ + const gchar *input_name; + + /* data pointer for derived structures */ + gpointer derived_data; + + /* link into the scanner configuration */ + GScannerConfig *config; + + /* fields filled in after g_scanner_get_next_token() */ + GTokenType token; + GTokenValue value; + guint line; + guint position; + + /* fields filled in after g_scanner_peek_next_token() */ + GTokenType next_token; + GTokenValue next_value; + guint next_line; + guint next_position; + + /* to be considered private */ + GHashTable *symbol_table; + gint input_fd; + const gchar *text; + const gchar *text_end; + gchar *buffer; + guint scope_id; + + /* handler function for _warn and _error */ + GScannerMsgFunc msg_handler; +}; + + +g_scanner_new +GScanner * +GScannerConfig *config_templ + + +g_scanner_destroy +void +GScanner *scanner + + +g_scanner_input_file +void +GScanner *scanner,gint input_fd + + +g_scanner_sync_file_offset +void +GScanner *scanner + + +g_scanner_input_text +void +GScanner *scanner,const gchar *text,guint text_len + + +g_scanner_get_next_token +GTokenType +GScanner *scanner + + +g_scanner_peek_next_token +GTokenType +GScanner *scanner + + +g_scanner_cur_token +GTokenType +GScanner *scanner + + +g_scanner_cur_value +GTokenValue +GScanner *scanner + + +g_scanner_cur_line +guint +GScanner *scanner + + +g_scanner_cur_position +guint +GScanner *scanner + + +g_scanner_eof +gboolean +GScanner *scanner + + +g_scanner_set_scope +guint +GScanner *scanner,guint scope_id + + +g_scanner_scope_add_symbol +void +GScanner *scanner,guint scope_id,const gchar *symbol,gpointer value + + +g_scanner_scope_remove_symbol +void +GScanner *scanner,guint scope_id,const gchar *symbol + + +g_scanner_scope_lookup_symbol +gpointer +GScanner *scanner,guint scope_id,const gchar *symbol + + +g_scanner_scope_foreach_symbol +void +GScanner *scanner,guint scope_id,GHFunc func,gpointer user_data + + +g_scanner_lookup_symbol +gpointer +GScanner *scanner,const gchar *symbol + + +g_scanner_freeze_symbol_table +void +GScanner *scanner + + +g_scanner_thaw_symbol_table +void +GScanner *scanner + + +g_scanner_unexp_token +void +GScanner *scanner,GTokenType expected_token,const gchar *identifier_spec,const gchar *symbol_spec,const gchar *symbol_name,const gchar *message,gint is_error + + +g_scanner_error +void +GScanner *scanner,const gchar *format,... + + +g_scanner_warn +void +GScanner *scanner,const gchar *format,... + + +g_scanner_stat_mode +gint +const gchar *filename + + +g_scanner_add_symbol +#define g_scanner_add_symbol( scanner, symbol, value ) G_STMT_START { \ + g_scanner_scope_add_symbol ((scanner), 0, (symbol), (value)); \ +} G_STMT_END + + +g_scanner_remove_symbol +#define g_scanner_remove_symbol( scanner, symbol ) G_STMT_START { \ + g_scanner_scope_remove_symbol ((scanner), 0, (symbol)); \ +} G_STMT_END + + +g_scanner_foreach_symbol +#define g_scanner_foreach_symbol( scanner, func, data ) G_STMT_START { \ + g_scanner_scope_foreach_symbol ((scanner), 0, (func), (data)); \ +} G_STMT_END + + +GCompletion +struct GCompletion +{ + GList* items; + GCompletionFunc func; + + gchar* prefix; + GList* cache; +}; + + +g_completion_new +GCompletion * +GCompletionFunc func + + +g_completion_add_items +void +GCompletion* cmp,GList* items + + +g_completion_remove_items +void +GCompletion* cmp,GList* items + + +g_completion_clear_items +void +GCompletion* cmp + + +g_completion_complete +GList * +GCompletion* cmp,gchar* prefix,gchar** new_prefix + + +g_completion_free +void +GCompletion* cmp + + +GDateYear +typedef guint16 GDateYear; + + +GDateDay +typedef guint8 GDateDay; /* day of the month */ + + +GDate + + +GDateDMY +typedef enum +{ + G_DATE_DAY = 0, + G_DATE_MONTH = 1, + G_DATE_YEAR = 2 +} GDateDMY; + + +GDateWeekday +typedef enum +{ + G_DATE_BAD_WEEKDAY = 0, + G_DATE_MONDAY = 1, + G_DATE_TUESDAY = 2, + G_DATE_WEDNESDAY = 3, + G_DATE_THURSDAY = 4, + G_DATE_FRIDAY = 5, + G_DATE_SATURDAY = 6, + G_DATE_SUNDAY = 7 +} GDateWeekday; + + +GDateMonth +typedef enum +{ + G_DATE_BAD_MONTH = 0, + G_DATE_JANUARY = 1, + G_DATE_FEBRUARY = 2, + G_DATE_MARCH = 3, + G_DATE_APRIL = 4, + G_DATE_MAY = 5, + G_DATE_JUNE = 6, + G_DATE_JULY = 7, + G_DATE_AUGUST = 8, + G_DATE_SEPTEMBER = 9, + G_DATE_OCTOBER = 10, + G_DATE_NOVEMBER = 11, + G_DATE_DECEMBER = 12 +} GDateMonth; + + +G_DATE_BAD_JULIAN +#define G_DATE_BAD_JULIAN 0U + + +G_DATE_BAD_DAY +#define G_DATE_BAD_DAY 0U + + +G_DATE_BAD_YEAR +#define G_DATE_BAD_YEAR 0U + + +GDate +struct GDate +{ + guint julian_days : 32; /* julian days representation - we use a + * bitfield hoping that 64 bit platforms + * will pack this whole struct in one big + * int + */ + + guint julian : 1; /* julian is valid */ + guint dmy : 1; /* dmy is valid */ + + /* DMY representation */ + guint day : 6; + guint month : 4; + guint year : 16; +}; + + +g_date_new +GDate * +void + + +g_date_new_dmy +GDate * +GDateDay day,GDateMonth month,GDateYear year + + +g_date_new_julian +GDate * +guint32 julian_day + + +g_date_free +void +GDate *date + + +g_date_valid +gboolean +GDate *date + + +g_date_valid_day +gboolean +GDateDay day + + +g_date_valid_month +gboolean +GDateMonth month + + +g_date_valid_year +gboolean +GDateYear year + + +g_date_valid_weekday +gboolean +GDateWeekday weekday + + +g_date_valid_julian +gboolean +guint32 julian_date + + +g_date_valid_dmy +gboolean +GDateDay day,GDateMonth month,GDateYear year + + +g_date_weekday +GDateWeekday +GDate *date + + +g_date_month +GDateMonth +GDate *date + + +g_date_year +GDateYear +GDate *date + + +g_date_day +GDateDay +GDate *date + + +g_date_julian +guint32 +GDate *date + + +g_date_day_of_year +guint +GDate *date + + +g_date_monday_week_of_year +guint +GDate *date + + +g_date_sunday_week_of_year +guint +GDate *date + + +g_date_clear +void +GDate *date,guint n_dates + + +g_date_set_parse +void +GDate *date,const gchar *str + + +g_date_set_time +void +GDate *date,GTime time + + +g_date_set_month +void +GDate *date,GDateMonth month + + +g_date_set_day +void +GDate *date,GDateDay day + + +g_date_set_year +void +GDate *date,GDateYear year + + +g_date_set_dmy +void +GDate *date,GDateDay day,GDateMonth month,GDateYear y + + +g_date_set_julian +void +GDate *date,guint32 julian_date + + +g_date_is_first_of_month +gboolean +GDate *date + + +g_date_is_last_of_month +gboolean +GDate *date + + +g_date_add_days +void +GDate *date,guint n_days + + +g_date_subtract_days +void +GDate *date,guint n_days + + +g_date_add_months +void +GDate *date,guint n_months + + +g_date_subtract_months +void +GDate *date,guint n_months + + +g_date_add_years +void +GDate *date,guint n_years + + +g_date_subtract_years +void +GDate *date,guint n_years + + +g_date_is_leap_year +gboolean +GDateYear year + + +g_date_days_in_month +guint8 +GDateMonth month,GDateYear year + + +g_date_monday_weeks_in_year +guint8 +GDateYear year + + +g_date_sunday_weeks_in_year +guint8 +GDateYear year + + +g_date_compare +gint +GDate *lhs,GDate *rhs + + +g_date_to_struct_tm +void +GDate *date,struct tm *tm + + +g_date_strftime +gsize +gchar *s,gsize slen,const gchar *format,GDate *date + + +g_relation_new +GRelation * +gint fields + + +g_relation_destroy +void +GRelation *relation + + +g_relation_index +void +GRelation *relation,gint field,GHashFunc hash_func,GCompareFunc key_compare_func + + +g_relation_insert +void +GRelation *relation,... + + +g_relation_delete +gint +GRelation *relation,gconstpointer key,gint field + + +g_relation_select +GTuples * +GRelation *relation,gconstpointer key,gint field + + +g_relation_count +gint +GRelation *relation,gconstpointer key,gint field + + +g_relation_exists +gboolean +GRelation *relation,... + + +g_relation_print +void +GRelation *relation + + +g_tuples_destroy +void +GTuples *tuples + + +g_tuples_index +gpointer +GTuples *tuples,gint index,gint field + + +g_spaced_primes_closest +guint +guint num + + +GIOFuncs + + +GIOError +typedef enum +{ + G_IO_ERROR_NONE, + G_IO_ERROR_AGAIN, + G_IO_ERROR_INVAL, + G_IO_ERROR_UNKNOWN +} GIOError; + + +GSeekType +typedef enum +{ + G_SEEK_CUR, + G_SEEK_SET, + G_SEEK_END +} GSeekType; + + +GIOCondition +typedef enum +{ + G_IO_IN GLIB_SYSDEF_POLLIN, + G_IO_OUT GLIB_SYSDEF_POLLOUT, + G_IO_PRI GLIB_SYSDEF_POLLPRI, + G_IO_ERR GLIB_SYSDEF_POLLERR, + G_IO_HUP GLIB_SYSDEF_POLLHUP, + G_IO_NVAL GLIB_SYSDEF_POLLNVAL +} GIOCondition; + + +GIOChannel +struct GIOChannel +{ + guint channel_flags; + guint ref_count; + GIOFuncs *funcs; +}; + + +GIOFunc +gboolean +GIOChannel *source, + GIOCondition condition, + gpointer data + + +GIOFuncs +struct GIOFuncs +{ + GIOError (*io_read) (GIOChannel *channel, + gchar *buf, + guint count, + guint *bytes_read); + GIOError (*io_write) (GIOChannel *channel, + gchar *buf, + guint count, + guint *bytes_written); + GIOError (*io_seek) (GIOChannel *channel, + gint offset, + GSeekType type); + void (*io_close) (GIOChannel *channel); + guint (*io_add_watch) (GIOChannel *channel, + gint priority, + GIOCondition condition, + GIOFunc func, + gpointer user_data, + GDestroyNotify notify); + void (*io_free) (GIOChannel *channel); +}; + + +g_io_channel_init +void +GIOChannel *channel + + +g_io_channel_ref +void +GIOChannel *channel + + +g_io_channel_unref +void +GIOChannel *channel + + +g_io_channel_read +GIOError +GIOChannel *channel,gchar *buf,guint count,guint *bytes_read + + +g_io_channel_write +GIOError +GIOChannel *channel,gchar *buf,guint count,guint *bytes_written + + +g_io_channel_seek +GIOError +GIOChannel *channel,gint offset,GSeekType type + + +g_io_channel_close +void +GIOChannel *channel + + +g_io_add_watch_full +guint +GIOChannel *channel,gint priority,GIOCondition condition,GIOFunc func,gpointer user_data,GDestroyNotify notify + + +g_io_add_watch +guint +GIOChannel *channel,GIOCondition condition,GIOFunc func,gpointer user_data + + +GTimeVal + + +GSourceFuncs + + +GMainLoop + + +GTimeVal +struct GTimeVal +{ + glong tv_sec; + glong tv_usec; +}; + + +GSourceFuncs +struct GSourceFuncs +{ + gboolean (*prepare) (gpointer source_data, + GTimeVal *current_time, + gint *timeout, + gpointer user_data); + gboolean (*check) (gpointer source_data, + GTimeVal *current_time, + gpointer user_data); + gboolean (*dispatch) (gpointer source_data, + GTimeVal *current_time, + gpointer user_data); + GDestroyNotify destroy; +}; + + +G_PRIORITY_HIGH +#define G_PRIORITY_HIGH -100 + + +G_PRIORITY_DEFAULT +#define G_PRIORITY_DEFAULT 0 + + +G_PRIORITY_HIGH_IDLE +#define G_PRIORITY_HIGH_IDLE 100 + + +G_PRIORITY_DEFAULT_IDLE +#define G_PRIORITY_DEFAULT_IDLE 200 + + +G_PRIORITY_LOW +#define G_PRIORITY_LOW 300 + + +GSourceFunc +gboolean +gpointer data + + +g_source_add +guint +gint priority,gboolean can_recurse,GSourceFuncs *funcs,gpointer source_data,gpointer user_data,GDestroyNotify notify + + +g_source_remove +gboolean +guint tag + + +g_source_remove_by_user_data +gboolean +gpointer user_data + + +g_source_remove_by_source_data +gboolean +gpointer source_data + + +g_source_remove_by_funcs_user_data +gboolean +GSourceFuncs *funcs,gpointer user_data + + +g_get_current_time +void +GTimeVal *result + + +g_main_new +GMainLoop * +gboolean is_running + + +g_main_run +void +GMainLoop *loop + + +g_main_quit +void +GMainLoop *loop + + +g_main_destroy +void +GMainLoop *loop + + +g_main_is_running +gboolean +GMainLoop *loop + + +g_main_iteration +gboolean +gboolean may_block + + +g_main_pending +gboolean +void + + +g_timeout_add_full +guint +gint priority,guint interval,GSourceFunc function,gpointer data,GDestroyNotify notify + + +g_timeout_add +guint +guint interval,GSourceFunc function,gpointer data + + +g_idle_add +guint +GSourceFunc function,gpointer data + + +g_idle_add_full +guint +gint priority,GSourceFunc function,gpointer data,GDestroyNotify destroy + + +g_idle_remove_by_data +gboolean +gpointer data + + +GPollFD + + +GPollFunc +gint +GPollFD *ufds, + guint nfsd, + gint timeout + + +GPollFD +struct GPollFD +{ + gint fd; + gushort events; + gushort revents; +}; + + +g_main_add_poll +void +GPollFD *fd,gint priority + + +g_main_remove_poll +void +GPollFD *fd + + +g_main_set_poll_func +void +GPollFunc func + + +g_io_channel_unix_new +GIOChannel * +int fd + + +g_io_channel_unix_get_fd +gint +GIOChannel *channel + + +G_WIN32_MSG_HANDLE +#define G_WIN32_MSG_HANDLE 19981206 + + +g_main_poll_win32_msg_add +void +gint priority,GPollFD *fd,guint hwnd + + +g_io_channel_win32_new_messages +GIOChannel * +guint hwnd + + +g_io_channel_win32_new_pipe +GIOChannel * +int fd + + +g_io_channel_win32_new_pipe_with_wakeups +GIOChannel * +int fd,guint peer,int peer_fd + + +g_io_channel_win32_pipe_request_wakeups +void +GIOChannel *channel,guint peer,int peer_fd + + +g_io_channel_win32_pipe_readable +void +int fd,guint offset + + +g_io_channel_win32_get_fd +gint +GIOChannel *channel + + +g_io_channel_win32_new_stream_socket +GIOChannel * +int socket + + +MAXPATHLEN +# define MAXPATHLEN 1024 + + +pid_t +typedef int pid_t; + + +getcwd +# define getcwd _getcwd + + +getpid +# define getpid _getpid + + +access +# define access _access + + +open +# define open _open + + +read +# define read _read + + +write +# define write _write + + +lseek +# define lseek _lseek + + +close +# define close _close + + +pipe +# define pipe(phandles) _pipe (phandles, 4096, _O_BINARY) + + +popen +# define popen _popen + + +pclose +# define pclose _pclose + + +fdopen +# define fdopen _fdopen + + +ftruncate +# define ftruncate(fd, size) gwin_ftruncate (fd, size) + + +opendir +# define opendir gwin_opendir + + +readdir +# define readdir gwin_readdir + + +rewinddir +# define rewinddir gwin_rewinddir + + +closedir +# define closedir gwin_closedir + + +NAME_MAX +# define NAME_MAX 255 + + +gwin_ftruncate +int +gint f,guint size + + +gwin_opendir +DIR * +const gchar *dirname + + +gwin_rewinddir +void +DIR *dir + + +gwin_closedir +gint +DIR *dir + + +GMutex + + +GCond + + +GPrivate + + +GStaticPrivate + + +GThreadFunctions + + +GThreadFunctions +struct GThreadFunctions +{ + GMutex* (*mutex_new) (void); + void (*mutex_lock) (GMutex *mutex); + gboolean (*mutex_trylock) (GMutex *mutex); + void (*mutex_unlock) (GMutex *mutex); + void (*mutex_free) (GMutex *mutex); + GCond* (*cond_new) (void); + void (*cond_signal) (GCond *cond); + void (*cond_broadcast) (GCond *cond); + void (*cond_wait) (GCond *cond, + GMutex *mutex); + gboolean (*cond_timed_wait) (GCond *cond, + GMutex *mutex, + GTimeVal *end_time); + void (*cond_free) (GCond *cond); + GPrivate* (*private_new) (GDestroyNotify destructor); + gpointer (*private_get) (GPrivate *private_key); + void (*private_set) (GPrivate *private_key, + gpointer data); +}; + + +g_thread_init +void +GThreadFunctions *vtable + + +g_static_mutex_get_mutex_impl +GMutex * +GMutex **mutex + + +G_THREAD_UF +#define G_THREAD_UF(name, arglist) \ + (*g_thread_functions_for_glib_use . name) arglist + + +G_THREAD_CF +#define G_THREAD_CF(name, fail, arg) \ + (g_thread_supported () ? G_THREAD_UF (name, arg) : (fail)) + + +g_thread_supported +#define g_thread_supported() (g_threads_got_initialized) + + +g_mutex_new +#define g_mutex_new() G_THREAD_UF (mutex_new, ()) + + +g_mutex_lock +#define g_mutex_lock(mutex) G_THREAD_CF (mutex_lock, (void)0, (mutex)) + + +g_mutex_trylock +#define g_mutex_trylock(mutex) G_THREAD_CF (mutex_trylock, TRUE, (mutex)) + + +g_mutex_unlock +#define g_mutex_unlock(mutex) G_THREAD_CF (mutex_unlock, (void)0, (mutex)) + + +g_mutex_free +#define g_mutex_free(mutex) G_THREAD_CF (mutex_free, (void)0, (mutex)) + + +g_cond_new +#define g_cond_new() G_THREAD_UF (cond_new, ()) + + +g_cond_signal +#define g_cond_signal(cond) G_THREAD_CF (cond_signal, (void)0, (cond)) + + +g_cond_broadcast +#define g_cond_broadcast(cond) G_THREAD_CF (cond_broadcast, (void)0, (cond)) + + +g_cond_wait +#define g_cond_wait(cond, mutex) G_THREAD_CF (cond_wait, (void)0, (cond, \ + mutex)) + + +g_cond_free +#define g_cond_free(cond) G_THREAD_CF (cond_free, (void)0, (cond)) + + +g_cond_timed_wait +#define g_cond_timed_wait(cond, mutex, abs_time) G_THREAD_CF (cond_timed_wait, \ + TRUE, \ + (cond, mutex, \ + abs_time)) + + +g_private_new +#define g_private_new(destructor) G_THREAD_UF (private_new, (destructor)) + + +g_private_get +#define g_private_get(private_key) G_THREAD_CF (private_get, \ + ((gpointer)private_key), \ + (private_key)) + + +g_private_set +#define g_private_set(private_key, value) G_THREAD_CF (private_set, \ + (void) (private_key = \ + (GPrivate*) (value)), \ + (private_key, value)) + + +g_static_mutex_lock +#define g_static_mutex_lock(mutex) \ + g_mutex_lock (g_static_mutex_get_mutex (mutex)) + + +g_static_mutex_trylock +#define g_static_mutex_trylock(mutex) \ + g_mutex_trylock (g_static_mutex_get_mutex (mutex)) + + +g_static_mutex_unlock +#define g_static_mutex_unlock(mutex) \ + g_mutex_unlock (g_static_mutex_get_mutex (mutex)) + + +GStaticPrivate +struct GStaticPrivate +{ + guint index; +}; + + +G_STATIC_PRIVATE_INIT +#define G_STATIC_PRIVATE_INIT { 0 } + + +g_static_private_get +gpointer +GStaticPrivate *private_key + + +g_static_private_set +void +GStaticPrivate *private_key,gpointer data,GDestroyNotify notify + + +glib_dummy_decl +void +void + + +G_LOCK_NAME +#define G_LOCK_NAME(name) (g__ ## name ## _lock) + + +G_LOCK_DEFINE_STATIC +# define G_LOCK_DEFINE_STATIC(name) static G_LOCK_DEFINE (name) + + +G_LOCK_DEFINE +# define G_LOCK_DEFINE(name) \ + GStaticMutex G_LOCK_NAME (name) = G_STATIC_MUTEX_INIT + + +G_LOCK_EXTERN +# define G_LOCK_EXTERN(name) extern GStaticMutex G_LOCK_NAME (name) + + +G_LOCK +# define G_LOCK(name) G_STMT_START{ \ + g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, \ + "file %s: line %d (%s): locking: %s ", \ + __FILE__, __LINE__, G_GNUC_PRETTY_FUNCTION, \ + #name); \ + g_static_mutex_lock (&G_LOCK_NAME (name)); \ + }G_STMT_END + + +G_UNLOCK +# define G_UNLOCK(name) G_STMT_START{ \ + g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, \ + "file %s: line %d (%s): unlocking: %s ", \ + __FILE__, __LINE__, G_GNUC_PRETTY_FUNCTION, \ + #name); \ + g_static_mutex_unlock (&G_LOCK_NAME (name)); \ + }G_STMT_END + + +G_TRYLOCK +# define G_TRYLOCK(name) G_STMT_START{ \ + g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, \ + "file %s: line %d (%s): try locking: %s ", \ + __FILE__, __LINE__, G_GNUC_PRETTY_FUNCTION, \ + #name); \ + }G_STMT_END, g_static_mutex_trylock (&G_LOCK_NAME (name)) + + +G_LOCK +# define G_LOCK(name) g_static_mutex_lock (&G_LOCK_NAME (name)) + + +G_UNLOCK +# define G_UNLOCK(name) g_static_mutex_unlock (&G_LOCK_NAME (name)) + + +G_TRYLOCK +# define G_TRYLOCK(name) g_static_mutex_trylock (&G_LOCK_NAME (name)) + + +G_LOCK_DEFINE_STATIC +# define G_LOCK_DEFINE_STATIC(name) extern void glib_dummy_decl (void) + + +G_LOCK_DEFINE +# define G_LOCK_DEFINE(name) extern void glib_dummy_decl (void) + + +G_LOCK_EXTERN +# define G_LOCK_EXTERN(name) extern void glib_dummy_decl (void) + + +G_LOCK +# define G_LOCK(name) + + +G_UNLOCK +# define G_UNLOCK(name) + + +G_TRYLOCK +# define G_TRYLOCK(name) (FALSE) + + +g_log_domain_gmodule +extern const char *g_log_domain_gmodule; + + +G_MODULE_IMPORT +#define G_MODULE_IMPORT extern + + +G_MODULE_EXPORT +# define G_MODULE_EXPORT __declspec(dllexport) + + +G_MODULE_EXPORT +# define G_MODULE_EXPORT + + +GModuleFlags +typedef enum +{ + G_MODULE_BIND_LAZY = 1 << 0, + G_MODULE_BIND_MASK = 0x01 +} GModuleFlags; + + +GModule + + +GModuleCheckInit +const gchar * +GModule *module + + +GModuleUnload +void +GModule *module + + +g_module_supported +gboolean +void + + +g_module_open +GModule * +const gchar *file_name,GModuleFlags flags + + +g_module_close +gboolean +GModule *module + + +g_module_make_resident +void +GModule *module + + +g_module_error +gchar * +void + + +g_module_symbol +gboolean +GModule *module,const gchar *symbol_name,gpointer *symbol + + +g_module_name +gchar * +GModule *module + + +g_module_build_path +gchar * +const gchar *directory,const gchar *module_name + + +GLIB_HAVE_SYS_POLL_H +#define GLIB_HAVE_SYS_POLL_H + + +G_MINFLOAT +#define G_MINFLOAT FLT_MIN + + +G_MAXFLOAT +#define G_MAXFLOAT FLT_MAX + + +G_MINDOUBLE +#define G_MINDOUBLE DBL_MIN + + +G_MAXDOUBLE +#define G_MAXDOUBLE DBL_MAX + + +G_MINSHORT +#define G_MINSHORT SHRT_MIN + + +G_MAXSHORT +#define G_MAXSHORT SHRT_MAX + + +G_MININT +#define G_MININT INT_MIN + + +G_MAXINT +#define G_MAXINT INT_MAX + + +G_MINLONG +#define G_MINLONG LONG_MIN + + +G_MAXLONG +#define G_MAXLONG LONG_MAX + + +gint8 +typedef signed char gint8; + + +guint8 +typedef unsigned char guint8; + + +gint16 +typedef signed short gint16; + + +guint16 +typedef unsigned short guint16; + + +gint32 +typedef signed int gint32; + + +guint32 +typedef unsigned int guint32; + + +G_GNUC_EXTENSION +# define G_GNUC_EXTENSION __extension__ + + +G_GNUC_EXTENSION +# define G_GNUC_EXTENSION + + +G_HAVE_GINT64 +#define G_HAVE_GINT64 1 + + +gint64 +G_GNUC_EXTENSION typedef signed long long gint64; + + +guint64 +G_GNUC_EXTENSION typedef unsigned long long guint64; + + +G_GINT64_CONSTANT +#define G_GINT64_CONSTANT(val) (G_GNUC_EXTENSION (val##LL)) + + +GPOINTER_TO_INT +#define GPOINTER_TO_INT(p) ((gint) (p)) + + +GPOINTER_TO_UINT +#define GPOINTER_TO_UINT(p) ((guint) (p)) + + +GINT_TO_POINTER +#define GINT_TO_POINTER(i) ((gpointer) (i)) + + +GUINT_TO_POINTER +#define GUINT_TO_POINTER(u) ((gpointer) (u)) + + +g_ATEXIT +# define g_ATEXIT(proc) (!atexit (proc)) + + +g_ATEXIT +# define g_ATEXIT(proc) (atexit (proc)) + + +g_memmove +#define g_memmove(d,s,n) G_STMT_START { memmove ((d), (s), (n)); } G_STMT_END + + +GLIB_MAJOR_VERSION +#define GLIB_MAJOR_VERSION 1 + + +GLIB_MINOR_VERSION +#define GLIB_MINOR_VERSION 2 + + +GLIB_MICRO_VERSION +#define GLIB_MICRO_VERSION 3 + + +G_HAVE_INLINE +#define G_HAVE_INLINE 1 + + +G_HAVE_INLINE +#define G_HAVE_INLINE 1 + + +G_HAVE___INLINE +#define G_HAVE___INLINE 1 + + +G_HAVE___INLINE__ +#define G_HAVE___INLINE__ 1 + + +G_THREADS_ENABLED +#define G_THREADS_ENABLED + + +G_THREADS_IMPL_POSIX +#define G_THREADS_IMPL_POSIX + + +GStaticMutex + + +GStaticMutex +struct GStaticMutex +{ + struct _GMutex *runtime_mutex; + union { + char pad[24]; + double dummy_double; + void *dummy_pointer; + long dummy_long; + } aligned_pad_u; +}; + + +G_STATIC_MUTEX_INIT +#define G_STATIC_MUTEX_INIT { NULL, { { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0} } } + + +g_static_mutex_get_mutex +#define g_static_mutex_get_mutex(mutex) (g_thread_use_default_impl ? ((GMutex*) &((mutex)->aligned_pad_u)) : g_static_mutex_get_mutex_impl (&((mutex)->runtime_mutex))) + + +GINT16_TO_LE +#define GINT16_TO_LE(val) ((gint16) (val)) + + +GUINT16_TO_LE +#define GUINT16_TO_LE(val) ((guint16) (val)) + + +GINT16_TO_BE +#define GINT16_TO_BE(val) ((gint16) GUINT16_SWAP_LE_BE (val)) + + +GUINT16_TO_BE +#define GUINT16_TO_BE(val) (GUINT16_SWAP_LE_BE (val)) + + +GINT32_TO_LE +#define GINT32_TO_LE(val) ((gint32) (val)) + + +GUINT32_TO_LE +#define GUINT32_TO_LE(val) ((guint32) (val)) + + +GINT32_TO_BE +#define GINT32_TO_BE(val) ((gint32) GUINT32_SWAP_LE_BE (val)) + + +GUINT32_TO_BE +#define GUINT32_TO_BE(val) (GUINT32_SWAP_LE_BE (val)) + + +GINT64_TO_LE +#define GINT64_TO_LE(val) ((gint64) (val)) + + +GUINT64_TO_LE +#define GUINT64_TO_LE(val) ((guint64) (val)) + + +GINT64_TO_BE +#define GINT64_TO_BE(val) ((gint64) GUINT64_SWAP_LE_BE (val)) + + +GUINT64_TO_BE +#define GUINT64_TO_BE(val) (GUINT64_SWAP_LE_BE (val)) + + +GLONG_TO_LE +#define GLONG_TO_LE(val) ((glong) GINT32_TO_LE (val)) + + +GULONG_TO_LE +#define GULONG_TO_LE(val) ((gulong) GUINT32_TO_LE (val)) + + +GLONG_TO_BE +#define GLONG_TO_BE(val) ((glong) GINT32_TO_BE (val)) + + +GULONG_TO_BE +#define GULONG_TO_BE(val) ((gulong) GUINT32_TO_BE (val)) + + +GINT_TO_LE +#define GINT_TO_LE(val) ((gint) GINT32_TO_LE (val)) + + +GUINT_TO_LE +#define GUINT_TO_LE(val) ((guint) GUINT32_TO_LE (val)) + + +GINT_TO_BE +#define GINT_TO_BE(val) ((gint) GINT32_TO_BE (val)) + + +GUINT_TO_BE +#define GUINT_TO_BE(val) ((guint) GUINT32_TO_BE (val)) + + +G_BYTE_ORDER +#define G_BYTE_ORDER G_LITTLE_ENDIAN + + +GLIB_SYSDEF_POLLIN +#define GLIB_SYSDEF_POLLIN =1 + + +GLIB_SYSDEF_POLLOUT +#define GLIB_SYSDEF_POLLOUT =4 + + +GLIB_SYSDEF_POLLPRI +#define GLIB_SYSDEF_POLLPRI =2 + + +GLIB_SYSDEF_POLLERR +#define GLIB_SYSDEF_POLLERR =8 + + +GLIB_SYSDEF_POLLHUP +#define GLIB_SYSDEF_POLLHUP =16 + + +GLIB_SYSDEF_POLLNVAL +#define GLIB_SYSDEF_POLLNVAL =32 + + +G_HAVE_WCHAR_H +#define G_HAVE_WCHAR_H 1 + + +G_HAVE_WCTYPE_H +#define G_HAVE_WCTYPE_H 1 + diff --git a/docs/reference/glib/glib-docs.sgml b/docs/reference/glib/glib-docs.sgml new file mode 100644 index 00000000..cb0fc36d --- /dev/null +++ b/docs/reference/glib/glib-docs.sgml @@ -0,0 +1,99 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]> + + + GLib Reference Manual + + + + GLib Fundamentals + &glib-Basic-Types; + &glib-Limits-of-Basic-Types; + &glib-Standard-Macros; + &glib-Type-Conversion-Macros; + &glib-Byte-Order-Macros; + &glib-Miscellaneous-Macros; + + + + GLib Core Application Support + &glib-The-Main-Event-Loop; + &glib-Threads; + &glib-Dynamic-Loading-of-Modules; + &glib-Memory-Allocation; + &glib-IO-Channels; + &glib-Warnings-and-Assertions; + &glib-Message-Logging; + + + + GLib Utilities + &glib-String-Utility-Functions; + &glib-Date-and-Time-Functions; + &glib-Hook-Functions; + &glib-Miscellaneous-Utility-Functions; + &glib-Lexical-Scanner; + &glib-Automatic-String-Completion; + &glib-Timers; + &glib-Windows-Compatability-Functions; + + + + GLib Data Types + &glib-Memory-Chunks; + &glib-Doubly-Linked-Lists; + &glib-Singly-Linked-Lists; + &glib-Hash-Tables; + &glib-Strings; + &glib-String-Chunks; + &glib-Arrays; + &glib-Pointer-Arrays; + &glib-Byte-Arrays; + &glib-Balanced-Binary-Trees; + &glib-N-ary-Trees; + &glib-Quarks; + &glib-Keyed-Data-Lists; + &glib-Datasets; + &glib-Relations-and-Tuples; + &glib-Caches; + &glib-Memory-Allocators; + + \ No newline at end of file diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt new file mode 100644 index 00000000..f0ceaa8f --- /dev/null +++ b/docs/reference/glib/glib-sections.txt @@ -0,0 +1,1277 @@ + +glib.h + +
+Basic Types +types +gboolean +gpointer +gconstpointer +gchar +guchar + + +gint +guint +gshort +gushort +glong +gulong + + +gint8 +guint8 +gint16 +guint16 +gint32 +guint32 + + +G_HAVE_GINT64 +gint64 +guint64 +G_GINT64_CONSTANT + + +gfloat +gdouble + + +gsize +gssize + + +gldouble + +# I don't really know where to put these. +G_HAVE_WCHAR_H +G_HAVE_WCTYPE_H +GUTILS_C_VAR +
+ +
+Limits of Basic Types +limits +G_MININT +G_MAXINT + + +G_MINSHORT +G_MAXSHORT + + +G_MINLONG +G_MAXLONG + + +G_MINFLOAT +G_MAXFLOAT + + +G_MINDOUBLE +G_MAXDOUBLE +
+ +
+Standard Macros +macros +GLIB_MAJOR_VERSION +GLIB_MINOR_VERSION +GLIB_MICRO_VERSION + + +GLIB_CHECK_VERSION + + +G_DIR_SEPARATOR +G_DIR_SEPARATOR_S +G_SEARCHPATH_SEPARATOR +G_SEARCHPATH_SEPARATOR_S + + +TRUE +FALSE + + +NULL + + +MIN +MAX + + +ABS +CLAMP + + +G_STRUCT_MEMBER +G_STRUCT_MEMBER_P +G_STRUCT_OFFSET +
+ +
+Type Conversion Macros +type_conversion +GINT_TO_POINTER +GPOINTER_TO_INT + + +GUINT_TO_POINTER +GPOINTER_TO_UINT +
+ +
+Byte Order Macros +byte_order +G_BYTE_ORDER +G_LITTLE_ENDIAN +G_BIG_ENDIAN +G_PDP_ENDIAN + + +g_htonl +g_htons +g_ntohl +g_ntohs + + +GINT_FROM_BE +GINT_FROM_LE +GINT_TO_BE +GINT_TO_LE + + +GUINT_FROM_BE +GUINT_FROM_LE +GUINT_TO_BE +GUINT_TO_LE + + +GLONG_FROM_BE +GLONG_FROM_LE +GLONG_TO_BE +GLONG_TO_LE + + +GULONG_FROM_BE +GULONG_FROM_LE +GULONG_TO_BE +GULONG_TO_LE + + +GINT16_FROM_BE +GINT16_FROM_LE +GINT16_TO_BE +GINT16_TO_LE + + +GUINT16_FROM_BE +GUINT16_FROM_LE +GUINT16_TO_BE +GUINT16_TO_LE + + +GINT32_FROM_BE +GINT32_FROM_LE +GINT32_TO_BE +GINT32_TO_LE + + +GUINT32_FROM_BE +GUINT32_FROM_LE +GUINT32_TO_BE +GUINT32_TO_LE + + +GINT64_FROM_BE +GINT64_FROM_LE +GINT64_TO_BE +GINT64_TO_LE + + +GUINT64_FROM_BE +GUINT64_FROM_LE +GUINT64_TO_BE +GUINT64_TO_LE + + +GUINT16_SWAP_BE_PDP +GUINT16_SWAP_LE_BE +GUINT16_SWAP_LE_PDP + + +GUINT32_SWAP_BE_PDP +GUINT32_SWAP_LE_BE +GUINT32_SWAP_LE_PDP + + +GUINT64_SWAP_LE_BE + + +GUINT16_SWAP_LE_BE_CONSTANT +GUINT16_SWAP_LE_BE_X86 +GUINT32_SWAP_LE_BE_CONSTANT +GUINT32_SWAP_LE_BE_X86 +GUINT64_SWAP_LE_BE_CONSTANT +GUINT64_SWAP_LE_BE_X86 +
+ +
+Miscellaneous Macros +macros_misc +G_INLINE_FUNC + + +G_STMT_START +G_STMT_END + + +G_VA_COPY + + +G_GNUC_EXTENSION +G_GNUC_CONST +G_GNUC_NORETURN +G_GNUC_UNUSED +G_GNUC_PRINTF +G_GNUC_SCANF +G_GNUC_FORMAT +G_GNUC_FUNCTION +G_GNUC_PRETTY_FUNCTION + + +g_string + + +G_HAVE_INLINE +G_CAN_INLINE +inline +G_HAVE___INLINE +G_HAVE___INLINE__ +
+ +
+The Main Event Loop +main +GMainLoop +g_main_new +g_main_destroy +g_main_run +g_main_is_running +g_main_pending +g_main_iteration +g_main_quit + + +G_PRIORITY_HIGH +G_PRIORITY_DEFAULT +G_PRIORITY_HIGH_IDLE +G_PRIORITY_DEFAULT_IDLE +G_PRIORITY_LOW + + +g_timeout_add +g_timeout_add_full +GSourceFunc + + +g_idle_add +g_idle_add_full +g_idle_remove_by_data + + +g_main_add_poll +GPollFD +g_main_remove_poll + + +g_main_set_poll_func +GPollFunc + + +g_source_add +GSourceFuncs +g_source_remove +g_source_remove_by_funcs_user_data +g_source_remove_by_source_data +g_source_remove_by_user_data + + +GLIB_HAVE_SYS_POLL_H +GLIB_SYSDEF_POLLERR +GLIB_SYSDEF_POLLHUP +GLIB_SYSDEF_POLLIN +GLIB_SYSDEF_POLLNVAL +GLIB_SYSDEF_POLLOUT +GLIB_SYSDEF_POLLPRI +g_main_poll_win32_msg_add +G_WIN32_MSG_HANDLE +
+ +
+Threads +threads + +G_THREADS_ENABLED +G_THREADS_IMPL_POSIX +G_THREADS_IMPL_SOLARIS +G_THREADS_IMPL_NSPR +G_THREADS_IMPL_NONE + + +GThreadFunctions +g_thread_init +g_thread_supported + + +GMutex +g_mutex_new +g_mutex_lock +g_mutex_trylock +g_mutex_unlock +g_mutex_free + + +GStaticMutex +G_STATIC_MUTEX_INIT +g_static_mutex_lock +g_static_mutex_trylock +g_static_mutex_unlock +g_static_mutex_get_mutex + + +G_LOCK_DEFINE +G_LOCK_DEFINE_STATIC +G_LOCK_EXTERN +G_LOCK +G_TRYLOCK +G_UNLOCK + + +GCond +g_cond_new +g_cond_signal +g_cond_broadcast +g_cond_wait +g_cond_timed_wait +g_cond_free + + +GPrivate +g_private_new +g_private_get +g_private_set + + +GStaticPrivate +G_STATIC_PRIVATE_INIT +g_static_private_get +g_static_private_set + + +G_THREAD_CF +G_THREAD_UF +g_static_mutex_get_mutex_impl +G_LOCK_NAME +glib_dummy_decl +
+ +
+IO Channels +iochannels +GIOChannel + + +g_io_channel_unix_new +g_io_channel_unix_get_fd + + +g_io_channel_init + + +g_io_channel_read +GIOError +g_io_channel_write +g_io_channel_seek +GSeekType +g_io_channel_close + + +g_io_channel_ref +g_io_channel_unref + + +g_io_add_watch +g_io_add_watch_full +GIOCondition +GIOFunc + + +GIOFuncs + + +g_io_channel_win32_new_messages +g_io_channel_win32_new_pipe +g_io_channel_win32_new_pipe_with_wakeups +g_io_channel_win32_new_stream_socket + +g_io_channel_win32_get_fd +g_io_channel_win32_pipe_readable +g_io_channel_win32_pipe_request_wakeups +
+ +
+Memory Allocation +memory +g_new +g_new0 +g_renew + + +g_malloc +g_malloc0 +g_realloc + + +g_free + + +g_memmove +g_memdup + + +g_mem_profile +g_mem_check + +
+ +
+Warnings and Assertions +warnings +g_print +g_set_print_handler +GPrintFunc + + +g_printerr +g_set_printerr_handler + + +g_return_if_fail +g_return_val_if_fail + + +g_assert +g_assert_not_reached + + +g_on_error_query +g_on_error_stack_trace + + +G_BREAKPOINT +
+ +
+Message Logging +messages +G_LOG_DOMAIN +g_log_domain_glib +g_log_domain_gmodule +G_LOG_FATAL_MASK +G_LOG_LEVEL_USER_SHIFT +GLogFunc +GLogLevelFlags + + +g_log +g_logv +g_message +g_warning +g_error + + +g_log_set_handler +g_log_remove_handler +g_log_set_always_fatal +g_log_set_fatal_mask +g_log_default_handler + + +g_set_error_handler +GErrorFunc +g_set_warning_handler +GWarningFunc +g_set_message_handler +
+ +
+Timers +timers +GTimer +g_timer_new +g_timer_start +g_timer_stop +g_timer_elapsed +g_timer_reset +g_timer_destroy +
+ +
+String Utility Functions +string_utils +g_strdup +g_strndup +g_strnfill + + +g_strdup_printf +g_strdup_vprintf +g_snprintf +g_vsnprintf +g_printf_string_upper_bound + + +g_strup +g_strdown + + +g_strcasecmp +g_strncasecmp + + +g_strreverse +g_strtod + + +g_strchug +g_strchomp +g_strstrip + + +g_strdelimit +G_STR_DELIMITERS +g_strescape +g_strsplit +g_strfreev +g_strconcat +g_strjoin +g_strjoinv + + +g_strerror +g_strsignal +
+ +
+Date and Time Functions +date +GTimeVal +g_get_current_time + + +GTime +GDate +GDateDMY +GDateDay +GDateMonth +GDateWeekday +GDateYear +G_DATE_BAD_DAY +G_DATE_BAD_JULIAN +G_DATE_BAD_YEAR +g_date_add_days +g_date_add_months +g_date_add_years +g_date_clear +g_date_compare +g_date_day +g_date_day_of_year +g_date_days_in_month +g_date_free +g_date_is_first_of_month +g_date_is_last_of_month +g_date_is_leap_year +g_date_julian +g_date_monday_week_of_year +g_date_monday_weeks_in_year +g_date_month +g_date_new +g_date_new_dmy +g_date_new_julian +g_date_set_day +g_date_set_dmy +g_date_set_julian +g_date_set_month +g_date_set_parse +g_date_set_time +g_date_set_year +g_date_strftime +g_date_subtract_days +g_date_subtract_months +g_date_subtract_years +g_date_sunday_week_of_year +g_date_sunday_weeks_in_year +g_date_to_struct_tm +g_date_valid +g_date_valid_day +g_date_valid_dmy +g_date_valid_julian +g_date_valid_month +g_date_valid_weekday +g_date_valid_year +g_date_weekday +g_date_year +
+ +
+Hook Functions +hooks +GHookList +GHook +GHookFunc +GHookCheckFunc +GHookMarshaller +GHookCheckMarshaller +GHookFreeFunc +G_HOOK_DEFERRED_DESTROY + + +g_hook_list_init +g_hook_list_invoke +g_hook_list_invoke_check +g_hook_list_marshal +g_hook_list_marshal_check +g_hook_list_clear + + +g_hook_alloc +g_hook_append +g_hook_prepend +g_hook_insert_before +g_hook_insert_sorted +GHookCompareFunc +g_hook_compare_ids + + +g_hook_get +g_hook_find +g_hook_find_data +g_hook_find_func +GHookFindFunc +g_hook_find_func_data + + +g_hook_first_valid +g_hook_next_valid + +GHookFlagMask +G_HOOK_FLAG_USER_SHIFT + + +G_HOOK_IS_VALID +G_HOOK_ACTIVE +G_HOOK_IN_CALL +G_HOOK_IS_UNLINKED + + +g_hook_ref +g_hook_unref + +g_hook_free +g_hook_destroy +g_hook_destroy_link +
+ +
+Miscellaneous Utility Functions +misc_utils +g_get_prgname +g_set_prgname +g_getenv +g_get_user_name +g_get_real_name + + +g_get_home_dir +g_get_tmp_dir +g_get_current_dir +g_basename +g_dirname +g_path_is_absolute +g_path_skip_root + + +g_bit_nth_lsf +g_bit_nth_msf +g_bit_storage + + +g_spaced_primes_closest + + +g_atexit + + +g_parse_debug_string +GDebugKey + + +GVoidFunc +GFreeFunc + + +G_NATIVE_ATEXIT +g_ATEXIT +ATEXIT + +
+ +
+Lexical Scanner +scanner +GScanner +g_scanner_new +GScannerConfig + + +g_scanner_input_file +g_scanner_sync_file_offset +g_scanner_stat_mode +g_scanner_input_text +g_scanner_peek_next_token +g_scanner_get_next_token + + +g_scanner_cur_line +g_scanner_cur_position +g_scanner_cur_token +g_scanner_cur_value +g_scanner_eof + + +g_scanner_set_scope +g_scanner_scope_add_symbol +g_scanner_scope_foreach_symbol +g_scanner_scope_lookup_symbol +g_scanner_scope_remove_symbol + + +g_scanner_freeze_symbol_table +g_scanner_thaw_symbol_table +g_scanner_lookup_symbol + + +g_scanner_warn +g_scanner_error +g_scanner_unexp_token +GScannerMsgFunc + + +g_scanner_destroy + + +GTokenType +GTokenValue +GErrorType +G_CSET_a_2_z +G_CSET_A_2_Z +G_CSET_LATINC +G_CSET_LATINS + + +g_scanner_add_symbol +g_scanner_remove_symbol +g_scanner_foreach_symbol +
+ +
+Dynamic Loading of Modules +modules +GModule +g_module_supported +g_module_build_path +g_module_open +GModuleFlags +g_module_symbol +g_module_name +g_module_make_resident +g_module_close +g_module_error + +GModuleCheckInit +GModuleUnload +G_MODULE_EXPORT +G_MODULE_IMPORT +
+ +
+Automatic String Completion +completion +GCompletion +g_completion_new +GCompletionFunc +g_completion_add_items +g_completion_remove_items +g_completion_clear_items +g_completion_complete +g_completion_free +
+ +
+Windows Compatability Functions +windows +MAXPATHLEN +NAME_MAX +getcwd +getpid +pid_t +access +open +read +write +lseek +close +pipe +popen +pclose +fdopen +ftruncate +opendir +readdir +rewinddir +closedir + + +gwin_ftruncate +gwin_closedir +gwin_opendir +gwin_rewinddir + +
+ +# Data Structures + +
+Memory Chunks +memory_chunks +GMemChunk +G_ALLOC_AND_FREE +G_ALLOC_ONLY + + +g_mem_chunk_new +g_mem_chunk_alloc +g_mem_chunk_alloc0 +g_mem_chunk_free +g_mem_chunk_destroy + + +g_mem_chunk_create +g_chunk_new +g_chunk_new0 +g_chunk_free + + +g_mem_chunk_reset +g_mem_chunk_clean +g_blow_chunks + + +g_mem_chunk_info +g_mem_chunk_print + +
+ +
+Doubly-Linked Lists +linked_lists_double +GList + + +g_list_append +g_list_prepend +g_list_insert +g_list_insert_sorted +g_list_remove +g_list_remove_link +g_list_free + + +g_list_alloc +g_list_free_1 + + +g_list_length +g_list_copy +g_list_reverse +g_list_sort +g_list_concat +g_list_foreach +GFunc + + +g_list_first +g_list_last +g_list_previous +g_list_next +g_list_nth +g_list_nth_data + + +g_list_find +g_list_find_custom +g_list_position +g_list_index + + +g_list_pop_allocator +g_list_push_allocator +
+ +
+Singly-Linked Lists +linked_lists_single +GSList + + +g_slist_alloc +g_slist_append +g_slist_prepend +g_slist_insert +g_slist_insert_sorted +g_slist_remove +g_slist_remove_link +g_slist_free +g_slist_free_1 + + +g_slist_length +g_slist_copy +g_slist_reverse +g_slist_sort +g_slist_concat +g_slist_foreach + + +g_slist_last +g_slist_next +g_slist_nth +g_slist_nth_data + + +g_slist_find +g_slist_find_custom +g_slist_position +g_slist_index + + +g_slist_pop_allocator +g_slist_push_allocator +
+ +
+Hash Tables +hash_tables +GHashTable +g_hash_table_new +GHashFunc +GCompareFunc +g_hash_table_insert +g_hash_table_size +g_hash_table_lookup +g_hash_table_lookup_extended +g_hash_table_foreach +GHFunc +g_hash_table_remove +g_hash_table_foreach_remove +GHRFunc +g_hash_table_freeze +g_hash_table_thaw +g_hash_table_destroy + + +g_direct_equal +g_direct_hash +g_int_equal +g_int_hash +g_str_equal +g_str_hash + +
+ +
+Strings +strings +GString +g_string_new +g_string_sized_new +g_string_assign +g_string_sprintf +g_string_sprintfa +g_string_append +g_string_append_c +g_string_prepend +g_string_prepend_c +g_string_insert +g_string_insert_c +g_string_erase +g_string_truncate +g_string_free + + +g_string_up +g_string_down + +
+ +
+String Chunks +string_chunks +GStringChunk +g_string_chunk_new +g_string_chunk_insert +g_string_chunk_insert_const +g_string_chunk_free + +
+ +
+Arrays +arrays +GArray +g_array_new +g_array_append_val +g_array_append_vals +g_array_prepend_val +g_array_prepend_vals +g_array_insert_val +g_array_insert_vals +g_array_remove_index +g_array_remove_index_fast +g_array_index +g_array_set_size +g_array_free +
+ +
+Pointer Arrays +arrays_pointer +GPtrArray +g_ptr_array_new +g_ptr_array_add +g_ptr_array_remove +g_ptr_array_remove_index +g_ptr_array_remove_fast +g_ptr_array_remove_index_fast +g_ptr_array_set_size +g_ptr_array_index +g_ptr_array_free + +
+ +
+Byte Arrays +arrays_byte +GByteArray +g_byte_array_new +g_byte_array_append +g_byte_array_prepend +g_byte_array_remove_index +g_byte_array_remove_index_fast +g_byte_array_set_size +g_byte_array_free + +
+ +
+Balanced Binary Trees +trees-binary +GTree +g_tree_new +g_tree_insert +g_tree_nnodes +g_tree_height +g_tree_lookup +g_tree_search +GSearchFunc +g_tree_traverse +GTraverseFunc +GTraverseType +g_tree_remove +g_tree_destroy +
+ +
+N-ary Trees +trees-nary +GNode +g_node_new + + +g_node_insert +g_node_insert_before +g_node_append +g_node_prepend + + +g_node_insert_data +g_node_insert_data_before +g_node_append_data +g_node_prepend_data + + +g_node_reverse_children +g_node_traverse +GTraverseFlags +GNodeTraverseFunc +g_node_children_foreach +GNodeForeachFunc + + +g_node_get_root +g_node_find +g_node_find_child +g_node_child_index +g_node_child_position +g_node_first_child +g_node_last_child +g_node_nth_child +g_node_first_sibling +g_node_next_sibling +g_node_prev_sibling +g_node_last_sibling + + +G_NODE_IS_LEAF +G_NODE_IS_ROOT +g_node_depth +g_node_n_nodes +g_node_n_children +g_node_is_ancestor +g_node_max_height + + +g_node_unlink +g_node_destroy + + +g_node_pop_allocator +g_node_push_allocator +
+ + +
+Quarks +quarks +GQuark +g_quark_from_string +g_quark_from_static_string +g_quark_to_string +g_quark_try_string + +
+ +
+Keyed Data Lists +datalist +GData +g_datalist_init + + +g_datalist_id_set_data +g_datalist_id_set_data_full +g_datalist_id_get_data +g_datalist_id_remove_data +g_datalist_id_remove_no_notify + + +g_datalist_set_data +g_datalist_set_data_full +g_datalist_get_data +g_datalist_remove_data +g_datalist_remove_no_notify + + +g_datalist_foreach +g_datalist_clear +
+ + +
+Datasets +datasets +g_dataset_id_set_data +g_dataset_id_set_data_full +GDestroyNotify +g_dataset_id_get_data +g_dataset_id_remove_data +g_dataset_id_remove_no_notify + + +g_dataset_set_data +g_dataset_set_data_full +g_dataset_get_data +g_dataset_remove_data +g_dataset_remove_no_notify + + +g_dataset_foreach +GDataForeachFunc +g_dataset_destroy + +
+ +
+Relations and Tuples +relations +GRelation +g_relation_new +g_relation_index +g_relation_insert +g_relation_exists +g_relation_count +g_relation_select +g_relation_delete +g_relation_destroy + + +g_relation_print + + +GTuples +g_tuples_destroy +g_tuples_index +
+ +
+Caches +caches +GCache +g_cache_new +g_cache_insert +g_cache_remove +g_cache_destroy + + +g_cache_key_foreach +g_cache_value_foreach + + +GCacheDestroyFunc +GCacheDupFunc +GCacheNewFunc +
+ +
+Memory Allocators +allocators +GAllocator +g_allocator_new +g_allocator_free + + +G_ALLOCATOR_LIST +G_ALLOCATOR_NODE +G_ALLOCATOR_SLIST +
diff --git a/docs/reference/glib/glib/AUTHORS b/docs/reference/glib/glib/AUTHORS new file mode 100644 index 00000000..64f46b74 --- /dev/null +++ b/docs/reference/glib/glib/AUTHORS @@ -0,0 +1,7 @@ +Damon Chaplin and others. + +See: + + http://www.gtk.org/rdp/status.html + +for a complete list. diff --git a/docs/reference/glib/glib/COPYING b/docs/reference/glib/glib/COPYING new file mode 100644 index 00000000..df952d3c --- /dev/null +++ b/docs/reference/glib/glib/COPYING @@ -0,0 +1,30 @@ +This work may be reproduced and distributed in whole or in part, in +any medium, physical or electronic, so as long as this copyright +notice remains intact and unchanged on all copies. Commercial +redistribution is permitted and encouraged, but you may not +redistribute, in whole or in part, under terms more restrictive than +those under which you received it. If you redistribute a modified or +translated version of this work, you must also make the source code to +the modified or translated version available in electronic form +without charge. However, mere aggregation as part of a larger work +shall not count as a modification for this purpose. + +All code examples in this work are placed into the public domain, +and may be used, modified and redistributed without restriction. + +BECAUSE THIS WORK IS LICENSED FREE OF CHARGE, THERE IS NO +WARRANTY FOR THE WORK, TO THE EXTENT PERMITTED BY APPLICABLE LAW. +EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR +OTHER PARTIES PROVIDE THE WORK "AS IS" WITHOUT WARRANTY OF ANY +KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. SHOULD THE WORK PROVE DEFECTIVE, YOU ASSUME +THE COST OF ALL NECESSARY REPAIR OR CORRECTION. + +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY +AND/OR REDISTRIBUTE THE WORK AS PERMITTED ABOVE, BE LIABLE TO YOU +FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR +CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE +WORK, EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. diff --git a/docs/reference/glib/glib/ChangeLog b/docs/reference/glib/glib/ChangeLog new file mode 100644 index 00000000..081e1b25 --- /dev/null +++ b/docs/reference/glib/glib/ChangeLog @@ -0,0 +1,6 @@ +Wed Aug 18 23:11:28 1999 Owen Taylor + + * Import into CVS of glib-reference-1.1.3 + Filled in some basic contents for AUTHORS + README, and README.cvs + diff --git a/docs/reference/glib/glib/Makefile.am b/docs/reference/glib/glib/Makefile.am new file mode 100644 index 00000000..9ba90e06 --- /dev/null +++ b/docs/reference/glib/glib/Makefile.am @@ -0,0 +1,46 @@ +## Process this file with automake to produce Makefile.in + +# The name of the module. +DOC_MODULE=glib + +# The top-level SGML file. +DOC_MAIN_SGML_FILE=glib-docs.sgml + + +TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) + +scan: + gtkdoc-scan --module=$(DOC_MODULE) `glib-config --prefix`/include/glib.h `glib-config --prefix`/include/gmodule.h `glib-config --prefix`/lib/glib/include/glibconfig.h + +templates: scan + gtkdoc-mktmpl --module=$(DOC_MODULE) + +sgml: + gtkdoc-mkdb --module=$(DOC_MODULE) + +html: + if ! test -d html ; then mkdir html ; fi + -cd html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) + +clean-local: + rm -f *~ *.bak *.hierarchy *.signals *.args *-unused.txt + +maintainer-clean-local: clean + rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt + +install-data-local: + install -d -m 0755 $(TARGET_DIR) + install -m 0644 html/*.html $(TARGET_DIR) + install -m 0644 html/index.sgml $(TARGET_DIR) + gtkdoc-fixxref --module=$(DOC_MODULE) --html-dir=$(HTML_DIR) + +EXTRA_DIST = \ + $(DOC_MAIN_SGML_FILE) \ + $(DOC_MODULE)-sections.txt \ + glib-decl.txt + +dist-hook: + mkdir $(distdir)/tmpl + cp -p tmpl/*.sgml $(distdir)/tmpl + +.PHONY : html sgml templates scan diff --git a/docs/reference/glib/glib/NEWS b/docs/reference/glib/glib/NEWS new file mode 100644 index 00000000..e69de29b diff --git a/docs/reference/glib/glib/README b/docs/reference/glib/glib/README new file mode 100644 index 00000000..d0aa5981 --- /dev/null +++ b/docs/reference/glib/glib/README @@ -0,0 +1,14 @@ +This package contains the reference documentation +for GLib. For more information about Glib, +see: + + http://www.gtk.org + +For information about contributing to the +GLib/GTK+ reference documentation project, see: + + http://www.gtk.org/rdp/ + +The GLib reference documentation is freely redistributable, +see the file COPYING for details. + diff --git a/docs/reference/glib/glib/README.cvs-commits b/docs/reference/glib/glib/README.cvs-commits new file mode 100644 index 00000000..38e8735b --- /dev/null +++ b/docs/reference/glib/glib/README.cvs-commits @@ -0,0 +1,22 @@ +Before making any changes to this module, please +contact: + + Damon Chaplin + +This will ensure that duplicate work does not occur, +and also make sure we know who has written what +parts of the documentation. See + + http://www.gtk.org/rdp/ + +for more information. + +By contributing work to the Reference Documentation +Project, you agree that it will be covered under the +license terms described in the file COPYING +included in this directory. + + + + + diff --git a/docs/reference/glib/tmpl/allocators.sgml b/docs/reference/glib/tmpl/allocators.sgml new file mode 100644 index 00000000..6b12fd27 --- /dev/null +++ b/docs/reference/glib/tmpl/allocators.sgml @@ -0,0 +1,65 @@ + +Memory Allocators + + +allocates chunks of memory for #GList, #GSList and #GNode. + + + +The #GAllocator is used as an efficient way to allocate small pieces of +memory for use with the #GList, #GSList and #GNode data structures. +It uses a #GMemChunk so elements are allocated in groups, rather than +individually. + + +The #GList, #GSList and #GNode implementations create default #GAllocator +objects, which are probably sufficient for most purposes. These default +allocators use blocks of 128 elements. + + +To use your own #GAllocator, create it with g_allocator_new(). Then +use g_list_push_allocator(), g_slist_push_allocator() or +g_node_push_allocator() before any code which allocates new #GList, #GSList +or #GNode elements respectively. After allocating the new elements, you must +use g_list_pop_allocator(), g_slist_pop_allocator() or g_node_pop_allocator() +to restore the previous allocators. + + +Note that you cannot use the same allocator for #GList, #GSList and #GNode +elements. Each must use separate allocators. + + + + + + + + + +The #GAllocator struct contains private data. and should only be accessed +using the following functions. + + + + + +Creates a new #GAllocator. + + +@name: the name of the #GAllocator. This name is used to set the name of the +#GMemChunk used by the #GAllocator, and is only used for debugging. +@n_preallocs: the number of elements in each block of memory allocated. +Larger blocks mean less calls to g_malloc(), but some memory may be wasted. +(GLib uses 128 elements per block by default.) The value must be between 1 +and 65535. +@Returns: a new #GAllocator. + + + + +Frees all of the memory allocated by the #GAllocator. + + +@allocator: a #GAllocator. + + diff --git a/docs/reference/glib/tmpl/arrays.sgml b/docs/reference/glib/tmpl/arrays.sgml new file mode 100644 index 00000000..d05a1de8 --- /dev/null +++ b/docs/reference/glib/tmpl/arrays.sgml @@ -0,0 +1,224 @@ + +Arrays + + +arrays of arbitrary elements which grow automatically as elements are added. + + + +Arrays are similar to standard C arrays, except that they grow automatically +as elements are added. + + +Array elements can be of any size (though all elements of one array are the +same size), and the array can be automatically cleared to '0's and +zero-terminated. + + +To create a new array use g_array_new(). + + +To add elements to an array, use g_array_append_val(), g_array_append_vals(), +g_array_prepend_val(), and g_array_prepend_vals(). + + +To access an element of an array, use g_array_index(). + + +To set the size of an array, use g_array_set_size(). + + +To free an array, use g_array_free(). + + +Using a GArray to store gint values. + + GArray *garray; + gint i; + + /* We create a new array to store gint values. + We don't want it zero-terminated or cleared to 0's. */ + garray = g_array_new (FALSE, FALSE, sizeof (gint)); + for (i = 0; i < 10000; i++) + g_array_append_val (garray, i); + + for (i = 0; i < 10000; i++) + if (g_array_index (garray, gint, i) != i) + g_print ("ERROR: got %d instead of %d\n", + g_array_index (garray, gint, i), i); + + g_array_free (garray, TRUE); + + + + + + + + + +Contains the public fields of an Array. +The data field points to the element data. +It may change as elements are added to the array. +The len field contains the number of elements +in the array. + + +@data: +@len: + + + +Creates a new #GArray. + + +@zero_terminated: TRUE if the array should have an extra element at the end +which is set to '0'. +@clear: TRUE if #GArray elements should be automatically cleared to '0' +when they are allocated. +@element_size: the size of each element in bytes. +@Returns: the new #GArray. + + + + +Adds the value on to the end of the array. +The array will grow in size automatically if necessary. + + + +g_array_append_val() is a macro which uses a reference to the value +parameter @v. This means that you cannot use it with literal values +such as "27". You must use variables. + + + +@a: a #GArray. +@v: the value to append to the #GArray. +@Returns: the #GArray. + + + + +Adds @len elements onto the end of the array. + + +@array: a #GArray. +@data: a pointer to the elements to append to the end of the array. +@len: the number of elements to append. +@Returns: the #GArray. + + + + +Adds the value on to the start of the array. +The array will grow in size automatically if necessary. + + +This operation is slower than g_array_append_val() since the existing elements +in the array have to be moved to make space for the new element. + + + +g_array_prepend_val() is a macro which uses a reference to the value +parameter @v. This means that you cannot use it with literal values +such as "27". You must use variables. + + + +@a: a #GArray. +@v: the value to prepend to the #GArray. +@Returns: the #GArray. + + + + +Adds @len elements onto the start of the array. + + +This operation is slower than g_array_append_vals() since the existing elements +in the array have to be moved to make space for the new elements. + + +@array: a #GArray. +@data: a pointer to the elements to prepend to the start of the array. +@len: the number of elements to prepend. +@Returns: the #GArray. + + + + + + + +@a: +@i: +@v: + + + + + + + +@array: +@index: +@data: +@len: +@Returns: + + + + + + + +@array: +@index: +@Returns: + + + + + + + +@array: +@index: +@Returns: + + + + +Returns the element of a #GArray at the given index. +The return value is cast to the given type. +FIXME: need more info on how it works with structures. + + +@a: a #GArray. +@t: the type of the elements. +@i: the index of the element to return. +@Returns: the element of the #GArray at the index given by @i. + + + + +Sets the size of the array, expanding it if necessary. +If the array was created with clear set to TRUE, the new elements are set to 0. + + +@array: a #GArray. +@length: the new size of the #GArray. +@Returns: the #GArray. + + + + +Frees the memory allocated for the #GArray. +If free_segment is TRUE it frees the actual element data as well. + + +@array: a #GArray. +@free_segment: if TRUE the actual element data is freed as well. + + diff --git a/docs/reference/glib/tmpl/arrays_byte.sgml b/docs/reference/glib/tmpl/arrays_byte.sgml new file mode 100644 index 00000000..cba774b8 --- /dev/null +++ b/docs/reference/glib/tmpl/arrays_byte.sgml @@ -0,0 +1,135 @@ + +Byte Arrays + + +arrays of bytes, which grow automatically as elements are added. + + + +GByteArray is based on #GArray, to provide arrays of bytes which grow +automatically as elements are added. + + +To create a new #GByteArray use g_byte_array_new(). + + +To add elements to a #GByteArray, use g_byte_array_append(), and +g_byte_array_prepend(). + + +To set the size of a GByteArray, use g_byte_array_set_size(). + + +To free a GByteArray, use g_byte_array_free(). + + + +Using a GByteArray. + + GByteArray *gbarray; + gint i; + + gbarray = g_byte_array_new (); + for (i = 0; i < 10000; i++) + g_byte_array_append (gbarray, (guint8*) "abcd", 4); + + for (i = 0; i < 10000; i++) + { + g_assert (gbarray->data[4*i] == 'a'); + g_assert (gbarray->data[4*i+1] == 'b'); + g_assert (gbarray->data[4*i+2] == 'c'); + g_assert (gbarray->data[4*i+3] == 'd'); + } + + g_byte_array_free (gbarray, TRUE); + + + + + + + + + +The GByteArray struct allows access to the public fields of a GByteArray. +The data field points to the element data. +It may change as elements are added to the array. +The len field contains the number of elements +in the array. + + +@data: +@len: + + + +Creates a new #GByteArray. + + +@Returns: the new #GByteArray. + + + + +Adds the given bytes to the end of the #GByteArray. +The array will grow in size automatically if necessary. + + +@array: a #GByteArray. +@data: the byte data to be added. +@len: the number of bytes to add. +@Returns: the #GByteArray. + + + + +Adds the given data to the start of the #GByteArray. +The array will grow in size automatically if necessary. + + +@array: a #GByteArray. +@data: the byte data to be added. +@len: the number of bytes to add. +@Returns: the #GByteArray. + + + + + + + +@array: +@index: +@Returns: + + + + + + + +@array: +@index: +@Returns: + + + + +Sets the size of the #GByteArray, expanding it if necessary. + + +@array: a #GByteArray. +@length: the new size of the #GByteArray. +@Returns: the #GByteArray. + + + + +Frees the memory allocated by the #GByteArray. +If free_segment is TRUE it frees the actual byte data. + + +@array: a #GByteArray. +@free_segment: if TRUE the actual byte data is freed as well. + + diff --git a/docs/reference/glib/tmpl/arrays_pointer.sgml b/docs/reference/glib/tmpl/arrays_pointer.sgml new file mode 100644 index 00000000..59e1b44b --- /dev/null +++ b/docs/reference/glib/tmpl/arrays_pointer.sgml @@ -0,0 +1,182 @@ + +Pointer Arrays + + +arrays of pointers to any type of data, which grow automatically as new +elements are added. + + + +Pointer Arrays are similar to Arrays but are used only for storing pointers. + + + +If you remove elements from the array, elements at the end of the array +are moved into the space previously occupied by the removed element. +This means that you should not rely on the index of particular elements +remaining the same. You should also be careful when deleting elements while +iterating over the array. + + + +To create a pointer array, use g_ptr_array_new(). + + +To add elements to a pointer array, use g_ptr_array_add(). + + +To remove elements from a pointer array, use g_ptr_array_remove(), and +g_ptr_array_remove_index(). + + +To access an element of a pointer array, use g_ptr_array_index(). + + +To set the size of a pointer array, use g_ptr_array_set_size(). + + +To free a pointer array, use g_ptr_array_free(). + + +Using a GPtrArray. + + GPtrArray *gparray; + gchar *string1 = "one", *string2 = "two", *string3 = "three"; + + gparray = g_ptr_array_new (); + g_ptr_array_add (gparray, (gpointer) string1); + g_ptr_array_add (gparray, (gpointer) string2); + g_ptr_array_add (gparray, (gpointer) string3); + + if (g_ptr_array_index (gparray, 0) != (gpointer) string1) + g_print ("ERROR: got %p instead of %p\n", + g_ptr_array_index (gparray, 0), string1); + + g_ptr_array_free (gparray, TRUE); + + + + + + + + + +Contains the public fields of a pointer array. +The pdata field points to the array of pointers, +which may as when the array grows. +The len field is the number of pointers in the +array. + + +@pdata: +@len: + + + +Creates a new #GPtrArray. + + +@Returns: the new #GPtrArray. + + + + +Adds a pointer to the end of the pointer array. +The array will grow in size automatically if necessary. + + +@array: a #GPtrArray. +@data: the pointer to add. + + + + +Removes the first occurrence of given pointer from the pointer array. +It returns TRUE if the pointer was removed, or FALSE if the pointer +was not found. + + + +If you remove elements from the array, elements at the end of the array +are moved into the space previously occupied by the removed element. +This means that you should not rely on the index of particular elements +remaining the same. You should also be careful when deleting elements while +iterating over the array. + + + +@array: a #GPtrArray. +@data: the pointer to remove. +@Returns: TRUE if the pointer is removed. FALSE if the pointer is not found +in the array. + + + + +Removes the pointer at the given index from the pointer array. + + + +If you remove elements from the array, elements at the end of the array +are moved into the space previously occupied by the removed element. +This means that you should not rely on the index of particular elements +remaining the same. You should also be careful when deleting elements while +iterating over the array. + + + +@array: a #GPtrArray. +@index: the index of the pointer to remove. +@Returns: the pointer which was removed. + + + + + + + +@array: +@data: +@Returns: + + + + + + + +@array: +@index: +@Returns: + + + + +Sets the size of the array, expanding it if necessary. +New elements are set to NULL. + + +@array: a #GPtrArray. +@length: the new length of the pointer array. + + + + +Returns the pointer at the given index of the pointer array. + + +@array: a #GPtrArray. +@index: the index of the pointer to return. +@Returns: the pointer at the given index. + + + + +Frees all of the memory allocated for the pointer array. + + +@array: a #GPtrArray. +@free_seg: if TRUE the actual element data is freed as well. + + diff --git a/docs/reference/glib/tmpl/byte_order.sgml b/docs/reference/glib/tmpl/byte_order.sgml new file mode 100644 index 00000000..01e931c9 --- /dev/null +++ b/docs/reference/glib/tmpl/byte_order.sgml @@ -0,0 +1,545 @@ + +Byte Order Macros + + +a portable way to convert between different byte orders. + + + +These macros provide a portable way to determine the host byte order +and to convert values between different byte orders. + + +The byte order is the order in which bytes are stored to create larger +data types such as the #gint and #glong values. +The host byte order is the byte order used on the current machine. + + +Some processors store the most significant bytes (i.e. the bytes that +hold the largest part of the value) first. These are known as big-endian +processors. + + +Other processors (notably the x86 family) store the most significant byte +last. These are known as little-endian processors. + + +Finally, to complicate matters, some other processors store the bytes in +a rather curious order known as PDP-endian. For a 4-byte word, the 3rd +most significant byte is stored first, then the 4th, then the 1st and finally +the 2nd. + + +Obviously there is a problem when these different processors communicate +with each other, for example over networks or by using binary file formats. +This is where these macros come in. +They are typically used to convert values into a byte order +which has been agreed on for use when communicating between different +processors. The Internet uses what is known as 'network byte order' +as the standard byte order (which is in fact the big-endian byte order). + + + + + + + + + +The host byte order. +This can be either #G_LITTLE_ENDIAN or #G_BIG_ENDIAN (support for +#G_PDP_ENDIAN may be added in future.) + + + + + + +Specifies one of the possible types of byte order. +See #G_BYTE_ORDER. + + + + + + +Specifies one of the possible types of byte order. +See #G_BYTE_ORDER. + + + + + + +Specifies one of the possible types of byte order (currently unused). +See #G_BYTE_ORDER. + + + + + + +Converts a 32-bit integer value from host to network byte order. + + +@val: a 32-bit integer value in host byte order. +@Returns: @val converted to network byte order. + + + + +Converts a 16-bit integer value from host to network byte order. + + +@val: a 16-bit integer value in host byte order. +@Returns: @val converted to network byte order. + + + + +Converts a 32-bit integer value from network to host byte order. + + +@val: a 32-bit integer value in network byte order. +@Returns: @val converted to host byte order. + + + + +Converts a 16-bit integer value from network to host byte order. + + +@val: a 16-bit integer value in network byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #gint value from big-endian to host byte order. + + +@val: a #gint value in big-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #gint value from little-endian to host byte order. + + +@val: a #gint value in little-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #gint value from host byte order to big-endian. + + +@val: a #gint value in host byte order. +@Returns: @val converted to big-endian byte order. + + + + +Converts a #gint value from host byte order to little-endian. + + +@val: a #gint value in host byte order. +@Returns: @val converted to little-endian byte order. + + + + +Converts a #guint value from big-endian to host byte order. + + +@val: a #guint value in big-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #guint value from little-endian to host byte order. + + +@val: a #guint value in little-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #guint value from host byte order to big-endian. + + +@val: a #guint value in host byte order. +@Returns: @val converted to big-endian byte order. + + + + +Converts a #guint value from host byte order to little-endian. + + +@val: a #guint value in host byte order. +@Returns: @val converted to little-endian byte order. + + + + +Converts a #glong value from big-endian to the host byte order. + + +@val: a #glong value in big-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #glong value from little-endian to host byte order. + + +@val: a #glong value in little-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #glong value from host byte order to big-endian. + + +@val: a #glong value in host byte order. +@Returns: @val converted to big-endian byte order. + + + + +Converts a #glong value from host byte order to little-endian. + + +@val: a #glong value in host byte order. +@Returns: @val converted to little-endian. + + + + +Converts a #gulong value from big-endian to host byte order. + + +@val: a #gulong value in big-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #gulong value from little-endian to host byte order. + + +@val: a #gulong value in little-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #gulong value from host byte order to big-endian. + + +@val: a #gulong value in host byte order. +@Returns: @val converted to big-endian. + + + + +Converts a #gulong value from host byte order to little-endian. + + +@val: a #gulong value in host byte order. +@Returns: @val converted to little-endian. + + + + +Converts a #gint16 value from big-endian to host byte order. + + +@val: a #gint16 value in big-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #gint16 value from little-endian to host byte order. + + +@val: a #gint16 value in little-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #gint16 value from host byte order to big-endian. + + +@val: a #gint16 value in host byte order. +@Returns: @val converted to big-endian. + + + + +Converts a #gint16 value from host byte order to little-endian. + + +@val: a #gint16 value in host byte order. +@Returns: @val converted to little-endian. + + + + +Converts a #guint16 value from big-endian to host byte order. + + +@val: a #guint16 value in big-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #guint16 value from little-endian to host byte order. + + +@val: a #guint16 value in little-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #guint16 value from host byte order to big-endian. + + +@val: a #guint16 value in host byte order. +@Returns: @val converted to big-endian. + + + + +Converts a #guint16 value from host byte order to little-endian. + + +@val: a #guint16 value in host byte order. +@Returns: @val converted to little-endian. + + + + +Converts a #gint32 value from big-endian to host byte order. + + +@val: a #gint32 value in big-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #gint32 value from little-endian to host byte order. + + +@val: a #gint32 value in little-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #gint32 value from host byte order to big-endian. + + +@val: a #gint32 value in host byte order. +@Returns: @val converted to big-endian. + + + + +Converts a #gint32 value from host byte order to little-endian. + + +@val: a #gint32 value in host byte order. +@Returns: @val converted to little-endian. + + + + +Converts a #guint32 value from big-endian to host byte order. + + +@val: a #guint32 value in big-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #guint32 value from little-endian to host byte order. + + +@val: a #guint32 value in little-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #guint32 value from host byte order to big-endian. + + +@val: a #guint32 value in host byte order. +@Returns: @val converted to big-endian. + + + + +Converts a #guint32 value from host byte order to little-endian. + + +@val: a #guint32 value in host byte order. +@Returns: @val converted to little-endian. + + + + +Converts a #gint64 value from big-endian to host byte order. + + +@val: a #gint64 value in big-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #gint64 value from little-endian to host byte order. + + +@val: a #gint64 value in little-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #gint64 value from host byte order to big-endian. + + +@val: a #gint64 value in host byte order. +@Returns: @val converted to big-endian. + + + + +Converts a #gint64 value from host byte order to little-endian. + + +@val: a #gint64 value in host byte order. +@Returns: @val converted to little-endian. + + + + +Converts a #guint64 value from big-endian to host byte order. + + +@val: a #guint64 value in big-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #guint64 value from little-endian to host byte order. + + +@val: a #guint64 value in little-endian byte order. +@Returns: @val converted to host byte order. + + + + +Converts a #guint64 value from host byte order to big-endian. + + +@val: a #guint64 value in host byte order. +@Returns: @val converted to big-endian. + + + + +Converts a #guint64 value from host byte order to little-endian. + + +@val: a #guint64 value in host byte order. +@Returns: @val converted to little-endian. + + + + +Converts a #guint16 value between big-endian and pdp-endian byte order. +The conversion is symmetric so it can be used both ways. + + +@val: a #guint16 value in big-endian or pdp-endian byte order. +@Returns: @val converted to the opposite byte order. + + + + +Converts a #guint16 value between little-endian and big-endian byte order. +The conversion is symmetric so it can be used both ways. + + +@val: a #guint16 value in little-endian or big-endian byte order. +@Returns: @val converted to the opposite byte order. + + + + +Converts a #guint16 value between little-endian and pdp-endian byte order. +The conversion is symmetric so it can be used both ways. + + +@val: a #guint16 value in little-endian or pdp-endian byte order. +@Returns: @val converted to the opposite byte order. + + + + +Converts a #guint32 value between big-endian and pdp-endian byte order. +The conversion is symmetric so it can be used both ways. + + +@val: a #guint32 value in big-endian or pdp-endian byte order. +@Returns: @val converted to the opposite byte order. + + + + +Converts a #guint32 value between little-endian and big-endian byte order. +The conversion is symmetric so it can be used both ways. + + +@val: a #guint32 value in little-endian or big-endian byte order. +@Returns: @val converted to the opposite byte order. + + + + +Converts a #guint32 value between little-endian and pdp-endian byte order. +The conversion is symmetric so it can be used both ways. + + +@val: a #guint32 value in little-endian or pdp-endian byte order. +@Returns: @val converted to the opposite byte order. + + + + +Converts a #guint64 value between little-endian and big-endian byte order. +The conversion is symmetric so it can be used both ways. + + +@val: a #guint64 value in little-endian or big-endian byte order. +@Returns: @val converted to the opposite byte order. + + diff --git a/docs/reference/glib/tmpl/caches.sgml b/docs/reference/glib/tmpl/caches.sgml new file mode 100644 index 00000000..aad81b57 --- /dev/null +++ b/docs/reference/glib/tmpl/caches.sgml @@ -0,0 +1,152 @@ + +Caches + + +allows sharing of complex data structures to save resources. + + + +A #GCache allows sharing of complex data structures, in order to save +system resources. + + +GTK uses a #GCache for both GtkStyles and GdkGCs. These consume a lot of +resouces, 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. + + +#GCache uses keys and values. +A #GCache key describes the properties of a particular resource. +A #GCache value is the actual resource. + + + + + + + + + +The #GCache struct is an opaque data structure containing information about +a #GCache. It should only be accesssed via the following functions. + + + + + +Creates a new GCache. + + +@value_new_func: a function to create a new object given a key. +This is called by g_cache_insert() if an object with the given key +does not already exist. +@value_destroy_func: a function to destroy an object. It is +called by g_cache_remove() when the object is no longer needed (i.e. its +reference count drops to 0). +@key_dup_func: a function to copy a key. It is called by +g_cache_insert() if the key does not already exist in the GCache. +@key_destroy_func: a function to destroy a key. It is +called by g_cache_remove() when the object is no longer needed (i.e. its +reference count drops to 0). +@hash_key_func: a function to create a hash value from a key. +@hash_value_func: a function to create a hash value from a value. +@key_compare_func: a function to compare two keys. It should return TRUE if +the two keys are equivalent. +@Returns: a new #GCache. + + + + +Gets the value corresponding to the given key, creating it if necessary. +It first checks if the value already exists in the #GCache, by using +the @key_compare_func function passed to g_cache_new(). +If it does already exist it is returned, and its reference count is increased +by one. +If the value does not currently exist, if is created by calling the +@value_new_func. The key is duplicated by calling +@key_dup_func and the duplicated key and value are inserted +into the #GCache. + + +@cache: a #GCache. +@key: a key describing a #GCache object. +@Returns: a pointer to a #GCache value. + + + + +Decreases the reference count of the given value. +If it drops to 0 then the value and its corresponding key are destroyed, +using the @value_destroy_func and @key_destroy_func passed to g_cache_new(). + + +@cache: a #GCache. +@value: the value to remove. + + + + +Frees the memory allocated for the GCache. + + +Note that it does not destroy the keys and values which were contained in the +GCache. + + +@cache: + + + + +Calls the given function for each of the keys in the #GCache. + + +@cache: a #GCache. +@func: the function to call with each #GCache key. +@user_data: user data to pass to the function. + + + + +Calls the given function for each of the values in the #GCache. + + +@cache: a #GCache. +@func: the function to call with each #GCache value. +@user_data: user data to pass to the function. + + + + +Specifies the type of the @value_destroy_func and @key_destroy_func functions +passed to g_cache_new(). +The functions are passed a pointer to the #GCache key or #GCache value and +should free any memory and other resources associated with it. + + +@value: the #GCache value to destroy. + + + + +Specifies the type of the @key_dup_func function passed to g_cache_new(). +The function is passed a key (NOT a value as the prototype implies) and +should return a duplicate of the key. + + +@value: the #GCache key to destroy (NOT a #GCache value as it seems). +@Returns: a copy of the #GCache key. + + + + +Specifies the type of the @value_new_func function passed to g_cache_new(). +It is passed a #GCache key and should create the value corresponding to the +key. + + +@key: a #GCache key. +@Returns: a new #GCache value corresponding to the key. + + diff --git a/docs/reference/glib/tmpl/completion.sgml b/docs/reference/glib/tmpl/completion.sgml new file mode 100644 index 00000000..6bb76816 --- /dev/null +++ b/docs/reference/glib/tmpl/completion.sgml @@ -0,0 +1,121 @@ + +Automatic String Completion + + +support for automatic completion using a group of target strings. + + + +#GCompletion provides support for automatic completion of a string using +any group of target strings. It is typically used for file name completion +as is common in many Unix shells. + + +A #GCompletion is created using g_completion_new(). +Target items are added and removed with +g_completion_add_items(), g_completion_remove_items() and +g_completion_clear_items(). +A completion attempt is requested with g_completion_complete(). +When no longer needed, the #GCompletion is freed with g_completion_free(). + + +Items in the completion can be simple strings (e.g. file names), +or pointers to arbitrary data structures. If data structures are used +you must provide a #GCompletionFunc in g_completion_new(), +which retrieves the item's string from the data structure. + + + + + + + + + +The data structure used for automatic completion. +items is the list of target items (strings +or data structures). +func is the function called to get the string +associated with a target item. It is NULL if the target items are strings. +prefix is the last prefix passed to +g_completion_complete(). +cache is the list of items which begin with +prefix. + + +@items: +@func: +@prefix: +@cache: + + + +Creates a new #GCompletion. + + +@func: the function to be called to return the string representing an item +in the #GCompletion, or NULL if strings are going to be used as the +#GCompletion items. +@Returns: the new #GCompletion. + + + + +Specifies the type of the function passed to g_completion_new(). +It should return the string corresponding to the given target item. +This is used when you use data structures as #GCompletion items. + + +@Param1: the completion item. +@Returns: the string corresponding to the item. + + + + +Adds items to the #GCompletion. + + +@cmp: the #GCompletion. +@items: the list of items to add. + + + + +Removes items from a #GCompletion. + + +@cmp: the #GCompletion. +@items: the items to remove. + + + + +Removes all items from the #GCompletion. + + +@cmp: the #GCompletion. + + + + +Attempts to complete the string @prefix using the #GCompletion target items. + + +@cmp: the #GCompletion. +@prefix: the prefix string, typically typed by the user, which is compared +with each of the items. +@new_prefix: if non-NULL, returns the longest prefix which is common to all +items that matched @prefix, or NULL if no items matched @prefix. +This string should be freed when no longer needed. +@Returns: the list of items whose strings begin with @prefix. This should +not be changed. + + + + +Frees all memory used by the #GCompletion. + + +@cmp: the #GCompletion. + + diff --git a/docs/reference/glib/tmpl/datalist.sgml b/docs/reference/glib/tmpl/datalist.sgml new file mode 100644 index 00000000..99ac4ac2 --- /dev/null +++ b/docs/reference/glib/tmpl/datalist.sgml @@ -0,0 +1,197 @@ + +Keyed Data Lists + + +lists of data elements which are accessible by a string or #GQuark identifier. + + + +Keyed data lists provide lists of arbitrary data elements which can be accessed +either with a string or with a #GQuark corresponding to the string. + + +The GQuark methods are quicker, since the strings have to be converted to +GQuarks anyway. + + +Data lists are used in GTK for associating arbitrary data with +GtkObjects, using gtk_object_set_data() and related functions. + + + +To create a datalist, use g_datalist_init(). + + +To add data elements to a datalist use g_datalist_id_set_data(), +g_datalist_id_set_data_full(), g_datalist_set_data() +and g_datalist_set_data_full(). + + +To get data elements from a datalist use g_datalist_id_get_data() and +g_datalist_get_data(). + + +To iterate over all data elements in a datalist use g_datalist_foreach(). + + +To remove data elements from a datalist use g_datalist_id_remove_data() and +g_datalist_remove_data(). + + +To remove all data elements from a datalist, use g_datalist_clear(). + + + + + + + + + +The #GData struct is an opaque data structure to represent a +Keyed Data List. +It should only be accessed via the following functions. + + + + + +Resets the datalist to NULL. +It does not free any memory or call any destroy functions. + + +@datalist: a pointer to a pointer to a datalist. + + + + +Sets the data corresponding to the given #GQuark id. +Any previous data with the same key is removed, and its +destroy function is called. + + +@dl: a datalist. +@q: the #GQuark to identify the data element. +@d: the data element. + + + + +Sets the data corresponding to the given #GQuark id, and the function to +be called when the element is removed from the datalist. +Any previous data with the same key is removed, and its +destroy function is called. + + +@datalist: a datalist. +@key_id: the #GQuark to identify the data element. +@data: the data element. +@destroy_func: the function to call when the data element is removed. This +function will be called with the data element and can be used to free any +memory allocated for it. + + + + +Gets a data element. + + +@datalist: a datalist. +@key_id: the #GQuark identifying a data element. +@Returns: the data element, or NULL if it is not found. + + + + +Removes an element, using its #GQuark identifier. + + +@dl: a datalist. +@q: the #GQuark identifying the data element. + + + + + + + +@datalist: +@key_id: + + + + +Sets the data element corresponding to the given string identifier. + + +@dl: a datalist. +@k: the string to identify the data element. +@d: the data element. + + + + +Sets the data element corresponding to the given string identifier, and the +function to be called when the data element is removed. + + +@dl: a datalist. +@k: the string to identify the data element. +@d: the data element. +@f: the function to call when the data element is removed. This +function will be called with the data element and can be used to free any +memory allocated for it. + + + + +Gets a data element, using its string identifer. +This is slower than g_datalist_id_get_data() because the string is first +converted to a #GQuark. + + +@dl: a datalist. +@k: the string identifying a data element. +@Returns: the data element, or NULL if it is not found. + + + + +Removes an element using its string identifier. +The data element's destroy function is called if it has been set. + + +@dl: a datalist. +@k: the string identifying the data element. + + + + + + + +@dl: +@k: + + + + +Calls the given function for each data element of the datalist. +The function is called with each data element's #GQuark id and data, +together with the given @user_data parameter. + + +@datalist: a datalist. +@func: the function to call for each data element. +@user_data: user data to pass to the function. + + + + +Frees all the data elements of the datalist. +The data elements' destroy functions are called if they have been set. + + +@datalist: a datalist. + + diff --git a/docs/reference/glib/tmpl/datasets.sgml b/docs/reference/glib/tmpl/datasets.sgml new file mode 100644 index 00000000..afd64be0 --- /dev/null +++ b/docs/reference/glib/tmpl/datasets.sgml @@ -0,0 +1,204 @@ + +Datasets + + +associate groups of data elements with particular memory locations. + + + +Datasets associate groups of data elements with particular memory locations. +These are useful if you need to associate data with a structure returned +from an external library. Since you cannot modify the structure, you use +its location in memory as the key into a dataset, where you can associate +any number of data elements with it. + + +There are two forms of most of the dataset functions. +The first form uses strings to identify the data elements associated with +a location. The second form uses #GQuark identifiers, which are created +with a call to g_quark_from_string() or g_quark_from_static_string(). +The second form is quicker, since it does not require looking up the string +in the hash table of #GQuark identifiers. + + +There is no function to create a dataset. It is automatically created as +soon as you add elements to it. + +To add data elements to a dataset use g_dataset_id_set_data(), +g_dataset_id_set_data_full(), g_dataset_set_data() +and g_dataset_set_data_full(). + + +To get data elements from a dataset use g_dataset_id_get_data() and +g_dataset_get_data(). + + +To iterate over all data elements in a dataset use g_dataset_foreach(). + + +To remove data elements from a dataset use g_dataset_id_remove_data() and +g_dataset_remove_data(). + + +To destroy a dataset, use g_dataset_destroy(). + + + + + + + + + +Sets the data element associated with the given #GQuark id. +Any previous data with the same key is removed, and its destroy function +is called. + + +@l: the location identifying the dataset. +@k: the #GQuark id to identify the data element. +@d: the data element. + + + + +Sets the data element associated with the given #GQuark id, and also the +function to call when the data element is destroyed. +Any previous data with the same key is removed, and its +destroy function is called. + + +@dataset_location: the location identifying the dataset. +@key_id: the #GQuark id to identify the data element. +@data: the data element. +@destroy_func: the function to call when the data element is removed. This +function will be called with the data element and can be used to free any +memory allocated for it. + + + + +Specifies the type of function which is called when a data element is +destroyed. It is passed the pointer to the data element and should free +any memory and resources allocated for it. + + +@data: the data element. + + + + +Gets the data element corresponding to a #GQuark. + + +@dataset_location: the location identifying the dataset. +@key_id: the #GQuark id to identify the data element. +@Returns: the data element corresponding to the #GQuark, or NULL if it is +not found. + + + + +Removes a data element from a dataset. +The data element's destroy function is called if it has been set. + + +@l: the location identifying the dataset. +@k: the #GQuark id identifying the data element. + + + + + + + +@dataset_location: +@key_id: + + + + +Sets the data corresponding to the given string identifier. + + +@l: the location identifying the dataset. +@k: the string to identify the data element. +@d: the data element. + + + + +Sets the data corresponding to the given string identifier, and the function +to call when the data element is destroyed. + + +@l: the location identifying the dataset. +@k: the string to identify the data element. +@d: the data element. +@f: the function to call when the data element is removed. This +function will be called with the data element and can be used to free any +memory allocated for it. + + + + +Gets the data element corresponding to a string. + + +@l: the location identifying the dataset. +@k: the string identifying the data element. +@Returns: the data element corresponding to the string, or NULL if it is not +found. + + + + +Removes a data element corresponding to a string. +Its destroy function is called if it has been set. + + +@l: the location identifying the dataset. +@k: the string identifying the data element. + + + + + + + +@l: +@k: + + + + +Calls the given function for each data element which is associated with the +given location. + + +@dataset_location: the location identifying the dataset. +@func: the function to call for each data element. +@user_data: user data to pass to the function. + + + + +Specifies the type of function passed to g_dataset_foreach(). +It is called with each #GQuark id and associated data element, +together with the @user_data parameter supplied to g_dataset_foreach(). + + +@key_id: the #GQuark id to identifying the data element. +@data: the data element. +@user_data: user data passed to g_dataset_foreach(). + + + + +Destroys the dataset, freeing all memory allocated, and calling any +destroy functions set for data elements. + + +@dataset_location: the location identifying the dataset. + + diff --git a/docs/reference/glib/tmpl/date.sgml b/docs/reference/glib/tmpl/date.sgml new file mode 100644 index 00000000..7350193b --- /dev/null +++ b/docs/reference/glib/tmpl/date.sgml @@ -0,0 +1,655 @@ + +Date and Time Functions + + + +Calendrical Calculations and Miscellaneous Time Stuff + + + +The #GDate data structure represents a day between January 1, Year 1, +and sometime a few thousand years in the future (right now it will go +to the year 65535 or so, but g_date_set_parse() only parses up to the +year 8000 or so - just count on "a few thousand"). #GDate is meant to +represent everyday dates, not astronomical dates or historical dates +or ISO timestamps or the like. It extrapolates the current Gregorian +calendar forward and backward in time; there is no attempt to change +the calendar to match time periods or locations. #GDate does not store +time information; it represents a day. + + + +The #GDate implementation has several nice features; it is only a +64-bit struct, so storing large numbers of dates is very efficient. It +can keep both a Julian and Day-Month-Year representation of the date, +since some calculations are much easier with one representation or the +other. A Julian representation is simply a count of days since some +fixed day in the past; for #GDate the fixed day is January 1, 1 AD. +("Julian" dates in the #GDate API aren't really Julian dates in the +technical sense; technically, Julian dates count from the start of the +Julian period, Jan 1, 4713 BC). + + + +#GDate is simple to use. First you need a "blank" date; you can get a +dynamically allocated date from g_date_new(), or you can declare an +automatic variable or array and initialize it to a sane state by +calling g_date_clear(). A cleared date is sane; it's safe to call +g_date_set_dmy() and the other mutator functions to initialize the +value of a cleared date. However, a cleared date is initially +invalid, meaning that it doesn't represent a day +that exists. It is undefined to call any of the date calculation +routines on an invalid date. If you obtain a date from a user or other +unpredictable source, you should check its validity with the +g_date_valid() predicate. g_date_valid() is also used to check for +errors with g_date_set_parse() and other functions that can +fail. Dates can be invalidated by calling g_date_clear() again. + + + +It is very important to use the API to access the #GDate +struct. Often only the DMY or only the Julian +representation is valid. Sometimes neither is valid. Use the API. + + + +glib doesn't contain any time-manipulation functions; however, there +is a #GTime typedef which is equivalent to time_t, and a #GTimeVal +struct which represents a more precise time (with microseconds). You +can request the current time as a #GTimeVal with g_get_current_time(). + + + + + + + + + +Represents a precise time, with seconds and microseconds. Same as the +struct timeval returned by the +gettimeofday() UNIX call. + + +@tv_sec: +@tv_usec: + + + +Equivalent to gettimeofday(), but also works on +Win32. Returns the current time. + + +@result: + + + + +Simply a replacement for time_t. Unrelated to GTimer. + + + + + +Represents a day between January 1, Year 1 and a few thousand years in +the future. None of its members should be accessed directly. If the +GDate is obtained from g_date_new(), it will +be safe to mutate but invalid and thus not safe for calendrical computations. +If it's declared on the stack, it will contain garbage so must be +initialized with g_date_clear(). g_date_clear() makes the date invalid +but sane. An invalid date doesn't represent a day, it's "empty." A +date becomes valid after you set it to a Julian day or you set a day, +month, and year. + + +@julian_days: +@julian: +@dmy: +@day: +@month: +@year: + + + +This enumeration isn't used in the API, but may be useful if you need +to mark a number as a day, month, or year. + + +@G_DATE_DAY: +@G_DATE_MONTH: +@G_DATE_YEAR: + + + +Integer representing a day of the month; between 1 and +31. #G_DATE_BAD_DAY represents an invalid day of the month. + + + + + +Enumeration representing a month; values are #G_DATE_JANUARY, +#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the "invalid" value. + + +@G_DATE_BAD_MONTH: +@G_DATE_JANUARY: +@G_DATE_FEBRUARY: +@G_DATE_MARCH: +@G_DATE_APRIL: +@G_DATE_MAY: +@G_DATE_JUNE: +@G_DATE_JULY: +@G_DATE_AUGUST: +@G_DATE_SEPTEMBER: +@G_DATE_OCTOBER: +@G_DATE_NOVEMBER: +@G_DATE_DECEMBER: + + + +Enumeration representing a day of the week; #G_DATE_MONDAY, +#G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday. + + +@G_DATE_BAD_WEEKDAY: +@G_DATE_MONDAY: +@G_DATE_TUESDAY: +@G_DATE_WEDNESDAY: +@G_DATE_THURSDAY: +@G_DATE_FRIDAY: +@G_DATE_SATURDAY: +@G_DATE_SUNDAY: + + + +Integer representing a year; #G_DATE_BAD_YEAR is the invalid +value. The year must be 1 or higher; negative (BC) years are not +allowed. The year is represented with four digits. + + + + + +Represents an invalid #GDateDay. + + + + + + +Represents an invalid Julian day number. + + + + + + +Represents an invalid year. + + + + + + +Increment a date some number of days. To move forward by weeks, add +weeks*7 days. The date must be valid. + + +@date: The date to increment +@n_days: Number of days to move the date forward + + + + +Increment a date by some number of months. If the day of the month is +greater than 28, this routine may change the day of the month (because +the destination month may not have the current day in it). The date +must be valid. + + +@date: Date to increment +@n_months: Number of months to move forward + + + + +Increment a date by some number of years. If the date is February 29, +and the destination year is not a leap year, the date will be changed +to February 28. The date must be valid. + + +@date: Date to increment +@n_years: Number of years to move forward + + + + +Initialize one or more #GDate structs to a sane but invalid +state. The cleared dates will not represent an existing date, but will +not contain garbage. Useful to init a date declared on the stack. +Validity can be tested with g_date_valid(). + + +@date: Pointer to one or more dates to clear +@n_dates: Number of dates to clear + + + + +qsort()-style comparsion function for dates. Both +dates must be valid. + + +@lhs: First date to compare +@rhs: Second date to compare +@Returns: 0 for equal, less than zero if @lhs is less than @rhs, +greater than zero if @lhs is greater than @rhs + + + + +Return the day of the month; the #GDate must be valid. + + +@date: Date to extract the day of the month from +@Returns: Day of the month + + + + +Return the day of the year, where Jan 1 is the first day of the +year. Date must be valid. + + +@date: Date to extract day of year from +@Returns: Day of the year + + + + +Return the number of days in a month, taking leap years into account. + + +@month: Month +@year: Year +@Returns: Number of days in @month during the year @year. + + + + +Free a #GDate returned from g_date_new() + + +@date: Date to free + + + + +Returns TRUE if the date is on the first of a month. Date must be valid. + + +@date: Date to check +@Returns: Boolean, if the date is the first of the month + + + + +Returns TRUE if the date is the last day of the month. Date must be valid. + + +@date: Date to check +@Returns: Boolean, if the date is the last day of the month + + + + +Returns TRUE if the year is a leap year + + +@year: Year to check +@Returns: Boolean, if the year is a leap year + + + + +Accessor, returns the Julian day or "serial number" of the #GDate. The +Julian day is simply the number of days since January 1, Year 1; i.e., +January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2, +etc. Date must be valid. + + +@date: Date to extract the Julian day from +@Returns: Julian day + + + + +Return the week of the year, where weeks are understood to start on +Monday. If the date is before the first Monday of the year, return +0. Date must be valid. + + +@date: Date to use +@Returns: Week of the year + + + + +Return the number of weeks in the year, where weeks are taken to start +on Monday. Will be 52 or 53. Date must be valid. (Years always have 52 +7-day periods, plus 1 or 2 extra days depending on whether it's a leap +year. This function is basically telling you how many Mondays are in +the year, i.e. there are 53 Mondays if one of the extra days happens +to be a Monday.) + + +@year: Year +@Returns: Number of Mondays in the year + + + + +Accessor for the month of the year. Date must be valid. + + +@date: Date to get the month from +@Returns: A #GDateMonth + + + + +Allocate a #GDate and initialize it to a sane state. The new date will +be cleared (as if you'd called g_date_clear()) but invalid (it won't +represent an existing day). Free the return value with g_date_free(). + + +@Returns: The newly-allocated #GDate + + + + +Like g_date_new(), but also sets the value of the date. Assuming the +day/month/year triplet you pass in represents an existing day, the +returned date will be valid. + + +@day: Day of the month +@month: Month of the year +@year: Year +@Returns: Allocated date initialized with @day, @month, and @year + + + + +Like g_date_new(), but also sets the value of the date. Assuming the +Julian day number you pass in is valid (greater than 0, less than an +unreasonably large number), the returned date will be valid. + + +@julian_day: Days since January 1, Year 1 +@Returns: Allocated date initialized with @julian_day + + + + +Set the day of the month for a #GDate. If the resulting day-month-year +triplet is invalid, the date will be invalid. + + +@date: Date to set the day for +@day: Day to set + + + + +Set the value of a #GDate from a day, month, and year. The DMY triplet +must be valid; if you aren't sure it is, call g_date_valid_dmy() to +check before you set it. + + +@date: Date to set the value of +@day: Day +@month: Month +@y: Year + + + + +Set the value of a #GDate from a Julian day number. + + +@date: Date to set +@julian_date: Julian day number (days since January 1, Year 1) + + + + +Set the month of the year for a #GDate. If the resulting + day-month-year triplet is invalid, the date will be invalid. + + +@date: Date +@month: Month to set + + + + +Parse a user-inputted string @str, and try to figure out what date it +represents, taking the current locale into account. If the string is +successfully parsed, the date will be valid after the call. Otherwise, +it will be invalid. You should check using g_date_valid() to see +whether the parsing succeeded. + + + +This function is not appropriate for file formats and the like; it +isn't very precise, and its exact behavior varies with the +locale. It's intended to be a heuristic routine that guesses what the +user means by a given string (and it does work pretty well in that +capacity). + + +@date: Date to fill in +@str: String to parse + + + + +Set the value of a date from a #GTime (time_t) value. To set the value +of a date to the current day, you could write: + + g_date_set_time(date, time(NULL)); + + + +@date: Date to update +@time: #GTime value to set + + + + +Set the year for a #GDate. If the resulting day-month-year triplet is + invalid, the date will be invalid. + + +@date: Date +@year: Year to set + + + + +Generate a printed representation of the date, in a locale-specific +way. Works just like the standard C strftime() +function, but only accepts date-related formats; time-related formats +give undefined results. Date must be valid. + + +@s: Destination buffer +@slen: Max buffer size +@format: Format string +@date: valid #GDate +@Returns: number of characters written to the buffer, or 0 the buffer was too small + + + + +Move a date some number of days into the past. To move by weeks, just +move by weeks*7 days. Date must be valid. + + +@date: Date to decrement +@n_days: Number of days to move + + + + +Move a date some number of months into the past. If the current day of +the month doesn't exist in the destination month, the day of the month +may change. Date must be valid. + + +@date: Date to decrement +@n_months: Number of months to move + + + + +Move a date some number of years into the past. If the current day +doesn't exist in the destination year (i.e. it's February 29 and you +move to a non-leap-year) then the day is changed to February 29. Date +must be valid. + + +@date: Date to decrement +@n_years: Number of years to move + + + + +Week of the year during which this date falls, if weeks are understood +to being on Sunday. Date must be valid. Can return 0 if the day is +before the first Sunday of the year. + + +@date: Date +@Returns: Week number + + + + +Return the number of weeks in the year, where weeks are taken to start +on Sunday. Will be 52 or 53. Date must be valid. (Years always have 52 +7-day periods, plus 1 or 2 extra days depending on whether it's a leap +year. This function is basically telling you how many Sundays are in +the year, i.e. there are 53 Sundays if one of the extra days happens +to be a Sunday.) + + +@year: Year to count weeks in +@Returns: Number of weeks + + + + +Fills in the date-related bits of a struct tm +using the @date value. Initializes the non-date parts with something +sane but meaningless. + + +@date: Date to set the struct tm from +@tm: struct tm to fill + + + + +Returns TRUE if the #GDate represents an existing day. #GDate must not +contain garbage; it should have been initialized with g_date_clear() +if it wasn't allocated by one of the g_date_new() variants. + + +@date: Date to check +@Returns: Whether the date is valid. + + + + +Returns TRUE if the day of the month is valid (a day is valid if it's +between 1 and 31 inclusive). + + +@day: Day to check. +@Returns: Boolean, whether the day is valid. + + + + +Returns TRUE if the day/month/year triplet forms a valid, existing day +in the range of days GDate understands (Year 1 or later, no more than +a few thousand years in the future). + + +@day: Day +@month: Month +@year: Year +@Returns: Boolean, whether the date is a valid one + + + + +Returns TRUE if the Julian day is valid. Anything greater than zero is basically a +valid Julian, though there is a 32-bit limit. + + +@julian_date: Julian day to check +@Returns: Boolean, whether the Julian day is valid. + + + + +Returns TRUE if the month value is valid. The 12 #GDateMonth +enumeration values are the only valid months. + + +@month: Month +@Returns: Boolean, whether the month is valid + + + + +Returns TRUE if the weekday is valid. The 7 #GDateWeekday enumeration +values are the only valid weekdays. + + +@weekday: Weekday +@Returns: Boolean, whether the weekday is valid. + + + + +Returns TRUE if the year is valid. Any year greater than 0 is valid, +though there is a 16-bit limit to what GDate will understand. + + +@year: Year +@Returns: Boolean, whether the year is valid. + + + + +Returns the day of the week for a #GDate. The date must be valid. + + +@date: Date +@Returns: Day of the week as a #GDateWeekday + + + + +Accessor; returns the year of a #GDate. The date must be valid. + + +@date: Date +@Returns: Year in which the date falls + + diff --git a/docs/reference/glib/tmpl/glib-unused.sgml b/docs/reference/glib/tmpl/glib-unused.sgml new file mode 100644 index 00000000..e69de29b diff --git a/docs/reference/glib/tmpl/hash_tables.sgml b/docs/reference/glib/tmpl/hash_tables.sgml new file mode 100644 index 00000000..75ffd060 --- /dev/null +++ b/docs/reference/glib/tmpl/hash_tables.sgml @@ -0,0 +1,358 @@ + +Hash Tables + + +associations between keys and values so that given a key the value +can be found quickly. + + + +A #GHashTable provides associations between keys and values which +is optimized so that given a key, the associated value can be found +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) +should be copied with g_strdup() before being inserted. + + +If keys or values are dynamically allocated, you must be careful to ensure +that they are freed when they are removed from the #GHashTable, and also +when they are overwritten by new insertions into the #GHashTable. +It is also not advisable to mix static strings and dynamically-allocated +strings in a #GHashTable, because it then becomes difficult to determine +whether the string should be freed. + + +To create a #GHashTable, use g_hash_table_new(). + + +To insert a key and value into a #GHashTable, use g_hash_table_insert(). + + +To lookup a value corresponding to a given key, use g_hash_table_lookup() +and g_hash_table_lookup_extended(). + + +To remove a key and value, use g_hash_table_remove(). + + +To call a function for each key and value pair use g_hash_table_foreach(). + + +To destroy a #GHashTable use g_hash_table_destroy(). + + + + + + + + + +The #GHashTable struct is an opaque data structure to represent a +Hash Table. +It should only be accessed via the following functions. + + + + + +Creates a new #GHashTable. + + +@hash_func: a function to create a hash value from a key. +Hash values are used to determine where keys are stored within the +#GHashTable data structure. +The g_direct_hash(), g_int_hash() and g_str_hash() functions are provided for +some common types of keys. If hash_func is NULL, g_direct_hash() is used. +@key_compare_func: a function to compare two keys to see if they are equal. +This is used when looking up keys in the #GHashTable. +The g_direct_equal(), g_int_equal() and g_str_equal() functions are provided +for the most common types of keys. If compare_func is NULL, keys are compared +directly in a similar fashion to g_direct_equal(), but without the overhead +of a function call. +@Returns: a new #GHashTable. + + + + +Specifies the type of the hash function which is passed to +g_hash_table_new() when a #GHashTable is created. + + +The function is passed a key and should return a guint hash value. +The functions g_direct_hash(), g_int_hash() and g_str_hash() provide +hash functions which can be used when the key is a #gpointer, #gint, and +#gchar* respectively. + + +FIXME: Need more here. +The hash values should be evenly distributed over a fairly large range? +The modulus is taken with the hash table size (a prime number) +to find the 'bucket' to place each key into. +The function should also be very fast, since it is called for each key +lookup. + + +@key: a key. +@Returns: the hash value corresponding to the key. + + + + +Specifies the type of a comparison function used to compare two values. +The value which should be returned depends on the context in which the +#GCompareFunc is used. + + +In g_hash_table_new(), g_cache_new(), and g_relation_index() the function +should return TRUE if the two parameters are equal, or FALSE if they are not. + + +In g_list_find_custom() and g_slist_find_custom() the function should return +0 if the two parameters are equal. + + +In g_list_insert_sorted(), g_list_sort(), g_slist_insert_sorted(), +g_slist_sort() and g_tree_new() the function should return a negative integer +if the first value comes before the second, 0 if they are equal, or a positive +integer if the first value comes after the second. + + +@a: a value. +@b: a value to compare with. +@Returns: TRUE if the two values are equivalent. + + + + +Inserts a new key and value into a #GHashTable. +If the key already exists in the #GHashTable its current value is replaced +with the new value. + + + +If the keys or values use dynamically allocated memory, then you should +first check if the key already exists in the GHashTable. If it does, +you should free the existing key and/or value before inserting the +new key and value. + + + +@hash_table: a #GHashTable. +@key: a key to insert. +@value: the value to associate with the key. + + + + +Returns the number of key/value pairs in a #GHashTable. + + +@hash_table: a #GHashTable. +@Returns: the number of key/value pairs in the #GHashTable. + + + + +Looks up a key in the #GHashTable, returning the associated value or NULL +if the key is not found. + + +@hash_table: a #GHashTable. +@key: the key to look up. +@Returns: the associated value, or NULL if the key is not found. + + + + +Looks up a key in the #GHashTable, returning the original key and the +associated value and a gboolean which is TRUE if the key was found. +This is useful if you need to free the memory allocated for the +original key, for example before calling g_hash_table_remove(). + + +@hash_table: a #GHashTable. +@lookup_key: the key to look up. +@orig_key: returns the original key. +@value: returns the value associated with the key. +@Returns: TRUE if the key was found in the #GHashTable. + + + + +Calls the given function for each of the key/value pairs in the #GHashTable. +The function is passed the key and value of each pair, and the given +@user_data parameter. + + +@hash_table: a #GHashTable. +@func: the function to call for each key/value pair. +@user_data: use data to pass to the function. + + + + +Specifies the type of the function passed to g_hash_table_foreach(). +It is called with each key/value pair, together with the @user_data parameter +which is passed to g_hash_table_foreach(). + + +@key: a key. +@value: the value corresponding to the key. +@user_data: user data passed to g_hash_table_foreach(). + + + + +Removes a key and its associated value from a #GHashTable. + + + +As with g_hash_table_insert(), you should make sure that any dynamically +allocated values are freed yourself. + + + +@hash_table: a #GHashTable. +@key: the key to remove. + + + + +Calls the given function for each key/value pair in the #GHashTable. +If the function returns TRUE, then the key/value pair is removed from the +#GHashTable. + + +@hash_table: a #GHashTable. +@func: the function to call for each key/value pair. +@user_data: user data to pass to the function. +@Returns: the number of key/value paris removed. + + + + +Specifies the type of the function passed to g_hash_table_foreach_remove(). +It is called with each key/value pair, together with the @user_data parameter +passed to g_hash_table_foreach_remove(). +It should return TRUE if the key/value pair should be removed from the +#GHashTable. + + +@key: a key. +@value: the value associated with the key. +@user_data: user data passed to g_hash_table_remove(). +@Returns: TRUE if the key/value pair should be removed from the #GHashTable. + + + + +Disable resizing of a #GHashTable. + + +This should be used if you need to make a lot of changes to a #GHashTable +at once, as it reduces the number of times that the #GHashTable is rebuilt. +You should call g_hash_table_thaw() after updating the #GHashTable to +enable resizing again. + + +@hash_table: a #GHashTable. + + + + +Enables resizing of a #GHashTable. + + +@hash_table: a #GHashTable. + + + + +Destroys the #GHashTable. + + + +If keys and/or values are dynamically allocated, you should free them +first. + + + +@hash_table: a #GHashTable. + + + + +Compares two #gpointer arguments and returns TRUE if they are equal. +It can be passed to g_hash_table_new() as the @key_compare_func +parameter, when using pointers as keys in a #GHashTable. + + +@v: a key. +@v2: a key to compare with @v. +@Returns: TRUE if the two keys match. + + + + +Converts a gpointer to a hash value. +It can be passed to g_hash_table_new() as the @hash_func parameter, when +using gpointer values as keys in a #GHashTable. + + +@v: a gpointer key. +@Returns: a hash value corresponding to the key. + + + + +Compares the two #gint values being pointed to and returns TRUE if they are +equal. +It can be passed to g_hash_table_new() as the @key_compare_func +parameter, when using pointers to integers as keys in a #GHashTable. + + +@v: a pointer to a #gint key. +@v2: a pointer to a #gint key to compare with @v. +@Returns: TRUE if the two keys match. + + + + +Converts a pointer to a #gint to a hash value. +It can be passed to g_hash_table_new() as the @hash_func parameter, when +using pointers to gint values as keys in a #GHashTable. + + +@v: a pointer to a #gint key. +@Returns: a hash value corresponding to the key. + + + + +Compares two strings and returns TRUE if they are equal. +It can be passed to g_hash_table_new() as the @key_compare_func +parameter, when using strings as keys in a #GHashTable. + + +@v: a key. +@v2: a key to compare with @v. +@Returns: TRUE if the two keys match. + + + + +Converts a string to a hash value. +It can be passed to g_hash_table_new() as the @hash_func parameter, when +using strings as keys in a #GHashTable. + + +@v: a string key. +@Returns: a hash value corresponding to the key. + + diff --git a/docs/reference/glib/tmpl/hooks.sgml b/docs/reference/glib/tmpl/hooks.sgml new file mode 100644 index 00000000..47cf06e1 --- /dev/null +++ b/docs/reference/glib/tmpl/hooks.sgml @@ -0,0 +1,524 @@ + +Hook Functions + + +support for manipulating lists of hook functions. + + + +The #GHookList, #GHook and their related functions provide support for +lists of hook functions. Functions can be added and removed from the lists, +and the list of hook functions can be invoked. + + + + + + + + + + + + + + + + +#guint seq_id; +the next free #GHook id. + + + +#guint hook_size; +the size of the #GHookList elements, in bytes. + + + +#guint is_setup : 1; +1 if the #GHookList has been initialized. + + + +#GHook *hooks; +the first #GHook element in the list. + + + +#GMemChunk *hook_memchunk; +the #GMemChunk used for allocating the #GHook elements. + + + +#GHookFreeFunc hook_free; +the function to call to free a #GHook element. + + + +#GHookFreeFunc hook_destroy; +the function to call to destory a #GHook element. + + + + + + +@seq_id: +@hook_size: +@is_setup: +@hooks: +@hook_memchunk: +@hook_free: +@hook_destroy: + + + + + + + + + +#gpointer data; +. + + + +#GHook *next; +. + + + +#GHook *prev; +. + + + +#guint ref_count; +. + + + +#guint hook_id; +. + + + +#guint flags; +. + + + +#gpointer data; +. + + + +#GDestroyNotify destroy; +. + + + + + +@data: +@next: +@prev: +@ref_count: +@hook_id: +@flags: +@func: +@destroy: + + + + + + +@data: + + + + + + + +@data: +@Returns: + + + + + + + +@hook: +@data: + + + + + + + +@hook: +@data: +@Returns: + + + + + + + +@hook_list: +@hook: + + + + + + + + + + + +Initializes a #GHookList. +This must be called before the #GHookList is used. + + +@hook_list: a #GHookList. +@hook_size: the size of each element in the #GHookList, typically +sizeof (GHook). + + + + +Calls all of the #GHook functions in a #GHookList. + + +@hook_list: a #GHookList. +@may_recurse: TRUE if functions which are already running (e.g. in another +thread) can be called. If set to FALSE, these are skipped. + + + + +Calls all of the #GHook functions in a #GHookList. +Any function which returns TRUE is removed from the #GHookList. + + +@hook_list: a #GHookList. +@may_recurse: TRUE if functions which are already running (e.g. in another +thread) can be called. If set to FALSE, these are skipped. + + + + + + + +@hook_list: a #GHookList. +@may_recurse: +@marshaller: +@data: + + + + + + + +@hook_list: a #GHookList. +@may_recurse: +@marshaller: +@data: + + + + +Removes all the #GHook elements from a #GHookList. + + +@hook_list: a #GHookList. + + + + +Allocates space for a #GHook and initializes it. + + +@hook_list: a #GHookList. +@Returns: a new #GHook. + + + + +Appends a #GHook onto the end of a #GHookList. + + +@hook_list: a #GHookList. +@hook: the #GHook to add to the end of @hook_list. + + + + +Prepends a #GHook on the start of a #GHookList. + + +@hook_list: a #GHookList. +@hook: the #GHook to add to the start of @hook_list. + + + + +Inserts a #GHook into a #GHookList, before a given #GHook. + + +@hook_list: a #GHookList. +@sibling: the #GHook to insert the new #GHook before. +@hook: the #GHook to insert. + + + + +Inserts a #GHook into a #GHookList, sorted by the given function. + + +@hook_list: a #GHookList. +@hook: the #GHook to insert. +@func: the comparison function used to sort the #GHook elements. + + + + +Defines the type of function used to compare #GHook elements in +g_hook_insert_sorted(). + + +@new_hook: the #GHook being inserted. +@sibling: the #GHook to compare with @new_hook. +@Returns: a value <= 0 if @new_hook should be before @sibling. + + + + +Compares the ids of two #GHook elements, returning a negative value +if the second id is greater than the first. + + +@new_hook: a #GHook. +@sibling: a #GHook to compare with @new_hook. +@Returns: a value <= 0 if the id of @sibling is >= the id of @new_hook. + + + + +Returns the #GHook with the given id, or NULL if it is not found. + + +@hook_list: a #GHookList. +@hook_id: a hook id. +@Returns: the #GHook with the given id, or NULL if it is not found. + + + + +Finds a #GHook in a #GHookList using the given function to test for a match. + + +@hook_list: a #GHookList. +@need_valids: TRUE if #GHook elements which have been destroyed should be +skipped. +@func: the function to call for each #GHook, which should return TRUE when +the #GHook has been found. +@data: the data passed to @func. +@Returns: the found #GHook or NULL if no matching #GHook is found. + + + + +Finds a #GHook in a #GHookList with the given data. + + +@hook_list: a #GHookList. +@need_valids: TRUE if #GHook elements which have been destroyed should be +skipped. +@data: the data to find. +@Returns: the #GHook with the given @data or NULL if no matching +#GHook is found. + + + + +Finds a #GHook in a #GHookList with the given function. + + +@hook_list: a #GHookList. +@need_valids: TRUE if #GHook elements which have been destroyed should be +skipped. +@func: the function to find. +@Returns: the #GHook with the given @func or NULL if no matching +#GHook is found. + + + + +Defines the type of the function passed to g_hooK_find_func(). + + +@hook: a #GHook. +@data: user data passed to g_hook_find_func(). +@Returns: TRUE if the required #GHook has been found. + + + + +Finds a #GHook in a #GHookList with the given function and data. + + +@hook_list: a #GHookList. +@need_valids: TRUE if #GHook elements which have been destroyed should be +skipped. +@func: the function to find. +@data: the data to find. +@Returns: the #GHook with the given @func and @data or NULL if no matching +#GHook is found. + + + + +Returns the first #GHook in a #GHookList which has not been destroyed. +The reference count for the #GHook is incremented, so you must call +g_hook_unref() to restore it when no longer needed. (Or call +g_hook_next_valid() if you are stepping through the #GHookList.) + + +@hook_list: a #GHookList. +@may_be_in_call: TRUE if hooks which are currently running (e.g. in another +thread) are considered valid. If set to FALSE, these are skipped. +@Returns: the first valid #GHook, or NULL if none are valid. + + + + +Returns the next #GHook in a #GHookList which has not been destroyed. +The reference count for the #GHook is incremented, so you must call +g_hook_unref() to restore it when no longer needed. (Or continue to call +g_hook_next_valid() until NULL is returned.) + + + +@hook_list: a #GHookList. +@hook: the current #GHook. +@may_be_in_call: TRUE if hooks which are currently running (e.g. in another +thread) are considered valid. If set to FALSE, these are skipped. +@Returns: the next valid #GHook, or NULL if none are valid. + + + + + + + +@G_HOOK_FLAG_ACTIVE: +@G_HOOK_FLAG_IN_CALL: +@G_HOOK_FLAG_MASK: + + + + + + + + + + +Returns TRUE if the #GHook is valid, i.e. it is in a #GHookList, it is active +and it has not been destroyed. + + +@hook: a #GHook. +@Returns: TRUE if the #GHook is valid. + + + + +Returns TRUE if the #GHook is active, which is normally TRUE until the #GHook +is destroyed. + + +@hook: a #GHook. +@Returns: TRUE if the #GHook is active. + + + + +Returns TRUE if the #GHook function is currently executing. + + +@hook: a #GHook. +@Returns: TRUE if the #GHook function is currently executing. + + + + +Returns TRUE if the #GHook is not in a #GHookList. + + + +@hook: a #GHook. +@Returns: TRUE if the #GHook is not in a #GHookList. + + + + +Increments the reference count for a #GHook. + + +@hook_list: a #GHookList. +@hook: the #GHook to increment the reference count of. + + + + +Decrements the reference count of a #GHook. +If the reference count falls to 0, the #GHook is removed from the #GHookList +and g_hook_free() is called to free it. + + +@hook_list: a #GHookList. +@hook: + + + + +Calls the #GHookList @hook_free function if it exists, and frees the memory +allocated for the #GHook. + + +@hook_list: a #GHookList. +@hook: the #GHook to free. + + + + +Destroys a #GHook, given its ID. + + +@hook_list: a #GHookList. +@hook_id: a hook ID. +@Returns: TRUE if the #GHook was found in the #GHookList and destroyed. + + + + +Removes one #GHook from a #GHookList, calling the @hook_destroy function in +the #GHookList, and the @destroy function of the #GHook, if they exist. + + +@hook_list: a #GHookList. +@hook: the #GHook to remove. + + diff --git a/docs/reference/glib/tmpl/iochannels.sgml b/docs/reference/glib/tmpl/iochannels.sgml new file mode 100644 index 00000000..1c44eb2c --- /dev/null +++ b/docs/reference/glib/tmpl/iochannels.sgml @@ -0,0 +1,319 @@ + +IO Channels + + +portable support for using files, pipes and sockets. + + + +The #GIOChannel data type aims to provide a portable method for using file +descriptors, pipes, and sockets, and integrating them into the +main event loop. +Currently full support is available on Unix platforms, though support for +Windows is only partially complete. + + +To create a new #GIOChannel on Unix systems use g_io_channel_unix_new(). +This works for plain file descriptors, pipes and sockets. + + +Once a #GIOChannel has been created, it can be used in a generic manner +with the functions g_io_channel_read(), g_io_channel_write(), +g_io_channel_seek(), and g_io_channel_close(). + + +To add a #GIOChannel to the +main event loop +use g_io_add_watch() or g_io_add_watch_full(). Here you specify which events +you are interested in on the #GIOChannel, and provide a function to be +called whenever these events occur. + + +#GIOChannel instances are created with an initial reference count of 1. +g_io_channel_ref() and g_io_channel_unref() can be used to increment or +decrement the reference count respectively. When the reference count falls +to 0, the #GIOChannel is freed. (Though it isn't closed automatically.) +Using g_io_add_watch() or g_io_add_watch_full() increments a channel's +reference count. + + +GTK+ contains the convenience function gtk_input_add_full() +which creates a #GIOChannel from a file descriptor and adds it to the +main event loop. +The event source can later be removed with gtk_input_remove(). +Similar functions can also be found in GDK. + + + + + + + +gtk_input_add_full(), gtk_input_remove(), gdk_input_add(), +gdk_input_add_full(), gdk_input_remove() + +Convenience functions for creating #GIOChannel instances and adding them to the +main event loop. + + + + + + + + +A data structure representing an IO Channel. The fields should be considered +private and should only be accessed with the following functions. + + +@channel_flags: +@ref_count: +@funcs: + + + +Creates a new #GIOChannel given a file descriptor. +On Unix systems this works for plain files, pipes, and sockets. + + +The returned #GIOChannel has a reference count of 1. + + +@fd: a file descriptor. +@Returns: a new #GIOChannel. + + + + +Returns the file descriptor of the Unix #GIOChannel. + + +@channel: a #GIOChannel, created with g_io_channel_unix_new(). +@Returns: the file descriptor of the #GIOChannel. + + + + +Initializes a #GIOChannel struct. This is called by each of the above functions +when creating a #GIOChannel, and so is not often needed by the application +programmer (unless you are creating a new type of #GIOChannel). + + +@channel: a #GIOChannel. + + + + +Reads data from a #GIOChannel. + + +@channel: a #GIOChannel. +@buf: a buffer to read the data into (which should be at least count bytes +long). +@count: the number of bytes to read from the #GIOChannel. +@bytes_read: returns the number of bytes actually read. +@Returns: %G_IO_ERROR_NONE if the operation was successful. + + + + + + + +@G_IO_ERROR_NONE: +@G_IO_ERROR_AGAIN: +@G_IO_ERROR_INVAL: +@G_IO_ERROR_UNKNOWN: + + + +Writes data to a #GIOChannel. + + +@channel: a #GIOChannel. +@buf: the buffer containing the data to write. +@count: the number of bytes to write. +@bytes_written: the number of bytes actually written. +@Returns: %G_IO_ERROR_NONE if the operation was successful. + + + + +Sets the current position in the #GIOChannel, similar to the standard system +call fseek(). + + +@channel: a #GIOChannel. +@offset: an offset, in bytes, which is added to the position specified by +@type. +@type: the position in the file, which can be %G_SEEK_CUR (the current +position), %G_SEEK_SET (the start of the file), or %G_SEEK_END (the end of the +file). +@Returns: %G_IO_ERROR_NONE if the operation was successful. + + + + +An enumeration specifying the base position for a g_io_channel_seek() +operation. + + + + + + +G_SEEK_CUR +the current position in the file. + + + +G_SEEK_SET +the start of the file. + + + +G_SEEK_END +the end of the file. + + + + + + +@G_SEEK_CUR: +@G_SEEK_SET: +@G_SEEK_END: + + + +Closes a #GIOChannel. +The #GIOChannel will be freed when its reference count drops to 0. + + +@channel: a #GIOChannel. + + + + +Increments the reference count of a #GIOChannel. + + +@channel: a #GIOChannel. + + + + +Decrements the reference count of a #GIOChannel. + + +@channel: a #GIOChannel. + + + + +Adds the #GIOChannel into the +main event loop +with the default priority. + + +@channel: a #GIOChannel. +@condition: the condition to watch for. +@func: the function to call when the condition is satisfied. +@user_data: user data to pass to @func. +@Returns: the event source id. + + + + +Adds the #GIOChannel into the +main event loop +with the given priority. + + +@channel: a #GIOChannel. +@priority: the priority of the #GIOChannel source. +@condition: the condition to watch for. +@func: the function to call when the condition is satisfied. +@user_data: user data to pass to @func. +@notify: the function to call when the source is removed. +@Returns: the event source id. + + + + +A bitwise combination representing a condition to watch for on an event +source. + + + + + + +G_IO_IN +There is data to read. + + + +G_IO_OUT +Data can be written (without blocking). + + + +G_IO_PRI +There is urgent data to read. + + + +G_IO_ERR +Error condition. + + + +G_IO_HUP +Hung up (the connection has been broken, usually for pipes and +sockets). + + + +G_IO_NVAL +Invalid request. The file descriptor is not open. + + + + + + +@G_IO_IN: +@G_IO_OUT: +@G_IO_PRI: +@G_IO_ERR: +@G_IO_HUP: +@G_IO_NVAL: + + + +Specifies the type of function passed to g_io_add_watch() or +g_io_add_watch_full(), which is called when the requested condition on a +#GIOChannel is satisfied. + + +@source: the #GIOChannel event source. +@condition: the condition which has been satisfied. +@data: user data set in g_io_add_watch() or g_io_add_watch_full(). +@Returns: the function should return FALSE if the event source should be +removed. + + + + +A table of functions used to handle different types of #GIOChannel in a +generic way. + + +@io_read: +@io_write: +@io_seek: +@io_close: +@io_add_watch: +@io_free: + diff --git a/docs/reference/glib/tmpl/limits.sgml b/docs/reference/glib/tmpl/limits.sgml new file mode 100644 index 00000000..ec68926d --- /dev/null +++ b/docs/reference/glib/tmpl/limits.sgml @@ -0,0 +1,87 @@ + +Limits of Basic Types + + +portable method of determining the limits of the standard types. + + + +These macros provide a portable method to determine the limits of some of +the standard integer and floating point types. + + + + + + + + + +The minimum value which can be held in a #gint. + + + + + + +The maximum value which can be held in a #gint. + + + + + + +The minimum value which can be held in a #gshort. + + + + + + +The maximum value which can be held in a #gshort. + + + + + + +The minimum value which can be held in a #glong. + + + + + + +The maximum value which can be held in a #glong. + + + + + + +The minimum value which can be held in a #gfloat. + + + + + + +The maximum value which can be held in a #gfloat. + + + + + + +The minimum value which can be held in a #gdouble. + + + + + + +The maximum value which can be held in a #gdouble. + + + + diff --git a/docs/reference/glib/tmpl/linked_lists_double.sgml b/docs/reference/glib/tmpl/linked_lists_double.sgml new file mode 100644 index 00000000..63ae2cfb --- /dev/null +++ b/docs/reference/glib/tmpl/linked_lists_double.sgml @@ -0,0 +1,406 @@ + +Doubly-Linked Lists + + +linked lists containing integer values or pointers to data, with the ability +to iterate over the list in both directions. + + + +The #GList structure and its associated functions provide a standard +doubly-linked list data structure. + + +Each element in the list contains a piece of data, together with pointers +which link to the previous and next elements in the list. +Using these pointers it is possible to move through the list in both +directions (unlike the +Singly-Linked Lists +which only allows movement through the list in the forward direction). + + +The data contained in each element can be either integer values, by using one +of the +Type Conversion Macros, +or simply pointers to any type of data. + + +List elements are allocated in blocks using a #GListAllocator, which is +more efficient than allocating elements individually. + + +Note that most of the #GList functions expect to be passed a pointer to +the first element in the list. The functions which insert elements return +the new start of the list, which may have changed. + + +There is no function to create a #GList. NULL is considered to be the empty +list so you simply set a #GList* to NULL. + +To add elements, use g_list_append(), g_list_prepend(), g_list_insert() +and g_list_insert_sorted(). + + +To remove elements, use g_list_remove(). + + +To find elements in the list use g_list_first(), g_list_last(), g_list_next(), +g_list_previous(), g_list_nth(), g_list_nth_data(), g_list_find() and +g_list_find_custom(). + + +To find the index of an element use g_list_position() and g_list_index(). + + +To call a function for each element in the list use g_list_foreach(). + + +To free the entire list, use g_list_free(). + + + + + + + + + +The #GList struct is used for each element in a doubly-linked list. +The data field holds the element's data, which can +be a pointer to any kind of data, or any integer value using the +Type Conversion Macros. +The next and prev +pointers are the links to the next and previous elements in the list. + + +@data: +@next: +@prev: + + + +Adds a new element on to the end of the list. + + + +The return value is the new start of the list, which may have changed, so +make sure you store the new value. + + + + /* Notice that these are initialized to the empty list. */ + GList *list = NULL, *number_list = NULL; + + /* This is a list of strings. */ + list = g_list_append (list, "first"); + list = g_list_append (list, "second"); + + /* This is a list of integers. */ + number_list = g_list_append (number_list, GINT_TO_POINTER (27)); + number_list = g_list_append (number_list, GINT_TO_POINTER (14)); + + +@list: a pointer to a #GList. +@data: the data for the new element. +@Returns: the new start of the #GList. + + + + +Adds a new element on to the start of the list. + + + +The return value is the new start of the list, which may have changed, so +make sure you store the new value. + + + + /* Notice that it is initialized to the empty list. */ + GList *list = NULL; + list = g_list_prepend (list, "last"); + list = g_list_prepend (list, "first"); + + +@list: a pointer to a #GList. +@data: the data for the new element. +@Returns: the new start of the #GList. + + + + +Inserts a new element into the list at the given position. + + +@list: a pointer to a #GList. +@data: the data for the new element. +@position: the position to insert the element. If this is negative, or is +larger than the number of elements in the list, the new element is added on +to the end of the list. +@Returns: the new start of the #GList. + + + + +Inserts a new element into the list, using the given comparison function +to determine its position. + + +@list: a pointer to a #GList. +@data: the data for the new element. +@func: the function to compare elements in the list. It should return a +number > 0 if the first parameter comes after the second parameter in +the sort order. +@Returns: the new start of the #GList. + + + + +Removes an element from a #GList. +If two elements contain the same data, only the first is removed. +If none of the elements contain the data, the #GList is unchanged. + + +@list: a #GList. +@data: the data of the element to remove. +@Returns: the new start of the #GList. + + + + +Removes an element from a #GList, without freeing the element. +The removed element's prev and next links are set to NULL, so that it becomes a +self-contained list with one element. + + +@list: a #GList. +@llink: an element in the #GList. +@Returns: the new start of the #GList, without the element. + + + + +Frees all of the memory used by a #GList. +The freed elements are added to the #GListAllocator free list. + + + +If list elements contain dynamically-allocated memory, they should be freed +first. + + + +@list: + + + + +Allocates space for one #GList element. +It is called by g_list_append(), g_list_prepend(), g_list_insert() and +g_list_insert_sorted() and so is rarely used on its own. + + +@Returns: a pointer to the newly-allocated #GList element. + + + + +Frees one #GList element. +It is usually used after g_list_remove_link(). + + +@list: a #GList element. + + + + +Gets the number of elements in a #GList. + + +@list: a #GList. +@Returns: the number of elements in the #GList. + + + + + + + +@list: +@Returns: + + + + +Reverses a #GList. +It simply switches the next and prev pointers of each element. + + +@list: a #GList. +@Returns: the start of the reversed #GList. + + + + + + + +@list: +@compare_func: +@Returns: + + + + +Adds the second #GList onto the end of the first #GList. +Note that the elements of the second #GList are not copied. +They are used directly. + + +@list1: a #GList. +@list2: the #GList to add to the end of the first #GList. +@Returns: the start of the new #GList. + + + + +Calls a function for each element of a #GList. + + +@list: a #GList. +@func: the function to call with each element's data. +@user_data: user data to pass to the function. + + + + +Specifies the type of functions passed to g_list_foreach() and +g_slist_foreach(). + + +@data: the element's data. +@user_data: user data passed to g_list_foreach() or g_slist_foreach(). + + + + +Gets the first element in a #GList. + + +@list: a #GList. +@Returns: the first element in a #GList, or NULL if the #GList has no elements. + + + + +Gets the last element in a #GList. + + +@list: a #GList. +@Returns: the last element in the #GList, or NULL if the #GList has no +elements. + + + + +A convenience macro to gets the previous element in a #GList. + + +@list: an element in a #GList. +@Returns: the previous element, or NULL if there are no previous elements. + + + + +A convenience macro to gets the next element in a #GList. + + +@list: an element in a #GList. +@Returns: the next element, or NULL if there are no more elements. + + + + +Gets the element at the given position in a #GList. + + +@list: a #GList. +@n: the position of the element, counting from 0. +@Returns: the element, or NULL if the position is off the end of the #GList. + + + + +Gets the data of the element at the given position. + + +@list: a #GList. +@n: the position of the element. +@Returns: the element's data, or NULL if the position is off the end of the +#GList. + + + + +Finds the element in a #GList which contains the given data. + + +@list: a #GList. +@data: the element data to find. +@Returns: the found #GList element, or NULL if it is not found. + + + + +Finds an element in a #GList, using a supplied function to find the desired +element. +It iterates over the list, calling the given function which should return 0 +when the desired element is found. +The function takes two #gconstpointer arguments, the #GList element's data +and the given user data. + + +@list: a #GList. +@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 #GList element, or NULL if it is not found. + + + + +Gets the position of the given element in the #GList (starting from 0). + + +@list: a #GList. +@llink: an element in the #GList. +@Returns: the position of the element in the #GList, or -1 if the element is +not found. + + + + +Gets the position of the element containing the given data (starting from 0). + + +@list: a #GList. +@data: the data to find. +@Returns: the index of the element containing the data, or -1 if the data +is not found. + + + + + + + + + + + + + + +@allocator: + + diff --git a/docs/reference/glib/tmpl/linked_lists_single.sgml b/docs/reference/glib/tmpl/linked_lists_single.sgml new file mode 100644 index 00000000..68f7f015 --- /dev/null +++ b/docs/reference/glib/tmpl/linked_lists_single.sgml @@ -0,0 +1,370 @@ + +Singly-Linked Lists + + +linked lists containing integer values or pointers to data, limited to +iterating over the list in one direction. + + + +The #GSList structure and its associated functions provide a standard +singly-linked list data structure. + + +Each element in the list contains a piece of data, together with a pointer +which links to the next element in the list. +Using this pointer it is possible to move through the list in one +direction only (unlike the +Doubly-Linked Lists +which allow movement in both directions). + + +The data contained in each element can be either integer values, by using one +of the +Type Conversion Macros, +or simply pointers to any type of data. + + +List elements are allocated in blocks using a #GListAllocator, which is +more efficient than allocating elements individually. + + +Note that most of the #GSList functions expect to be passed a pointer to +the first element in the list. The functions which insert elements return +the new start of the list, which may have changed. + + +There is no function to create a #GSList. NULL is considered to be the empty +list so you simply set a #GSList* to NULL. + +To add elements, use g_slist_append(), g_slist_prepend(), g_slist_insert() +and g_slist_insert_sorted(). + + +To remove elements, use g_slist_remove(). + + +To find elements in the list use g_slist_last(), g_slist_next(), +g_slist_nth(), g_slist_nth_data(), g_slist_find() and +g_slist_find_custom(). + + +To find the index of an element use g_slist_position() and g_slist_index(). + + +To call a function for each element in the list use g_slist_foreach(). + + +To free the entire list, use g_slist_free(). + + + + + + + + + +The #GSList struct is used for each element in the singly-linked list. +The data field holds the element's data, which can +be a pointer to any kind of data, or any integer value using the +Type Conversion Macros. +The next field contains the link to the next +element in the list. + + +@data: +@next: + + + +Allocates space for one #GSList element. +It is called by the g_slist_append(), g_slist_prepend(), g_slist_insert() and +g_slist_insert_sorted() functions and so is rarely used on its own. + + +@Returns: a pointer to the newly-allocated #GSList element. + + + + +Adds a new element on to the end of the list. + + + +The return value is the new start of the list, which may have changed, so +make sure you store the new value. + + + + /* Notice that these are initialized to the empty list. */ + GSList *list = NULL, *number_list = NULL; + + /* This is a list of strings. */ + list = g_slist_append (list, "first"); + list = g_slist_append (list, "second"); + + /* This is a list of integers. */ + number_list = g_slist_append (number_list, GINT_TO_POINTER (27)); + number_list = g_slist_append (number_list, GINT_TO_POINTER (14)); + + +@list: a #GSList. +@data: the data for the new element. +@Returns: the new start of the #GSList. + + + + +Adds a new element on to the start of the list. + + + +The return value is the new start of the list, which may have changed, so +make sure you store the new value. + + + + /* Notice that it is initialized to the empty list. */ + GSList *list = NULL; + list = g_slist_prepend (list, "last"); + list = g_slist_prepend (list, "first"); + + +@list: a #GSList. +@data: the data for the new element. +@Returns: the new start of the #GSList. + + + + +Inserts a new element into the list at the given position. + + +@list: a #GSList. +@data: the data for the new element. +@position: the position to insert the element. If this is negative, or is +larger than the number of elements in the list, the new element is added on +to the end of the list. +@Returns: the new start of the #GSList. + + + + +Inserts a new element into the list, using the given comparison function +to determine its position. + + +@list: a #GSList. +@data: the data for the new element. +@func: the function to compare elements in the list. It should return a +number > 0 if the first parameter comes after the second parameter in +the sort order. +@Returns: the new start of the #GSList. + + + + +Removes an element from a #GSList. +If two elements contain the same data, only the first is removed. +If none of the elements contain the data, the #GSList is unchanged. + + +@list: a #GSList. +@data: the data of the element to remove. +@Returns: the new start of the #GSList. + + + + +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 +self-contained list with one element. + + +@list: a #GSList. +@llink: an element in the #GSList. +@Returns: the new start of the #GSList, without the element. + + + + +Frees all of the memory used by a #GSList. +The freed elements are added to the #GListAllocator free list. + + +@list: a #GSList. + + + + +Frees one #GSList element. +It is usually used after g_slist_remove_link(). + + +@list: a #GSList element. + + + + +Gets the number of elements in a #GSList. + + +@list: a #GSList. +@Returns: the number of elements in the #GSList. + + + + + + + +@list: +@Returns: + + + + +Reverses a #GSList. + + +@list: a #GSList. +@Returns: the start of the reversed #GSList. + + + + + + + +@list: +@compare_func: +@Returns: + + + + +Adds the second #GSList onto the end of the first #GSList. +Note that the elements of the second #GSList are not copied. +They are used directly. + + +@list1: a #GSList. +@list2: the #GSList to add to the end of the first #GSList. +@Returns: the start of the new #GSList. + + + + +Calls a function for each element of a #GSList. + + +@list: a #GSList. +@func: the function to call with each element's data. +@user_data: user data to pass to the function. + + + + +Gets the last element in a #GSList. + + +@list: a #GSList. +@Returns: the last element in the #GSList, or NULL if the #GSList has no +elements. + + + + +A convenience macro to gets the next element in a #GSList. + + +@slist: an element in a #GSList. +@Returns: the next element, or NULL if there are no more elements. + + + + +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. + + + + +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 +#GSList. + + + + +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. + + + + +Finds an element in a #GSList, using a supplied function to find the desired +element. +It iterates over the list, calling the given function which should return 0 +when the desired element is found. +The function takes two #gconstpointer arguments, the #GSList element's data +and the given user data. + + +@list: a #GSList. +@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. + + + + +Gets the position of the given element in the #GSList (starting from 0). + + +@list: a #GSList. +@llink: an element in the #GSList. +@Returns: the position of the element in the #GSList, or -1 if the element +is not found. + + + + +Gets the position of the element containing the given data (starting from 0). + + +@list: a #GSList. +@data: the data to find. +@Returns: the index of the element containing the data, or -1 if the data +is not found. + + + + + + + + + + + + + + +@allocator: + + diff --git a/docs/reference/glib/tmpl/macros.sgml b/docs/reference/glib/tmpl/macros.sgml new file mode 100644 index 00000000..e597270d --- /dev/null +++ b/docs/reference/glib/tmpl/macros.sgml @@ -0,0 +1,207 @@ + +Standard Macros + + +commonly-used macros. + + + +These macros provide a few commonly-used features. + + + + + + + + + +The major version number of the GLib library. + + + + + + +The minor version number of the GLib library. + + + + + + +The micro version number of the GLib library. + + + + + + +Checks the version of the GLib library. +It returns TRUE if the GLib library is the same or newer than the given +version. + + +Checking the version of the GLib library. + + if (!GLIB_CHECK_VERSION (1, 2, 0)) + g_error ("GLib version 1.2.0 or above is needed"); + + + + +@major: the major version number. +@minor: the minor version number. +@micro: the micro version number. + + + + +The directory separator character. +This is '/' on Unix machines and '\' under Windows. + + + + + + +The directory separator as a string. +This is "/" on Unix machines and "\" under Windows. + + + + + + +The search path separator character. +This is ':' on Unix machines and ';' under Windows. + + + + + + +The search path separator as a string. +This is ":" on Unix machines and ";" under Windows. + + + + + + +Defines the TRUE value for the #gboolean type. + + + + + + +Defines the FALSE value for the #gboolean type. + + + + + + +Defines the standard NULL pointer. + + + + + + +Calculates the minimum of @a and @b. + + +@a: a numeric value. +@b: a numeric value. +@Returns: the minimum of @a and @b. + + + + +Calculates the maximum of @a and @b. + + +@a: a numeric value. +@b: a numeric value. +@Returns: the maximum of @a and @b. + + + + +Calculates the absolute value of @a. +The absolute value is simply the number with any negative sign taken away. + + +For example, + + +ABS(-10) is 10. + + +ABS(10) is also 10. + + + + +@a: a numeric value. +@Returns: the absolute value of @a. + + + + +Ensures that @x is between the limits set by @low and @high. + + +For example, + + +CLAMP(5, 10, 15) is 10. + + +CLAMP(15, 5, 10) is 10. + + +CLAMP(20, 15, 25) is 20. + + + + +@x: the value to clamp. +@low: the minimum value allowed. +@high: the maximum value allowed. +@Returns: the value of @x clamped to the range between @low and @high. + + + + +Returns a member of a structure at a given offset, using the given type. + + +@member_type: the type of the struct field. +@struct_p: a pointer to a struct. +@struct_offset: the offset of the field from the start of the struct, in bytes. +@Returns: the struct member. + + + + +Returns an untyped pointer to a given offset of a struct. + + +@struct_p: a pointer to a struct. +@struct_offset: the offset from the start of the struct, in bytes. +@Returns: an untyped pointer to @struct_p plus @struct_offset bytes. + + + + +Returns the offset, in bytes, of a member of a struct. + + +@struct_type: a structure type, e.g. GtkWidget. +@member: a field in the structure, e.g. window. +@Returns: the offset of @member from the start of @struct_type. + + diff --git a/docs/reference/glib/tmpl/macros_misc.sgml b/docs/reference/glib/tmpl/macros_misc.sgml new file mode 100644 index 00000000..cfae430f --- /dev/null +++ b/docs/reference/glib/tmpl/macros_misc.sgml @@ -0,0 +1,158 @@ + +Miscellaneous Macros + + +specialised macros which are not used often. + + + +These macros provide more specialized features which are not needed so often +by application programmers. + + + + + + + + + +Used to declare inline functions. If inline functions are not supported on +the particular platform, the macro evaluates to the empty string. + + + + + + +Used within multi-statement macros so that they can be used in places where +only one statement is expected by the compiler. + + + + + + +Used within multi-statement macros so that they can be used in places where +only one statement is expected by the compiler. + + + + + + +Portable way to copy va_list variables. + + +@ap1: the va_list variable to place a copy of @ap2 in. +@ap2: a va_list. + + + + +Expands to "__extension__" when GNU C is used as the compiler. +This simply tells GNU C not to warn about the following non-standard code +when compiling with the -pedantic option. + + + + + + +Expands to the GNU C const function attribute if the compiler is GNU C. +This enables optimization of the function. +See the GNU C documentation for details. + + + + + + +Expands to the GNU C noreturn function attribute if the compiler is GNU C. +It is used for declaring functions which never return. +It enables optimization of the function, and avoids possible compiler +warnings. See the GNU C documentation for details. + + + + + + +Expands to the GNU C unused function attribute if the compiler is GNU C. +It is used for declaring functions which may never be used. +It avoids possible compiler warnings. See the GNU C documentation for details. + + + + + + +Expands to the GNU C format function attribute if the compiler is GNU C. +This is used for declaring functions which take a variable number of +arguments, with the same syntax as printf(). +It allows the compiler to type-check the arguments passed to the function. +See the GNU C documentation for details. + + +@format_idx: the index of the argument corresponding to the format string. +(The arguments are numbered from 1). +@arg_idx: the index of the first of the format arguments. + + + + +Expands to the GNU C format function attribute if the compiler is GNU C. +This is used for declaring functions which take a variable number of +arguments, with the same syntax as scanf(). +It allows the compiler to type-check the arguments passed to the function. +See the GNU C documentation for details. + + +@format_idx: the index of the argument corresponding to the format string. +(The arguments are numbered from 1). +@arg_idx: the index of the first of the format arguments. + + + + +Expands to the GNU C format_arg function attribute if the compiler is GNU C. +This is used for declaring functions which take a variable number of +parameters, like printf() and +scanf(). See the GNU C documentation for details. + +FIXME: I can't find this in my GNU C documentation. Take out? + + +@arg_idx: the index of the argument. + + + + +Expands to the GNU C __FUNCTION__ variable if the compiler is GNU C, +or "" if it isn't. +The GNU C __FUNCTION__ variable contains the name of the current function. +See the GNU C documentation for details. + + + + + + +Expands to the GNU C __PRETTY_FUNCTION__ variable if the compiler is GNU C, +or "" if it isn't. +The GNU C __PRETTY_FUNCTION__ variable contains the name of the current +function. For a C program this is the same as the __FUNCTION__ variable +but for C++ it also includes extra information such as the class +and function prototype. See the GNU C documentation for details. + + + + + + +Turns the argument into a string literal by using the '#' stringizing operator. + + +@x: text to convert to a literal string. + + diff --git a/docs/reference/glib/tmpl/main.sgml b/docs/reference/glib/tmpl/main.sgml new file mode 100644 index 00000000..d3773954 --- /dev/null +++ b/docs/reference/glib/tmpl/main.sgml @@ -0,0 +1,496 @@ + +The Main Event Loop + + +manages all available sources of events. + + + +The main event loop manages all the available sources of events for GLib +and GTK+ applications. These events can come from any number of different +types of sources such as file descriptors (plain files, pipes or sockets) +and timeouts. +New types of event sources can also be added using g_source_add(). + + +Each event source is assigned a priority. +The default priority, #G_PRIORITY_DEFAULT, is 0. +Values less than 0 denote higher priorities. +Values greater than 0 denote lower priorities. +Events from high priority sources +are always processed before events from lower priority sources. + + +Idle functions can also be added, and assigned a priority. These will be +run whenever no events with a higher priority are ready to be processed. + + +The #GMainLoop data type represents a main event loop. +A #GMainLoop is created with g_main_new(). After adding the initial event +sources, g_main_run() is called. This continuously checks for new events +from each of the event sources and dispatches them. +Finally, the processing of an event from one of the sources leads to a call +to g_main_quit() to exit the main loop, and g_main_run() returns. + + +It is possible to create new instances of #GMainLoop recursively. +This is often used in GTK+ applications when showing modal dialog boxes. +However, all event sources are global; they are not tied to a particular +#GMainLoop. + + +GTK+ contains wrappers of many of these functions, +e.g. gtk_main(), gtk_main_quit(), gtk_events_pending(), gtk_idle_add(), +gtk_timeout_add() and gtk_input_add_full(). +In a GTK+ application, these wrapper functions should be used instead. + + + + + + + + + +The #GMainLoop struct is an opaque data type representing the main event loop +of a GLib or GTK+ application. + + + + + +Creates a new #GMainLoop. + + +@is_running: set to TRUE to indicate that the loop is running. This is not +very important since calling g_main_run() will set this to TRUE anyway. +@Returns: a new #GMainLoop. + + + + +Frees the memory allocated for the #GMainLoop. + + +@loop: a #GMainLoop. + + + + +Runs a main loop until it stops running, which occurs when g_main_quit() +is called. + + +@loop: a #GMainLoop. + + + + +Returns TRUE if the main loop is running. + + +@loop: a #GMainLoop. +@Returns: TRUE if the main loop is running. + + + + +Returns TRUE if any events are pending (i.e. ready to be processed). + + +@Returns: TRUE if any events are pending. + + + + +Runs a single iteration of the main loop. +This will check which event sources are ready to be processed, and will +process the highest priority event sources which are ready. + + +@may_block: set to TRUE if it should block (i.e. wait) until an event source +becomes ready. It will return after an event source has been processed. +If set to FALSE it will return immediately if no event source is ready to be +processed. +@Returns: TRUE if more events are pending. + + + + +Stops the #GMainLoop. If g_main_run() was called to run the #GMainLoop, +it will now return. + + +@loop: a #GMainLoop. + + + + +Use this for high priority event sources. +It is not used within GLib or GTK+. + + + + + + +Use this for default priority event sources. +In GLib this priority is used when adding timeout functions with +g_timeout_add(). +In GDK this priority is used for events from the X Windows server. + + + + + + +Use this for high priority idle functions. +GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations, and +#G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is done to +ensure that any pending resizes are processed before any pending redraws, +so that widgets are not redrawn twice unnecessarily.) + + + + + + +Use this for default priority idle functions. +In GLib this priority is used when adding idle functions with g_idle_add(). + + + + + + +Use this for very low priority background tasks. +It is not used within GLib or GTK+. + + + + + + +Sets a function to be called at regular intervals, with the default priority, +#G_PRIORITY_DEFAULT. +The function is called repeatedly until it returns FALSE, at which point +the timeout is automatically destroyed and the function will not be called +again. +The first call to the function will be at the end of the first @interval. + + +Note that timeout functions may be delayed, due to the processing of other +event sources. Thus they should not be relied on for precise timing. +After each call to the timeout function, the time of the next +timeout is recalculated based on the current time and the given interval +(it does not try to 'catch up' time lost in delays). + + +@interval: the time between calls to @function, in milliseconds (1/1000ths +of a second.) +@function: the function to call at each interval. +@data: data to pass to @function. +@Returns: the id of the event source. + + + + +Sets a function to be called at regular intervals, with the given priority. +The function is called repeatedly until it returns FALSE, at which point +the timeout is automatically destroyed and the function will not be called +again. +The @notify function is called when the timeout is destroyed. +The first call to the function will be at the end of the first @interval. + + +Note that timeout functions may be delayed, due to the processing of other +event sources. Thus they should not be relied on for precise timing. +After each call to the timeout function, the time of the next +timeout is recalculated based on the current time and the given interval +(it does not try to 'catch up' time lost in delays). + + +@priority: the priority of the function. See #G_PRIORITY_DEFAULT, +#G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH, #G_PRIORITY_HIGH_IDLE, and +#G_PRIORITY_LOW. +@interval: the time between calls to the function, in milliseconds (1/1000ths +of a second.) +@function: the function to call at each interval. +@data: data to pass to @function (and @notify). +@notify: the function to call when the timeout is destroyed, or NULL. +@Returns: the id of event source. + + + + +Specifies the type of function passed to g_timeout_add(), g_timeout_add_full(), +g_idle_add(), and g_idle_add_full(). + + +@data: data passed to the function, set when the source was created with one +of the above functions. +@Returns: it should return FALSE if the source should be removed. + + + + +Adds a function to be called whenever there are no higher priority events +pending. The function is given the default idle priority, +#G_PRIORITY_DEFAULT_IDLE. +If the function returns FALSE it is automatically removed from the list of +event sources and will not be called again. + + +@function: the function to call. +@data: data to pass to the function. +@Returns: the id of the event source. + + + + +Adds a function to be called whenever there are no higher priority events +pending. +If the function returns FALSE it is automatically removed from the list of +event sources and will not be called again. + + +@priority: the priority of the idle function, which should be somewhere around +#G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. +@function: the function to call. +@data: data to pass to the function. +@destroy: the function to call when the timeout is destroyed, or NULL. +@Returns: the id of the event source. + + + + +Removes the idle function with the given data. + + +@data: the data which is passed to the idle function. +@Returns: TRUE if the idle function was found. + + + + +Adds a file descriptor to be polled. +This is usually combined with g_source_add() to add an event source. +The event source's check function will typically test the revents +field in the #GPollFD struct and return TRUE if events need to be processed. + + +@fd: a #GPollFD, which is a file descriptor together with a bitwise +combination of #GIOCondition flags determining which events to poll for. +@priority: the priority of the poll, which should be the same as the priority +used for g_source_add() to ensure that the file descriptor is polled whenever +the results may be needed. +See #G_PRIORITY_DEFAULT, #G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH, +#G_PRIORITY_HIGH_IDLE, and #G_PRIORITY_LOW. + + + + + + + + + + +#gint fd; +the file descriptor to poll (or a HANDLE on Win32 platforms). + + + +#gushort events; +a bitwise combination of flags from #GIOCondition, specifying which +events should be polled for. Typically for reading from a file descriptor +you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use +%G_IO_OUT | %G_IO_ERR. + + + + +#gushort revents; +a bitwise combination of flags from #GIOCondition, returned from the +poll() function to indicate which events occurred. + + + + + + +@fd: +@events: +@revents: + + + +Removes a file descriptor from the list being polled. + + +@fd: the #GPollFD to remove. + + + + +Sets the function to use to handle polling of file descriptors. +It will be used instead of the poll() system call +(or GLib's replacement function, which is used where +poll() isn't available). + + +This function could possibly be used to integrate the GLib event loop +with an external event loop. + + +@func: the function to call to poll all file descriptors. + + + + +Specifies the type of function passed to g_main_set_poll_func(). +The semantics of the function should match those of the +poll() system call. + + +@ufds: an array of #GPollFD elements. +@nfsd: the number of elements in @ufds. +@timeout: the maximum time to wait for an event of the file descriptors. +@Returns: the number of #GPollFD elements which have events or errors reported, +or -1 if an error occurred. + + + + +Adds a source to the main loop. + + +@priority: the priority of the function. See #G_PRIORITY_DEFAULT, +#G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH, #G_PRIORITY_HIGH_IDLE, and +#G_PRIORITY_LOW. +@can_recurse: if it is safe to call the source functions recursively. +@funcs: the functions to handle the source. +@source_data: data specific to the type of event source. +@user_data: user data which will be passed to the user function handling the +source. +@notify: the function to call when the source is destroyed. +@Returns: the id of the event source. + + + + +The #GSourceFuncs struct contains a table of functions used to handle +event sources in a generic manner. + + + + + + +prepare + +Called before all the file descriptors are polled. +If the source can determine that it is ready here (without waiting for the +results of the poll() call) it should return TRUE. +It can also return a @timeout value which should be the maximum timeout +(in milliseconds) which should be passed to the poll() call. +The actual timeout used will be -1 if all sources returned -1, or it will +be the minimum of all the @timeout values returned which were >= 0. + + + + +check + +Called after all the file descriptors are polled. +The source should return TRUE if it is ready to be processed. +Note that some time may have passed since the previous prepare function was +called, so the source should be checked again here. + + + + +dispatch + +Called to process the event source, after it has returned TRUE in either +its @prepare or its @check function. + + + + +destroy + +Called when the source is destroyed. It will be called with the user data +parameter passed to the g_source_add() and related functions. + + + + + +For idle sources, the prepare and check functions always return TRUE to +indicate that the source is always ready to be processed. +The prepare function also returns a timeout value of 0 to ensure that the +poll() call doesn't block (since that would be time wasted which could have +been spent running the idle function). + + +For timeout sources, the prepare and check functions both return TRUE if the +timeout interval has expired. +The prepare function also returns a timeout value to ensure that the poll() +call doesn't block too long and miss the next timeout. + + +For file descriptor sources, the prepare function typically returns FALSE, +since it must wait until poll() has been called before it knows whether any +events need to be processed. It sets the returned timeout to -1 to indicate +that it doesn't mind how long the poll() call blocks. +In the check function, it tests the results of the poll() call to see if +the required condition has been met, and returns TRUE if so. + + +@prepare: +@check: +@dispatch: +@destroy: + + + +Removes the event source with the given id. +The id is returned when the source is created, either directly with +g_source_add(), or indirectly with g_idle_add(), g_idle_add_full(), +g_timeout_add() and g_timeout_add_full(). + + +@tag: the id of the event source to remove. +@Returns: TRUE if the source was found. + + + + +Removes the event source with the given #GSourceFuncs and user data. + + +@funcs: the #GSourceFuncs of the source to remove. +@user_data: the user data of the source to remove. +@Returns: TRUE if the source was found. + + + + +Removes the event source with the given source data. + + +@source_data: the source data, which contains information specific to the +type of source. +@Returns: TRUE if the source was found. + + + + +Removes the event source with the given user data. + + +@user_data: the user data of the source to remove. +@Returns: TRUE if the source was found. + + diff --git a/docs/reference/glib/tmpl/memory.sgml b/docs/reference/glib/tmpl/memory.sgml new file mode 100644 index 00000000..4a6e1b43 --- /dev/null +++ b/docs/reference/glib/tmpl/memory.sgml @@ -0,0 +1,156 @@ + +Memory Allocation + + +general memory-handling. + + + +These functions provide support for allocating and freeing memory. + + + +If any call to allocate memory fails, the application is terminated. +This also means that there is no need to check if the call succeeded. + + + + + + + + + + +Allocates @count elements of type @type. +The returned pointer is cast to a pointer to the given type. +If @count is 0 it returns NULL. + + +@type: the type of the elements to allocate. +@count: the number of elements to allocate. +@Returns: a pointer to the allocated memory, cast to a pointer to @type. + + + + +Allocates @count elements of type @type, initialized to 0's. +The returned pointer is cast to a pointer to the given type. +If @count is 0 it returns NULL. + + +@type: the type of the elements to allocate. +@count: the number of elements to allocate. +@Returns: a pointer to the allocated memory, cast to a pointer to @type. + + + + +Reallocates the memory pointed to by @mem, so that it now has space for +@count elements of type @type. It returns the new address of the memory, +which may have been moved. + + +@type: the type of the elements to allocate. +@mem: the currently allocated memory. +@count: the number of elements to allocate. +@Returns: a pointer to the new allocated memory, cast to a pointer to @type. + + + + +Allocates @size bytes of memory. +If @size is 0 it returns NULL. + + +@size: the number of bytes to allocate. +@Returns: a pointer to the allocated memory. + + + + +Allocates @size bytes of memory, initialized to 0's. +If @size is 0 it returns NULL. + + +@size: the number of bytes to allocate. +@Returns: a pointer to the allocated memory. + + + + +Reallocates the memory pointed to by @mem, so that it now has space for +@size bytes of memory. It returns the new address of the memory, which may +have been moved. + + +@mem: the memory to reallocate. +@size: the new size of the allocated memory, in bytes. +@Returns: the new address of the allocated memory. + + + + +Frees the memory pointed to by @mem. +If @mem is NULL it simply returns. + + +@mem: the memory to free. + + + + +Copies a block of memory @n bytes long, from @s to @d. +The source and destination areas may overlap. + + + +On architectures where memmove() is not available, this function is implemented +using bcopy(), which may not be able to handle overlapping areas. + + + +@d: the destination address to copy the bytes to. +@s: the source address to copy the bytes from. +@n: the number of bytes to copy. + + + + +Allocates @byte_size bytes of memory, and copies @byte_size bytes into it +from @mem. If @mem is NULL it returns NULL. + + +@mem: the memory to copy. +@byte_size: the number of bytes to copy. +@Returns: a pointer to the newly allocated copy of the memory, or NULL if @mem +is NULL. + + + + +Outputs a summary of memory usage. +To use this function you must configure glib with the flag +'--enable-mem-profile=yes' before compiling. + + +It outputs the frequency of allocations of different sizes, +the total number of bytes which have been allocated, +the total number of bytes which have been freed, +and the difference between the previous two values, i.e. the number of bytes +still in use. + + + + + + +Checks if the given memory has already been freed. If it has it outputs +a warning message. +To use this function you must configure glib with the flag +'--enable-mem-check=yes' before compiling. + + +@mem: the memory to check. + + diff --git a/docs/reference/glib/tmpl/memory_chunks.sgml b/docs/reference/glib/tmpl/memory_chunks.sgml new file mode 100644 index 00000000..2f33963b --- /dev/null +++ b/docs/reference/glib/tmpl/memory_chunks.sgml @@ -0,0 +1,303 @@ + +Memory Chunks + + +efficient way to allocate groups of equal-sized chunks of memory. + + + +Memory chunks provide an efficient way to allocate equal-sized pieces of +memory, called atoms. They are used extensively within GLib itself. +For example, the +Doubly Linked Lists +use memory chunks to allocate space for elements of the lists. + + +There are two types of memory chunks, #G_ALLOC_ONLY, and #G_ALLOC_AND_FREE. + + +#G_ALLOC_ONLY chunks only allow allocation of atoms. The atoms can never +be freed individually. The memory chunk can only be free in its entirety. + + +#G_ALLOC_AND_FREE chunks do allow atoms to be freed individually. +The disadvantage of this is that the memory chunk has to keep track of which +atoms have been freed. This results in more memory being used and a slight +degradation in performance. + + + + + +To create a memory chunk use g_mem_chunk_new() or the convenience macro +g_mem_chunk_create(). + + +To allocate a new atom use g_mem_chunk_alloc(), g_mem_chunk_alloc0(), +or the convenience macros g_chunk_new() or g_chunk_new0(). + + +To free an atom use g_mem_chunk_free(), or the convenience macro +g_chunk_free(). (Atoms can only be freed if the memory chunk is created +with the type set to #G_ALLOC_AND_FREE.) + + +To free any blocks of memory which are no longer being used, use +g_mem_chunk_clean(). To clean all memory chunks, use g_blow_chunks(). + + +To reset the memory chunk, freeing all of the atoms, use g_mem_chunk_reset(). + + +To destroy a memory chunk, use g_mem_chunk_destroy(). + + +To help debug memory chunks, use g_mem_chunk_info() and g_mem_chunk_print(). + + + +Using a GMemChunk. + + GMemChunk *mem_chunk; + gchar *mem[10000]; + gint i; + + /* Create a GMemChunk with atoms 50 bytes long, and memory blocks holding + 100 bytes. Note that this means that only 2 atoms fit into each memory + block and so isn't very efficient. */ + mem_chunk = g_mem_chunk_new ("test mem chunk", 50, 100, G_ALLOC_AND_FREE); + + /* Now allocate 10000 atoms. */ + for (i = 0; i < 10000; i++) + { + mem[i] = g_chunk_new (gchar, mem_chunk); + + /* Fill in the atom memory with some junk. */ + for (j = 0; j < 50; j++) + mem[i][j] = i * j; + } + + /* Now free all of the atoms. Note that since we are going to destroy the + GMemChunk, this wouldn't normally be used. */ + for (i = 0; i < 10000; i++) + { + g_mem_chunk_free (mem_chunk, mem[i]); + } + + /* We are finished with the GMemChunk, so we destroy it. */ + g_mem_chunk_destroy (mem_chunk); + + + +Using a GMemChunk with data structures. + + GMemChunk *array_mem_chunk; + GRealArray *array; + + /* Create a GMemChunk to hold GRealArray structures, using the + g_mem_chunk_create() convenience macro. We want 1024 atoms in each + memory block, and we want to be able to free individual atoms. */ + array_mem_chunk = g_mem_chunk_create (GRealArray, 1024, G_ALLOC_AND_FREE); + + /* Allocate one atom, using the g_chunk_new() convenience macro. */ + array = g_chunk_new (GRealArray, array_mem_chunk); + + /* We can now use array just like a normal pointer to a structure. */ + array->data = NULL; + array->len = 0; + array->alloc = 0; + array->zero_terminated = (zero_terminated ? 1 : 0); + array->clear = (clear ? 1 : 0); + array->elt_size = elt_size; + + /* We can free the element, so it can be reused. */ + g_chunk_free (array, array_mem_chunk); + + /* We destroy the GMemChunk when we are finished with it. */ + g_mem_chunk_destroy (array_mem_chunk); + + + + + + + + + +The #GMemChunk struct is an opaque data structure representing a memory +chunk. It should be accessed only through the use of the following functions. + + + + + +Specifies the type of a #GMemChunk. +Used in g_mem_chunk_new() and g_mem_chunk_create() to specify that atoms +will be freed individually. + + + + + + +Specifies the type of a #GMemChunk. +Used in g_mem_chunk_new() and g_mem_chunk_create() to specify that atoms +will never be freed individually. + + + + + + +Creates a new #GMemChunk. + + +@name: a string to identify the #GMemChunk. It is not copied so it +should be valid for the lifetime of the #GMemChunk. It is only used in +g_mem_chunk_print(), which is used for debugging. +@atom_size: the size, in bytes, of each element in the #GMemChunk. +@area_size: the size, in bytes, of each block of memory allocated to contain +the atoms. +@type: the type of the #GMemChunk. +#G_ALLOC_AND_FREE is used if the atoms will be freed individually. +#G_ALLOC_ONLY should be used if atoms will never be freed individually. +#G_ALLOC_ONLY is quicker, since it does not need to track free atoms, +but it obviously wastes memory if you no longer need many of the atoms. +@Returns: the new #GMemChunk. + + + + +Allocates an atom of memory from a #GMemChunk. + + +@mem_chunk: a #GMemChunk. +@Returns: a pointer to the allocated atom. + + + + +Allocates an atom of memory from a #GMemChunk, setting the memory to 0. + + +@mem_chunk: a #GMemChunk. +@Returns: a pointer to the allocated atom. + + + + +Frees an atom in a #GMemChunk. +This should only be called if the #GMemChunk was created with +#G_ALLOC_AND_FREE. Otherwise it will simply return. + + +@mem_chunk: a #GMemChunk. +@mem: a pointer to the atom to free. + + + + +Frees all of the memory allocated for a #GMemChunk. + + +@mem_chunk: a #GMemChunk. + + + + +A convenience macro for creating a new #GMemChunk. +It calls g_mem_chunk_new(), using the given type to create the #GMemChunk +name. The atom size is determined using sizeof(), and the +area size is calculated by multiplying the @pre_alloc parameter with +the atom size. + + +@type: the type of the atoms, typically a structure name. +@pre_alloc: the number of atoms to store in each block of memory. +@alloc_type: the type of the #GMemChunk. +#G_ALLOC_AND_FREE is used if the atoms will be freed individually. +#G_ALLOC_ONLY should be used if atoms will never be freed individually. +#G_ALLOC_ONLY is quicker, since it does not need to track free atoms, +but it obviously wastes memory if you no longer need many of the atoms. +@Returns: the new #GMemChunk. + + + + +A convenience macro to allocate an atom of memory from a #GMemChunk. +It calls g_mem_chunk_alloc() and casts the returned atom to a pointer to +the given type, avoiding a type cast in the source code. + + +@type: the type of the #GMemChunk atoms, typically a structure name. +@chunk: a #GMemChunk. +@Returns: a pointer to the allocated atom, cast to a pointer to @type. + + + + +A convenience macro to allocate an atom of memory from a #GMemChunk. +It calls g_mem_chunk_alloc0() and casts the returned atom to a pointer to +the given type, avoiding a type cast in the source code. + + +@type: the type of the #GMemChunk atoms, typically a structure name. +@chunk: a #GMemChunk. +@Returns: a pointer to the allocated atom, cast to a pointer to @type. + + + + +A convenience macro to free an atom of memory from a #GMemChunk. +It simply switches the arguments and calls g_mem_chunk_free() +It is included simply to complement the other convenience macros, g_chunk_new() +and g_chunk_new0(). + + +@mem: a pointer to the atom to be freed. +@mem_chunk: a #GMemChunk. + + + + +Resets a GMemChunk to its initial state. +It frees all of the currently allocated blocks of memory. + + +@mem_chunk: a #GMemChunk. + + + + +Frees any blocks in a #GMemChunk which are no longer being used. + + +@mem_chunk: a #GMemChunk. + + + + +Calls g_mem_chunk_clean() on all #GMemChunk objects. + + + + + + +Outputs debugging information for all #GMemChunk objects currently in use. +It outputs the number of #GMemChunk objects currently allocated, +and calls g_mem_chunk_print() to output information on each one. + + + + + + +Outputs debugging information for a #GMemChunk. +It outputs the name of the #GMemChunk (set with g_mem_chunk_new()), +the number of bytes used, and the number of blocks of memory allocated. + + +@mem_chunk: a #GMemChunk. + + diff --git a/docs/reference/glib/tmpl/messages.sgml b/docs/reference/glib/tmpl/messages.sgml new file mode 100644 index 00000000..536b8e36 --- /dev/null +++ b/docs/reference/glib/tmpl/messages.sgml @@ -0,0 +1,262 @@ + +Message Logging + + +versatile support for logging messages with different levels of importance. + + + +These functions provide support for logging error messages or messages +used for debugging. + + + +There are several built-in levels of messages, defined in #GLogLevelFlags. +These can be extended with user-defined levels. + + + + + + + + + +Defines the log domain. +For applications, this is typically left as the default NULL (or "") domain. +Libraries should define this so that any messages which they log can +be differentiated from messages from other libraries and application code. +But be careful not to define it in any public header files. + + +For example, GTK uses this in its Makefile.am: + +INCLUDES = \ + -DG_LOG_DOMAIN=\"Gtk\" + + + + + + + + + + + + + + + + + + + +GLib log levels that are considered fatal by default. + + + + + + +Log level shift offset for user defined log levels (0-7 are used by GLib). + + + + + + +Specifies the prototype of log handler functions. + + +@log_domain: the log domain of the message. +@log_level: the log level of the message. +@message: the message to process. +@user_data: user data, set in g_log_set_handler(). + + + + +Flags specifying the level of log messages. + + +@G_LOG_FLAG_RECURSION: +@G_LOG_FLAG_FATAL: +@G_LOG_LEVEL_ERROR: +@G_LOG_LEVEL_CRITICAL: +@G_LOG_LEVEL_WARNING: +@G_LOG_LEVEL_MESSAGE: +@G_LOG_LEVEL_INFO: +@G_LOG_LEVEL_DEBUG: +@G_LOG_LEVEL_MASK: + + + +Logs an error or debugging message. +If the log level has been set as fatal, the abort() +function is called to terminate the program. + + +@log_domain: the log domain, usually #G_LOG_DOMAIN. +@log_level: the log level, either from #GLogLevelFlags or a user-defined level. +@format: the message format. See the printf() +documentation. +@Varargs: the parameters to insert into the format string. + + + + +Logs an error or debugging message. +If the log level has been set as fatal, the abort() +function is called to terminate the program. + + +@log_domain: the log domain. +@log_level: the log level. +@format: the message format. See the printf() +documentation. +@args: the parameters to insert into the format string. + + + + +A convenience function/macro to log a normal message. + + +@format: the message format. See the printf() +documentation. +@args...: the parameters to insert into the format string. + + + + +A convenience function/macro to log a warning message. + + +@format: the message format. See the printf() +documentation. +@args...: the parameters to insert into the format string. + + + + +A convenience function/macro to log an error message. +Error messages are always fatal, resulting in a call to +abort() to terminate the application. + + +@format: the message format. See the printf() +documentation. +@args...: the parameters to insert into the format string. + + + + +Sets the log handler for a domain and set of log levels. + + +@log_domain: the log domain, or NULL for the default "" application domain. +@log_levels: the levels to apply the log handler. +@log_func: the log handler function. +@user_data: data passed to the log handler. +@Returns: the id of the new handler. + + + + +Removes the log handler. + + +@log_domain: the log domain. +@handler_id: the id of the handler, which was returned in g_log_set_handler(). + + + + +Sets the message levels which are always fatal, in any log domain. +When a message with any of these levels is logged the program terminates. +You can only set the levels defined by GLib to be fatal. +%G_LOG_LEVEL_ERROR is always fatal. + + +@fatal_mask: the mask containing bits set for each level of error which is +to be fatal. +@Returns: the old fatal mask. + + + + +Sets the log levels which are fatal in the given domain. +%G_LOG_LEVEL_ERROR is always fatal. + + +@log_domain: the log domain. +@fatal_mask: the new fatal mask. +@Returns: the old fatal mask for the log domain. + + + + +The default log handler. +This is used if no log handler has been set for the particular log domain +and log level combination. It outputs the message to stderr or stdout +and if the log level is fatal it calls abort(). + + +stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL, and +%G_LOG_LEVEL_WARNING. stdout is used for the rest. +(On the Windows platform, stdout is always used.) + + +@log_domain: the log domain of the message. +@log_level: the level of the message. +@message: the message. +@unused_data: data passed from g_log which is unused. + + + + +Sets the function to be called to handle error messages. +This function is deprecated in favour of the new logging facilities. + + +@func: the function to be called to handle error messages. +@Returns: the old error handler. + + + + +Specifies the type of function passed to g_set_error_handler(). + + +@str: the error message. + + + + +Sets the function to be called to handle warning messages. +This function is deprecated in favour of the new logging facilities. + + +@func: the function to be called to handle warning messages. +@Returns: the old warning handler. + + + + +Specifies the type of function passed to g_set_warning_handler(). + + +@str: the warning message. + + + + +Sets the function to be called to handle messages. +This function is deprecated in favour of the new logging facilities. + + +@func: the function to be called to handle normal messages. +@Returns: the old message handler. + + diff --git a/docs/reference/glib/tmpl/misc_utils.sgml b/docs/reference/glib/tmpl/misc_utils.sgml new file mode 100644 index 00000000..bc039510 --- /dev/null +++ b/docs/reference/glib/tmpl/misc_utils.sgml @@ -0,0 +1,226 @@ + +Miscellaneous Utility Functions + + +a selection of portable utility functions. + + + +These are portable utility functions. + + + + + + + + +Gets the name of the program. +(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].) + + +@Returns: the name of the program. + + + + +Sets the name of the program. + + +@prgname: the name of the program. + + + + +Returns an environment variable. +On windows systems the returned value is only valid until the next call to +g_getenv(). + + +@variable: the environment variable to get. +@Returns: the value of the environment variable, or NULL if the environment +variable is not found. + + + + +Gets the user name of the current user. + + +@Returns: the user name of the current user. + + + + +Gets the real name of the user. This comes from the user's entry in the +passwd file. + + +@Returns: the user's real name. + + + + +Gets the current user's home directory. + + +@Returns: the current user's home directory. + + + + +Gets the directory to use for temporary files. +This is found from inspecting the environment variables TMPDIR, TMP, and TEMP +in that order. If none of those are defined "/tmp" is returned. + + +@Returns: the directory to use for temporary files. + + + + +Gets the current directory. +The returned string should be freed when no longer needed. + + +@Returns: the current directory. + + + + +Gets the name of the file without any leading directory components. +It returns a pointer into the given file name string. + + +@file_name: the name of the file. +@Returns: the name of the file without any leading directory components. + + + + +Gets the directory components of a file name. +If the file name has no directory components "." is returned. +The returned string should be freed when no longer needed. + + +@file_name: the name of the file. +@Returns: the directory components of the file. + + + + +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. + + +@file_name: a file name. +@Returns: TRUE if @file_name is an absolute path. + + + + +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. + + +@file_name: a file name. +@Returns: a pointer into @file_name after the root component. + + + + +FIXME: I don't know what this does! + + +@mask: +@nth_bit: +@Returns: + + + + +FIXME: I don't know what this does! + + +@mask: +@nth_bit: +@Returns: + + + + +Gets the number of bits used to hold @number, +e.g. if @number is 4, 3 bits are needed. + + +@number: a guint. +@Returns: the number of bits used to hold @number. + + + + +Gets the smallest prime number from a built-in array of primes which +is larger than @num. This is used within GLib to calculate the optimum +size of a #GHashTable. + + +The built-in array of primes ranges from 11 to 13845163 such that +each prime is approximately 1.5-2 times the previous prime. + + +@num: a guint. +@Returns: the smallest prime number from a built-in array of primes which is +larger than @num. + + + + +Specifies a function to be called at normal program termination. + + +@func: the function to call on normal program termination. + + + + +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 +command line or through environment variables. + + +@string: a list of debug options separated by ':' or "all" to set all flags. +@keys: pointer to an array of #GDebugKey which associate strings with +bit flags. +@nkeys: the number of #GDebugKey in the array. +@Returns: the combined set of bit flags. + + + + +Associates a string with a bit flag. +Used in g_parse_debug_string(). + + +@key: +@value: + + + +Specifies the type of function passed to g_atexit(). + + + + + + + + + +@data: + + diff --git a/docs/reference/glib/tmpl/modules.sgml b/docs/reference/glib/tmpl/modules.sgml new file mode 100644 index 00000000..24c1a4ba --- /dev/null +++ b/docs/reference/glib/tmpl/modules.sgml @@ -0,0 +1,176 @@ + +Dynamic Loading of Modules + + +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. + + +To use them you must first determine whether dynamic loading +is supported on the platform by calling g_module_supported(). +If it is, you can open a module with g_module_open(), +find the module's symbols (e.g. function names) with g_module_symbol(), +and later close the module with g_module_close(). +g_module_name() will return the file name of a currently opened module. + + +If any of the above functions fail, the error status can be found with +g_module_error(). + + +The gmodule implementation features reference counting for opened modules, +and supports hook functions within a module which are called when the +module is loaded and unloaded (see #GModuleCheckInit and #GModuleUnload). + + +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"), +it must ensure that it is never unloaded, by calling g_module_make_resident(). + + + + + + + + + +The #GModule struct is an opaque data structure to represent a +Dynamically-Loaded Module. +It should only be accessed via the following functions. + + + + + +Checks if modules are supported on the current platform. + + +@Returns: TRUE if modules are supported. + + + + + + + +@directory: +@module_name: +@Returns: + + + + +Opens a module. +If the module has already been opened, its reference count is incremented. + + +@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. + + + + +Flags passed to g_module_open(). +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: +@G_MODULE_BIND_MASK: + + + +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. + + + + +Gets the file name from a #GModule. + + +@module: the module. +@Returns: the file name of the module, or "main" if the module is the main +program itself. + + + + +Ensures that a module will never be unloaded. +Any future g_module_close() calls on the module will be ignored. + + +@module: a module to make permanently resident. + + + + +Closes a module. + + +@module: the module to close. +@Returns: TRUE on success. + + + + +Gets a string describing the last module error. + + +@Returns: 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 +error. + + +@module: the #GModule corresponding to the module which has just been loaded. +@Returns: NULL on success, or a string describing the initialization error. + + + + +Specifies the type of the module function called when it is unloaded. +If a module contains a function named g_module_unload() it is called +automatically when the module is unloaded. +It is passed the #GModule structure. + + +@module: the module about to be unloaded. + + + + +Used to declare functions exported by modules. + + + + + + +Used to declare functions imported from modules. + + + + diff --git a/docs/reference/glib/tmpl/quarks.sgml b/docs/reference/glib/tmpl/quarks.sgml new file mode 100644 index 00000000..b62e032a --- /dev/null +++ b/docs/reference/glib/tmpl/quarks.sgml @@ -0,0 +1,91 @@ + +Quarks + + +a 2-way association between a string and a unique integer identifier. + + + +Quarks are associations between strings and integer identifiers. +Given either the string or the #GQuark identifier it is possible to +retrieve the other. + + +Quarks are used for both +Datasets and +Keyed Data Lists. + + +To create a new quark from a string, use g_quark_from_string() or +g_quark_from_static_string(). + + +To find the string corresponding to a given #GQuark, use g_quark_to_string(). + + +To find the #GQuark corresponding to a given string, use g_quark_try_string(). + + + + + + + + + +A GQuark is an integer which uniquely identifies a particular string. + + + + + +Gets the #GQuark identifying the given string. +If the string does not currently have an associated #GQuark, a new +#GQuark is created, using a copy of the string. + + +@string: a string. +@Returns: the #GQuark identifying the string. + + + + +Gets the #GQuark identifying the given (static) string. +If the string does not currently have an associated #GQuark, a new +#GQuark is created, linked to the given string. + + +Note that this function is identical to g_quark_from_string() except +that if a new #GQuark is created the string itself is used rather than +a copy. This saves memory, but can only be used if the string will +always exist (if, for example, it is a statically-allocated string). + + +@string: a string. +@Returns: the #GQuark identifying the string. + + + + +Gets the string associated with the given #GQuark. + + +@quark: a #GQuark. +@Returns: the string associated with the #GQuark. + + + + +Gets the #GQuark associated with the given string, or 0 if the string has +no associated #GQuark. + + +If you want the GQuark to be created if it doesn't already exist, use +g_quark_from_string() or g_quark_from_static_string(). + + +@string: a string. +@Returns: the #GQuark associated with the string, or 0 if there is no +#GQuark associated with the string. + + diff --git a/docs/reference/glib/tmpl/relations.sgml b/docs/reference/glib/tmpl/relations.sgml new file mode 100644 index 00000000..4c1dd611 --- /dev/null +++ b/docs/reference/glib/tmpl/relations.sgml @@ -0,0 +1,201 @@ + +Relations and Tuples + + +tables of data which can be indexed on any number of fields. + + + +A #GRelation is a table of data which can be indexed on any number of fields, +rather like simple database tables. A #GRelation contains a number of +records, called tuples. Each record contains a number of fields. +Records are not ordered, so it is not possible to find the record at a +particular index. + + +Note that #GRelation tables are currently limited to 2 fields. + + +To create a GRelation, use g_relation_new(). + + +To specify which fields should be indexed, use g_relation_index(). +Note that this must be called before any tuples are added to the #GRelation. + + +To add records to a #GRelation use g_relation_insert(). + + +To determine if a given record appears in a #GRelation, use +g_relation_exists(). Note that fields are compared directly, so pointers +must point to the exact same position (i.e. different copies of the same +string will not match.) + + +To count the number of records which have a particular value in a given +field, use g_relation_count(). + + +To get all the records which have a particular value in a given field, +use g_relation_select(). To access fields of the resulting records, +use g_tuples_index(). To free the resulting records use g_tuples_destroy(). + + +To delete all records which have a particular value in a given field, +use g_relation_delete(). + + +To destroy the #GRelation, use g_relation_destroy(). + + +To help debug #GRelation objects, use g_relation_print(). + + + + + + + + + +The #GRelation struct is an opaque data structure to represent a +Relation. +It should only be accessed via the following functions. + + + + + +Creates a new #GRelation with the given number of fields. +Note that currently the number of fields must be 2. + + +@fields: the number of fields. +@Returns: a new #GRelation. + + + + +Creates an index on the given field. +Note that this must be called before any records are added to the #GRelation. + + +@relation: a #GRelation. +@field: the field to index, counting from 0. +@hash_func: a function to produce a hash value from the field data. +@key_compare_func: a function to compare two values of the given field. + + + + +Inserts a record into a #GRelation. + + +@relation: a #GRelation. +@Varargs: the fields of the record to add. This must match the number of +fields in the #GRelation. + + + + +Returns TRUE if a record with the given values exists in a #GRelation. +Note that the values are compared directly, so that, for example, two +copies of the same string will not match. + + +@relation: a #GRelation. +@Varargs: the fields of the record to compare. The number must match the +number of fields in the #GRelation. +@Returns: TRUE if a record matches. + + + + +Returns the number of tuples in a #GRelation that have the given value +in the given field. + + +@relation: a #GRelation. +@key: the value to compare with. +@field: the field of each record to match. +@Returns: the number of matches. + + + + +Returns all of the tuples which have the given key in the given field. +Use g_tuples_index() to access the returned records. +The returned records should be freed with g_tuples_destroy(). + + +@relation: a #GRelation. +@key: the value to compare with. +@field: the field of each record to match. +@Returns: the records (tuples) that matched. + + + + +Deletes any records from a GRelation that have the given key value in +the given field. + + +@relation: a #GRelation. +@key: the value to compare with. +@field: the field of each record to match. +@Returns: the number of records deleted. + + + + +Destroys the #GRelation, freeing all memory allocated. +However, it does not free memory allocated for the +tuple data, so you should free that first if appropriate. + + +@relation: a #GRelation. + + + + +Outputs information about all records in a #GRelation, as well as the indexes. +It is for debugging. + + +@relation: a #GRelation. + + + + +The #GTuples struct is used to return records (or tuples) from the +#GRelation by g_relation_select(). +It only contains one public member - the number of records that matched. +To access the matched records, you must use g_tuples_index(). + + +@len: + + + +Frees the records which were returned by g_relation_select(). +This should always be called after g_relation_select() when you are +finished with the records. +The records are not removed from the #GRelation. + + +@tuples: the tuple data to free. + + + + +Gets a field from the records returned by g_relation_select(). +It returns the given field of the record at the given index. +The returned value should not be changed. + + +@tuples: the tuple data, returned by g_relation_select(). +@index: the index of the record. +@field: the field to return. +@Returns: the field of the record. + + diff --git a/docs/reference/glib/tmpl/scanner.sgml b/docs/reference/glib/tmpl/scanner.sgml new file mode 100644 index 00000000..9940cc02 --- /dev/null +++ b/docs/reference/glib/tmpl/scanner.sgml @@ -0,0 +1,490 @@ + +Lexical Scanner + + +a general purpose lexical scanner. + + + +The #GScanner and its associated functions provide a general purpose +lexical scanner. + + +FIXME: really needs an example and more detail, but I don't completely +understand it myself. Look at gtkrc.c for some code using the scanner. + + + + + + + + + +The data structure representing a lexical scanner. + + +You should set input_name after creating the scanner, since it is used +by the default message handler when displaying warnings and errors. +If you are scanning a file, the file name would be a good choice. + + +The user_data and +derived_data fields are not used. +If you need to associate extra data with the scanner you can place them here. + + +If you want to use your own message handler you can set the +msg_handler field. The type of the message +handler function is declared by #GScannerMsgFunc. + + +@user_data: +@max_parse_errors: +@parse_errors: +@input_name: +@derived_data: +@config: +@token: +@value: +@line: +@position: +@next_token: +@next_value: +@next_line: +@next_position: +@symbol_table: +@input_fd: +@text: +@text_end: +@buffer: +@scope_id: +@msg_handler: + + + +Creates a new #GScanner. +The @config_templ structure specifies the initial settings of the scanner, +which are copied into the #GScanner config field. +If you pass NULL then the default settings are used. +(See g_scanner_config_template in gscanner.c for the defaults.) + + +@config_templ: the initial scanner settings. +@Returns: the new #GScanner. + + + + +Specifies the #GScanner settings. + + +cset_skip_characters specifies which characters +should be skipped by the scanner (the default is the whitespace characters: +space, tab, carriage-return and line-feed). + + +cset_identifier_first specifies the characters +which can start identifiers. +(the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z). + + +cset_identifier_nth specifies the characters +which can be used in identifiers, after the first character. +The default is #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS, +#G_CSET_LATINC. + + +cpair_comment_single specifies the characters +at the start and end of single-line comments. The default is "#\n" which +means that single-line comments start with a '#' and continue until a '\n' +(end of line). + + +case_sensitive specifies if symbols are +case sensitive. + + +The rest of the fields are flags which turn features on or off. +FIXME: should describe these. + + +@cset_skip_characters: +@cset_identifier_first: +@cset_identifier_nth: +@cpair_comment_single: +@case_sensitive: +@skip_comment_multi: +@skip_comment_single: +@scan_comment_multi: +@scan_identifier: +@scan_identifier_1char: +@scan_identifier_NULL: +@scan_symbols: +@scan_binary: +@scan_octal: +@scan_float: +@scan_hex: +@scan_hex_dollar: +@scan_string_sq: +@scan_string_dq: +@numbers_2_int: +@int_2_float: +@identifier_2_string: +@char_2_token: +@symbol_2_token: +@scope_0_fallback: + + + +Prepares to scan a file. + + +@scanner: a #GScanner. +@input_fd: a file descriptor. + + + + + + + +@scanner: + + + + +Gets the file attributes. +This is the st_mode field from the +stat structure. See the stat() +documentation. + + +@filename: the file name. +@Returns: the file attributes. + + + + +Prepares to scan a text buffer. + + +@scanner: a #GScanner. +@text: the text buffer to scan. +@text_len: the length of the text buffer. + + + + +Gets the next token, without removing it from the input stream. +The token data is placed in the +next_token, +next_value, +next_line, and +next_position fields of the #GScanner structure. + + +@scanner: a #GScanner. +@Returns: the type of the token. + + + + +Gets the next token, removing it from the input stream. +The token data is placed in the +token, +value, +line, and +position fields of the #GScanner structure. + + +@scanner: a #GScanner. +@Returns: the type of the token. + + + + +Gets the current line in the input stream (counting from 1). + + +@scanner: a #GScanner. +@Returns: the current line. + + + + +Gets the current position in the current line (counting from 0). + + +@scanner: a #GScanner. +@Returns: the current position on the line. + + + + +Gets the current token type. +This is simply the token field in the #GScanner +structure. + + +@scanner: a #GScanner. +@Returns: the current token type. + + + + +Gets the current token value. +This is simply the value field in the #GScanner +structure. + + +@scanner: a #GScanner. +@Returns: the current token value. + + + + +Returns TRUE if the scanner has reached the end of the file or text buffer. + + +@scanner: a #GScanner. +@Returns: TRUE if the scanner has reached the end of the file or text buffer. + + + + +Sets the current scope. + + +@scanner: a #GScanner. +@scope_id: the new scope id. +@Returns: the old scope id. + + + + +Adds a symbol to the given scope. + + +@scanner: a #GScanner. +@scope_id: the scope id. +@symbol: the symbol to add. +@value: the value of the symbol. + + + + + + + +@scanner: +@scope_id: +@func: +@user_data: + +@func_data: + + + + + + + +@scanner: +@scope_id: +@symbol: +@Returns: + + + + + + + +@scanner: +@scope_id: +@symbol: + + + + + + + +@scanner: + + + + + + + +@scanner: + + + + + + + +@scanner: +@symbol: +@Returns: + + + + +Outputs a warning message, via the #GScanner message handler. + + +@scanner: a #GScanner. +@format: the message format. See the printf() +documentation. +@Varargs: the parameters to insert into the format string. + + + + +Outputs an error message, via the #GScanner message handler. + + +@scanner: a #GScanner. +@format: the message format. See the printf() +documentation. +@Varargs: the parameters to insert into the format string. + + + + +Outputs a message resulting from an unexpected token in the input stream. +FIXME: I don't understand the arguments here. + + +@scanner: a #GScanner. +@expected_token: the expected token. +@identifier_spec: a string describing the expected type of identifier, +or NULL to use the default "identifier" string. +@symbol_spec: a string describing the expected type of identifier, +or NULL to use the default "symbol" string. +@symbol_name: +@message: a message string to output at the end of the warning/error, or NULL. +@is_error: if TRUE it is output as an error. If False it is output as a +warning. + + + + + + + +@scanner: +@message: +@error: + + + + +Frees all memory used by the #GScanner. + + +@scanner: a #GScanner. + + + + +The possible types of token returned from each g_scanner_get_next_token() call. + + +@G_TOKEN_EOF: +@G_TOKEN_LEFT_PAREN: +@G_TOKEN_RIGHT_PAREN: +@G_TOKEN_LEFT_CURLY: +@G_TOKEN_RIGHT_CURLY: + + + +A union holding the value of the token. + + + + + +The possible errors, used in the v_error field +of #GTokenValue, when the token is a G_TOKEN_ERROR. + + +@G_ERR_UNKNOWN: +@G_ERR_UNEXP_EOF: +@G_ERR_UNEXP_EOF_IN_STRING: +@G_ERR_UNEXP_EOF_IN_COMMENT: +@G_ERR_NON_DIGIT_IN_CONST: +@G_ERR_DIGIT_RADIX: +@G_ERR_FLOAT_RADIX: +@G_ERR_FLOAT_MALFORMED: + + + +The set of lower-case ASCII alphabet characters. +Used for specifying valid identifier characters in #GScannerConfig. + + + + + + +The set of upper-case ASCII alphabet characters. +Used for specifying valid identifier characters in #GScannerConfig. + + + + + + +Part of the set of extended characters in the Latin character sets. +FIXME: lower case? +Used for specifying valid identifier characters in #GScannerConfig. + + + + + + +Part of the set of extended characters in the Latin character sets. +FIXME: upper case? +Used for specifying valid identifier characters in #GScannerConfig. + + + + + + +Adds a symbol to the default scope. +Deprecated in favour of g_scanner_scope_add_symbol(). + + +@scanner: a #GScanner. +@symbol: the symbol to add. +@value: the value of the symbol. + + + + +Removes a symbol from the default scope. +Deprecated in favour of g_scanner_scope_remove_symbol(). + + +@scanner: a #GScanner. +@symbol: the symbol to remove. + + + + +Calls a function for each symbol in the default scope. +Deprecated in favour of g_scanner_scope_foreach_symbol(). + + +@scanner: a #GScanner. +@func: the function to call with each symbol. +@data: data to pass to the function. + + diff --git a/docs/reference/glib/tmpl/string_chunks.sgml b/docs/reference/glib/tmpl/string_chunks.sgml new file mode 100644 index 00000000..85961aed --- /dev/null +++ b/docs/reference/glib/tmpl/string_chunks.sgml @@ -0,0 +1,110 @@ + +String Chunks + + +efficient storage of groups of strings. + + + +String chunks are used to store groups of strings. +Memory is allocated in blocks, and as strings are added to the #GStringChunk +they are copied into the next free position in a block. When a block is +full a new block is allocated. + + +When storing a large number of strings, string chunks are more efficient +than using g_strdup() since fewer calls to malloc() +are needed, and less memory is wasted in memory allocation overheads. + + +By adding strings with g_string_chunk_insert_const() it is also possible +to remove duplicates. + + +To create a new #GStringChunk use g_string_chunk_new(). + + +To add strings to a #GStringChunk use g_string_chunk_insert(). + + +To add strings to a #GStringChunk, but without duplicating strings which are +already in the #GStringChunk, use g_string_chunk_insert_const(). + + +To free the entire #GStringChunk use g_string_chunk_free(). +It is not possible to free individual strings. + + + + + + + + + +An opaque data structure representing String Chunks. +It should only be accessed by using the following functions. + + + + + +Creates a new #GStringChunk. + + +@size: the default size of the blocks of memory which are allocated to store +the strings. If a particular string is larger than this default size, a larger +block of memory will be allocated for it. +@Returns: a new #GStringChunk. + + + + +Adds a copy of @string to the #GStringChunk. +It returns a pointer to the new copy of the string in the #GStringChunk. +The characters in the string can be changed, if necessary, though you +should not change anything after the end of the string. + + +Unlike g_string_chunk_insert_const(), this function does not check for +duplicates. Also strings added with g_string_chunk_insert() will not be +searched by g_string_chunk_insert_const() when looking for duplicates. + + +@chunk: a #GStringChunk. +@string: the string to add. +@Returns: a pointer to the copy of @string within the #GStringChunk. + + + + +Adds a copy of @string to the #GStringChunk, unless the same string has +already been added to the #GStringChunk with g_string_chunk_insert_const(). + + +This function is useful if you need to copy a large number of strings +but do not want to waste space storing duplicates. But you must remember +that there may be several pointers to the same string, and so any changes +made to the strings should be done very carefully. + + +Note that g_string_chunk_insert_const() will not return a pointer to a string +added with g_string_chunk_insert(), even if they do match. + + +@chunk: a #GStringChunk. +@string: the string to add. +@Returns: a pointer to the new or existing copy of @string within the +#GStringChunk. + + + + +Frees all memory allocated by the #GStringChunk. +After calling g_string_chunk_free() it is not safe to +access any of the strings which were contained within it. + + +@chunk: a #GStringChunk. + + diff --git a/docs/reference/glib/tmpl/string_utils.sgml b/docs/reference/glib/tmpl/string_utils.sgml new file mode 100644 index 00000000..2362f778 --- /dev/null +++ b/docs/reference/glib/tmpl/string_utils.sgml @@ -0,0 +1,354 @@ + +String Utility Functions + + +various string-related functions. + + + +This section describes a number of utility functions for creating, +duplicating, and manipulating strings. + + + + + + + + + +Duplicates a string. +The returned string should be freed when no longer needed. + + +@str: the string to duplicate. +@Returns: a newly-allocated copy of @str. + + + + +Duplicates the first @n characters of a string, and null-terminates it. +If @str is NULL, NULL is returned. +The returned string should be freed when no longer needed. + + +@str: the string to duplicate part of. +@n: the number of characters to copy, which must be less than or equal to the +length of @str. +@Returns: a newly-allocated copy of the first @n characters of @str, +null-terminated. + + + + +Creates a new string @length characters long filled with @fill_char. +The returned string should be freed when no longer needed. + + +@length: the length of the new string. +@fill_char: the character to fill the string with. +@Returns: a newly-allocated string filled the @fill_char. + + + + +Similar to the standard C sprintf() function +but safer, since it calculates the maximum space required and allocates +memory to hold the result. +The returned string should be freed when no longer needed. + + +@format: the standard sprintf() format string. +@Varargs: the parameters to insert into the format string. +@Returns: a newly-allocated string holding the result. + + + + +Similar to the standard C vsprintf() function +but safer, since it calculates the maximum space required and allocates +memory to hold the result. +The returned string should be freed when no longer needed. + + +@format: the standard sprintf() format string. +@args: the list of parameters to insert into the format string. +@Returns: a newly-allocated string holding the result. + + + + +A safer form of the standard sprintf() function. +The output is guaranteed to not exceed @n characters (including the +terminating NULL character), so it is easy to ensure that a buffer overflow +cannot occur. + + +See also g_strdup_printf(). + + + +In versions of GLib prior to 1.2.3, this function may return -1 if the output +was truncated, and the truncated string may not be NULL-terminated. + + + +@string: the buffer to hold the output. +@n: the maximum number of characters to produce (including the terminating null +character). +@format: the format string. See the sprintf() +documentation. +@Varargs: the arguments to insert in the output. +@Returns: the length of the output string. + + + + +A safer form of the standard vsprintf() function. +The output is guaranteed to not exceed @n characters (including the +terminating NULL character), so it is easy to ensure that a buffer overflow +cannot occur. + + +See also g_strdup_vprintf(). + + + +In versions of GLib prior to 1.2.3, this function may return -1 if the output +was truncated, and the truncated string may not be NULL-terminated. + + + +@string: the buffer to hold the output. +@n: the maximum number of characters to produce (including the terminating null +character). +@format: the format string. See the sprintf() +documentation. +@args: the list of arguments to insert in the output. +@Returns: the length of the output string. + + + + +Calculates the maximum space needed to store the output of the +sprintf() function. + + +@format: the format string. See the printf() +documentation. +@args: the parameters to be inserted into the format string. +@Returns: the maximum space needed to store the formatted string. + + + + +Converts a string to upper case. + + +@string: the string to convert. + + + + +Converts a string to lower case. + + +@string: the string to convert. + + + + +A case-insensitive string comparison, corresponding to the standard +strcasecmp() function on platforms which support it. + + +@s1: a string. +@s2: a string to compare with @s1. +@Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive +value if @s1 > @s2. + + + + +A case-insensitive string comparison, corresponding to the standard +strncasecmp() function on platforms which support it. +It is similar to g_strcasecmp() except it only compares the first @n characters +of the strings. + + +@s1: a string. +@s2: a string to compare with @s1. +@n: the maximum number of characters to compare. +@Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive +value if @s1 > @s2. + + + + +Reverses all of the characters in a string. +For example, g_strreverse ("abcdef") would be "fedcba". + + +@string: the string to reverse. + + + + +Converts a string to a gdouble value. +It calls the standard strtod() function +to handle the conversion, but if the string is not completely converted +it attempts the conversion again in the "C" locale, and returns the best +match. + + +@nptr: the string to convert to a numeric value. +@endptr: if non-NULL, it returns the character after the last character used +in the conversion. +@Returns: the gdouble value. + + + + +Removes leading whitespace from a string, by moving the rest of the +characters forward. + + +@string: a string to remove the leading whitespace from. +@Returns: @string. + + + + +Removes trailing whitespace from a string. + + +@string: a string to remove the trailing whitespace from. +@Returns: @string. + + + + +Removes leading and trailing whitespace from a string. + + +@string: a string to remove the leading and trailing whitespace from. + + + + +Converts any delimiter characters in @string to @new_delimiter. +Any characters in @string which are found in @delimiters are changed +to the @new_delimiter character. + + +@string: the string to convert. +@delimiters: a string containing the current delimiters, or NULL to use the +standard delimiters defined in #G_STR_DELIMITERS. +@new_delimiter: the new delimiter character. +@Returns: + + + + +The standard delimiters, used in #g_strdelimit. + + + + + + +Escapes all backslash characters, '\' in a string, by inserting a second '\'. + + +@string: a string to escape the backslashes in. +@Returns: a newly allocated copy of @string, with all backslash characters +escaped using a second backslash. + + + + +Splits a string into a maximum of @max_tokens pieces, using the given +@delimiter. If @max_tokens is reached, the final string in the returned +string array contains the remainder of @string. + + +@string: a string to split. +@delimiter: a string which specifies the places at which to split the string. +The delimiter is not included in any of the resulting strings, unless +max_tokens is reached. +@max_tokens: the maximum number of strings to split @string into. If this is +less than 1, the string is split completely. +@Returns: a newly-allocated array of strings. Use g_strfreev() to free it. + + + + +Frees a NULL-terminated array of strings, and the array itself. + + +@str_array: a NULL-terminated array of strings to free. + + + + +Concatenates all of the given strings into one long string. +The returned string should be freed when no longer needed. + + +@string1: The first string to add, which must not be NULL. +@Varargs: a NULL-terminated list of strings to append to the string. +@Returns: a newly-allocated string containing all the string arguments. + + + + +Joins a number of strings together to form one long string, with the optional +@separator inserted between each of them. + + +@separator: a string to insert between each of the strings, or NULL. +@Varargs: a NULL-terminated list of strings to join. +@Returns: a newly-allocated string containing all of the strings joined +together, with @separator between them. + + + + +Joins a number of strings together to form one long string, with the optional +@separator inserted between each of them. + + +@separator: a string to insert between each of the strings, or NULL. +@str_array: a NULL-terminated array of strings to join. +@Returns: a newly-allocated string containing all of the strings joined +together, with @separator between them. + + + + +Returns a string corresponding to the given error code, e.g. "no such process". +This function is included since not all platforms support the +strerror() function. + + +@errnum: the system error number. See the standard C %errno +documentation. +@Returns: a string describing the error code. +If the error code is unknown, it returns "unknown error (<code>)". +The string can only be used until the next call to g_strerror. + + + + +Returns a string describing the given signal, e.g. "Segmentation fault". +This function is included since not all platforms support the +strsignal() function. + + +@signum: the signal number. See the signal +documentation. +@Returns: a string describing the signal. +If the signal is unknown, it returns "unknown signal (<signum>)". +The string can only be used until the next call to g_strsignal. + + diff --git a/docs/reference/glib/tmpl/strings.sgml b/docs/reference/glib/tmpl/strings.sgml new file mode 100644 index 00000000..f621d180 --- /dev/null +++ b/docs/reference/glib/tmpl/strings.sgml @@ -0,0 +1,209 @@ + +Strings + + +text buffers which grow automatically as text is added. + + + +A #GString is similar to a standard C string, except that it grows +automatically as text is appended or inserted. + + +The space allocated for the string is always a power of two, so as the +string grows it will occupy 2, 4, 8, 16, 32, 64, 128 etc. characters. + + + + + + + + + +The #GString struct contains the public fields of a #GString. +The str field points to the character data. +It may move as text is added. +The len field contains the length of the string, +not including the terminating null character. + + +The str field is zero-terminated and so can be used as an ordinary C +string. But it may be moved when text is appended or inserted into the +string. + + +@str: +@len: + + + +Creates a new #GString, initialized with the given string. + + +@init: the initial text to copy into the string. +@Returns: the new #GString. + + + + +Creates a new GString, with enough space for @dfl_size characters. +This is useful if you are going to add a lot of text to the string and +don't want it to be reallocated too often. + + +@dfl_size: the default size of the space allocated to hold the string. +@Returns: the new #GString. + + + + +Copies the characters from one #GString into another, destroying any previous +contents. It is rather like the standard strcpy() function, except that +you do not have to worry about having enough space to copy the string. + + +@lval: the destination #GString. Its current contents are destroyed. +@rval: the source #GString. +@Returns: the destination #GString. + + + + +Writes a formatted string into a #GString. +This is similar to the standard sprintf() function, +except that the GString buffer automatically expands to contain the results. +The previous contents of the GString are destroyed. + + +@string: a #GString. +@format: the string format. See the sprintf() +documentation. +@Varargs: the parameters to insert into the format string. + + + + +Appends a formatted string onto the end of a #GString. +This function is is similar to g_string_sprintf() except that +the text is appended to the GString. + + +@string: a #GString. +@format: the string format. See the sprintf() +documentation. +@Varargs: the parameters to insert into the format string. + + + + +Adds a string onto the end of a #GString, expanding it if necessary. + + +@string: a #GString. +@val: the string to append onto the end of the #GString. +@Returns: the #GString. + + + + +Adds a character onto the end of a #GString, expanding it if necessary. + + +@string: a #GString. +@c: the character to append onto the end of the #GString. +@Returns: the #GString. + + + + +Adds a string on to the start of a #GString, expanding it if necessary. + + +@string: a #GString. +@val: the string to prepend on the start of the #GString. +@Returns: the #GString. + + + + +Adds a character onto the start of a #GString, expanding it if necessary. + + +@string: a #GString. +@c: the character to prepend on the start of the #GString. +@Returns: the #GString. + + + + +Inserts a copy of a string into a #GString, expanding it if necessary. + + +@string: a #GString. +@pos: the position to insert the copy of the string. +@val: the string to insert. +@Returns: the #GString. + + + + +Inserts a character into a #GString, expanding it if necessary. + + +@string: a #GString. +@pos: the position to insert the character. +@c: the character to insert. +@Returns: the #GString. + + + + +Removes @len characters from a #GString, starting at position @pos. +The rest of the #GString is shifted down to fill the gap. + + +@string: a #GString. +@pos: the position of the characters to remove. +@len: the number of characters to remove. +@Returns: the #GString. + + + + +Cuts off the end of the GString, leaving the first @len characters. + + +@string: a #GString. +@len: the new size of the #GString. +@Returns: the #GString. + + + + +Frees the memory allocated for the #GString. +If free_segment is TRUE it also frees the character data. + + +@string: a #GString. +@free_segment: if TRUE the actual character data is freed as well. + + + + +Converts a #GString to upper case. + + +@string: a #GString. +@Returns: the #GString. + + + + +Converts a #GString to lower case. + + +@string: a #GString. +@Returns: the #GString. + + diff --git a/docs/reference/glib/tmpl/threads.sgml b/docs/reference/glib/tmpl/threads.sgml new file mode 100644 index 00000000..8b2a372b --- /dev/null +++ b/docs/reference/glib/tmpl/threads.sgml @@ -0,0 +1,939 @@ + + +Threads + + + +thread abstraction; including mutexes, conditions and thread private data. + + + + +Threads act almost like processes, but unlike processes all threads of +one process share the same memory. This is good, as it provides easy +communication between the involved threads via this shared memory, and +it is bad, because strange things (so called Heisenbugs) might happen, +when the program is not carefully designed. Especially bad is, that due +to the concurrent nature of threads no assumptions on the order of +execution of different threads can be done unless explictly forced by +the programmer through synchronization primitives. + + + +The aim of the thread related functions in GLib is to provide a +portable means for writing multithread safe software. There are +primitives for mutexes to protect the access to portions of memory +(#GMutex, #GStaticMutex, #G_LOCK_DEFINE and friends), there are +primitives for condition variables to allow synchronization of threads +(#GCond) and finally there are primitives for thread-private data, +that every thread has a private instance of (#GPrivate, +#GStaticPrivate). + + + +Currently there is only as much thread support included in GLib as is +necessary to make GLib itself multithread safe. Future versions of +GLib might contain functions to actually create threads and the +like. For now the most portable way to create threads is to require +the macro #G_THREADS_IMPL_POSIX to be defined and use POSIX threads +then. This will work on almost all platforms (except most notably +Solaris). + + + + + + + + + + +This macro is defined, if GLib was compiled with thread support. This +does not necessarily mean, that there is a thread implementation +available, but the infrastructure is in place and once you provide a +thread implementation to g_thread_init(), GLib will be multithread +safe. It isn't and can't be, if #G_THREADS_ENABLED is not defined. + + + + + + + +This macro is defined, if POSIX style threads are used. + + + + + + + +This macro is defined, if the SOLARIS thread system is used. + + + + + + + +This macro is defined, if the NSPR thread implementation is used. +NSPR is the cross platform library of mozilla. + + + + + + + +This macro is defined, if no thread implementation is used. You can +however provide one to g_thread_init() to make GLib multithread safe. + + + + + + + +This function table is used by g_thread_init() to initialize the +thread system. The functions in that table are directly used by their +g_* prepended counterparts, that are described here, e.g. if you call +g_mutex_new() then mutex_new() from the table provided to +g_thread_init() will be called. + + + + +This struct should only be used, if you know, what you are doing. + + + +@mutex_new: +@mutex_lock: +@mutex_trylock: +@mutex_unlock: +@mutex_free: +@cond_new: +@cond_signal: +@cond_broadcast: +@cond_wait: +@cond_timed_wait: +@cond_free: +@private_new: +@private_get: +@private_set: + + + + +Before you use a thread related function in GLib, you should +initialize the thread system. This is done by calling +g_thread_init(). Most of the time you will only have to call +g_thread_init(NULL). + + + + +You should only call g_thread_init() with a non-NULL parameter, if you +really know, what you are doing. + + + + + +g_thread_init() must not be called directly or indirectly as a +callback from GLib. + + + + +g_thread_init() might only be called once. On the second call +it will abort with an error. If you want to make sure, that the thread +system is initialized, you can do that too: + + + + + +if (!g_thread_supported ()) g_thread_init (NULL); + + + + + +After that line either the thread system is initialized or the program +will abort, if no thread system is available in GLib, i.e. either +#G_THREADS_ENABLED is not defined or #G_THREADS_IMPL_NONE is defined. + + + +If no thread system is available and @vtable is NULL or if not all +elements of @vtable are non-NULL, then g_thread_init() will abort. + + + + +To use g_thread_init() in your program, you have to link with the +libraries, that the command "glib-config --libs gthread" outputs. This +is not the case for all the other thread related functions of +GLib. Those can be used without having to link with the thread +libraries. + + + +@vtable: a function table of type #GThreadFunctions, that provides the +entry points to the thread system to be used. + + + + +This function returns, whether the thread system is initialized or +not. + + + + +This function is actually a macro. Apart from taking the address of it +you can however use it as if it was a function. + + + +@Returns: TRUE, if the thread system is initialized. + + + + + +The #GMutex struct is an opaque data structure to represent a mutex +(mutual exclusion). It can be used to protect data against shared +access. Take for example the following function: + + + +A function which will not work in a threaded environment + + int give_me_next_number () + { + static int current_number = 0; + + /* now do a very complicated calculation to calculate the new number, + this might for example be a random number generator */ + current_number = calc_next_number (current_number); + return current_number; + } + + + + + +It is easy to see, that this won't work in a multithreaded +application. There current_number must be protected against shared +access. A first naive implementation would be: + + + + +The wrong way to write a thread-safe function + + int give_me_next_number () + { + static int current_number = 0; + int ret_val; + static GMutex * mutex = NULL; + + if (!mutex) + mutex = g_mutex_new (); + g_mutex_lock (mutex); + ret_val = current_number = calc_next_number (current_number); + g_mutex_unlock (mutex); + return ret_val; + } + + + + + +This looks like it would work, but there is a race condition while +constructing the mutex and this code can't work reliable. So please do +not use such constructs in your own programs. One working solution is: + + + + +A correct thread-safe function + + static GMutex *give_me_next_number_mutex = NULL; + + /* this function must be called before any call to give_me_next_number () + it must be called exactly once. */ + void init_give_me_next_number () + { + g_assert (give_me_next_number_mutex == NULL); + give_me_next_number_mutex = g_mutex_new (); + } + + int give_me_next_number () + { + static int current_number = 0; + int ret_val; + + g_mutex_lock (give_me_next_number_mutex); + ret_val = current_number = calc_next_number (current_number); + g_mutex_unlock (give_me_next_number_mutex); + return ret_val; + } + + + + + +#GStaticMutex provides a simpler and safer way of doing this. + + + +A #GMutex should only be accessed via the following functions. + + + + +All of the g_mutex_* functions are actually macros. Apart from taking +the addresses of them, you can however use them as if they were functions. + + + + + + + +Creates a new #GMutex. + + + + +This function will abort, if g_thread_init() has not been called yet. + + + +@Returns: a new #GMutex. + + + + + +Locks the #GMutex. If the #GMutex is already locked by another thread, +the current thread will block until the #GMutex is unlocked by the +other thread. + + + +This function can also be used, if g_thread_init() has not yet been +called and will do nothing then. + + + + +#GMutex is not guaranteed to be recursive, i.e. a thread might block, +if it already has locked the #GMutex. It will deadlock then, of +course. + + + +@mutex: a #GMutex. + + + + + +Tries to lock the #GMutex. If the #GMutex is already locked by another +thread, it immediately returns FALSE. Otherwise it locks the #GMutex +and returns TRUE. + + + +This function can also be used, if g_thread_init() has not yet been +called and will immediately return TRUE then. + + +@mutex: a #GMutex. +@Returns: TRUE, if the #GMutex could be locked. + + + + + +Unlocks the #GMutex. If another thread is blocked in a g_mutex_lock() +call, it will be woken and can lock the #GMutex itself. This function +can also be used, if g_thread_init() has not yet been called and will +do nothing then. + + +@mutex: a #GMutex. + + + + + +Destroys the #GMutex. + + +@mutex: a #GMutex. + + + + + +A #GStaticMutex works like a #GMutex, but it has one significant +advantage. It doesn't need to be created at run-time like a #GMutex, +but can be defined at compile-time. Here is a shorter, easier and +safer version of our give_me_next_number() example: + + + + +Using GStaticMutex to simplify thread-safe programming + + int give_me_next_number () + { + static int current_number = 0; + int ret_val; + static GStaticMutex mutex = G_STATIC_MUTEX_INIT; + + g_static_mutex_lock (&mutex); + ret_val = current_number = calc_next_number (current_number); + g_static_mutex_unlock (&mutex); + return ret_val; + } + + + + + +Even though #GStaticMutex is not opaque, it should only be used with +the following functions, as it is defined differently on different +platforms. + + +All of the g_static_mutex_* functions can also be used, if +g_thread_init() has not yet. + + + + +All of the g_static_mutex_* functions are actually macros. Apart from +taking the addresses of them, you can however use them as if they were +functions. + + + +@runtime_mutex: + + + + +Every #GStaticMutex must be initialized with this macro, before it can +be used. + + + + +Initializing a GStaticMutext + +GStaticMutex my_mutex = G_STATIC_MUTEX_INIT; + + + + + + + + +works like g_mutex_lock(), but for a #GStaticMutex. + + +@mutex: a #GStaticMutex. + + + + + +works like g_mutex_trylock(), but for a #GStaticMutex. + + +@mutex: a #GStaticMutex. +@Returns: TRUE, if the #GStaticMutex could be locked. + + + + + +works like g_mutex_unlock(), but for a #GStaticMutex. + + +@mutex: a #GStaticMutex. + + + + + +For some operations (like g_cond_wait()) you must have a #GMutex +instead of a #GStaticMutex. This function will return the +corresponding #GMutex for every #GStaticMutex. + + +@mutex: a #GStaticMutex. +@Returns: the corresponding #GMutex. + + + + + +The G_LOCK_* macros provide a convenient interface to #GStaticMutex +with the advantage that they will expand to nothing in programs +compiled against a thread-disabled GLib, saving code and memory +there. #G_LOCK_DEFINE defines a lock. It can occur, where variable +definitions may occur in programs, i.e. in the first block of a +function or outside of functions. The @name parameter will be mangled +to get the name of the #GStaticMutex. This means, that you can use +names of existing variables as the parameter, e.g. the name of the +variable you intent to protect with the lock. Look at our +give_me_next_number() example using the G_LOCK_* macros: + + + + +Using the G_LOCK_* convenience macros + +int give_me_next_number () + { + static int current_number = 0; + int ret_val; + G_LOCK_DEFINE_STATIC (current_number); + + G_LOCK (current_number); + ret_val = current_number = calc_next_number (current_number); + G_UNLOCK (current_number); + return ret_val; + } + + + + +@name: the name of the lock. + + + + + +This works like #G_LOCK_DEFINE, but it creates a static object. + + +@name: the name of the lock. + + + + + +This declares a lock, that is defined with #G_LOCK_DEFINE in another module. + + +@name: the name of the lock. + + + + + +works like g_mutex_lock(), but for a lock defined with #G_LOCK_DEFINE. + + +@name: the name of the lock. + + + + + +works like g_mutex_trylock(), but for a lock defined with #G_LOCK_DEFINE. + + +@name: the name of the lock. +@Returns: TRUE, if the lock could be locked. + + + + + +works like g_mutex_unlock(), but for a lock defined with #G_LOCK_DEFINE. + + +@name: the name of the lock. + + + + + +The #GCond struct is an opaque data structure to represent a +condition. A #GCond is an object, that threads can block on, if they +find a certain condition to be false. If other threads change the +state of this condition they can signal the #GCond, such that the +waiting thread is woken up. + + + + +Using GCond to block a thread until a condition is satisfied + +GCond* data_cond = NULL; /* Must be initialized somewhere */ +GMutex* data_mutex = NULL; /* Must be initialized somewhere */ +gpointer current_data = NULL; + +void push_data (gpointer data) +{ + g_mutex_lock (data_mutex); + current_data = data; + g_cond_signal (data_cond); + g_mutex_unlock (data_mutex); +} + +gpointer pop_data () +{ + gpointer data; + + g_mutex_lock (data_mutex); + while (!current_data) + g_cond_wait (data_cond, data_mutex); + data = current_data; + current_data = NULL; + g_mutex_unlock (data_mutex); + return data; +} + + + + + +Whenever a thread calls pop_data() now, it will wait until +current_data is non-NULL, i.e. until some other thread has called +push_data(). + + + + +It is important to use the g_cond_wait() and g_cond_timed_wait() +functions only inside a loop, which checks for the condition to be +true as it is not guaranteed that the waiting thread will find it +fulfilled, even if the signaling thread left the condition +in that state. This is because another thread can have altered the +condition, before the waiting thread got the chance to be woken up, +even if the condition itself is protected by a #GMutex, like above. + + + + +A #GCond should only be accessed via the following functions. + + + + +All of the g_cond_* functions are actually macros. Apart from taking +the addresses of them, you can however use them as if they were functions. + + + + + + + +Creates a new #GCond. This function will abort, if g_thread_init() +has not been called yet. + + +@Returns: a new #GCond. + + + + +If threads are waiting for @cond, exactly one of them is woken up. It +is good practice to hold the same lock as the waiting thread, while +calling this function, though not required. + + + +This function can also be used, if g_thread_init() has +not yet been called and will do nothing then. + + +@cond: a #GCond. + + + + + +If threads are waiting for @cond, all of them are woken up. It is good +practice to lock the same mutex as the waiting threads, while calling +this function, though not required. + + + +This function can also be used, if g_thread_init() has +not yet been called and will do nothing then. + + +@cond: a #GCond. + + + + + +Waits until this thread is woken up on the #GCond. The #GMutex is +unlocked before falling asleep and locked again before resuming. + + + +This function can also be used, if g_thread_init() has not yet been +called and will immediately return then. + + +@cond: a #GCond. +@mutex: the #GMutex, that is currently locked. + + + + + +Waits until this thread is woken up on the #GCond, but not longer than +until the time, that is specified by @abs_time. The #GMutex is +unlocked before falling asleep and locked again before resuming. + + + +If @abs_time is NULL, g_cond_timed_wait() acts like g_cond_wait(). + + + +This function can also be used, if g_thread_init() has not yet been +called and will immediately return TRUE then. + + +@cond: a #GCond. +@mutex: the #GMutex, that is currently locked. +@abs_time: a #GTimeVal, determining the final time. +@Returns: TRUE, if the thread is woken up in time. + + + + + +Destroys the #GCond. + + +@cond: a #GCond. + + + + +The #GPrivate struct is an opaque data structure to represent a thread +private data key. Threads can thereby obtain and set a pointer, which +is private to the current thread. Take our give_me_next_number() +example from above. Now we don't want current_number to be shared +between the threads, but to be private to each thread. This can be +done as follows: + + + +Using GPrivate for per-thread data + + GPrivate* current_number_key = NULL; /* Must be initialized somewhere */ + /* with g_private_new (g_free); */ + + int give_me_next_number () + { + int *current_number = g_private_get (current_number_key); + + if (!current_number) + { + current_number = g_new (int,1); + *current_number = 0; + g_private_set (current_number_key, current_number); + } + *current_number = calc_next_number (*current_number); + return *current_number; + } + + + + + +Here the pointer belonging to the key current_number_key is read. If +it is NULL, it has not been set yet. Then get memory for an integer +value, assign this memory to the pointer and write the pointer +back. Now we have an integer value, that is private to the current +thread. + + + +The #GPrivate struct should only be accessed via the following functions. + + + + +All of the g_private_* functions are actually macros. Apart from taking +the addresses of them, you can however use them as if they were functions. + + + + + + + +Creates a new #GPrivate. If @destructor is non-NULL, it is a pointer +to a destructor function. Whenever a thread ends and the corresponding +pointer keyed to this instance of #GPrivate is non-NULL, the +destructor is called with this pointer as the argument. + + + + +The @destructor is working quite differently from @notify in +g_static_private_set(). + + + + + +A #GPrivate can not be destroyed. Reuse it instead, if you can to +avoid shortage. + + + + + +This function will abort, if g_thread_init() has not been called yet. + + + +@destructor: a function to handle the data keyed to #GPrivate, when a +thread ends. + + + + + +Returns the pointer keyed to @private_key for the current thread. This +pointer is NULL, when g_private_set() hasn't been called for the +current @private_key and thread yet. + + + +This function can also be used, if g_thread_init() has not yet been +called and will return the value of @private_key casted to #gpointer then. + + +@private_key: a #GPrivate. +@Returns: the corresponding pointer. + + + + + +Sets the pointer keyed to @private_key for the current thread. + + + +This function can also be used, if g_thread_init() has not yet been +called and will set @private_key to @data casted to #GPrivate* then. + + +@private_key: a #GPrivate. +@value: + +@data: the new pointer. + + + + + +A #GStaticPrivate works almost like a #GPrivate, but it has one +significant advantage. It doesn't need to be created at run-time like +a #GPrivate, but can be defined at compile-time. This is similar to +the difference between #GMutex and #GStaticMutex. Now look at our +give_me_next_number() example with #GStaticPrivate: + + + + +Using GStaticPrivate for per-thread data + + int give_me_next_number () + { + static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT; + int *current_number = g_static_private_get (&current_number_key); + + if (!current_number) + { + current_number = g_new (int,1); + *current_number = 0; + g_static_private_set (&current_number_key, current_number, g_free); + } + *current_number = calc_next_number (*current_number); + return *current_number; + } + + + + +@index: + + + +Every #GStaticPrivate must be initialized with this macro, before it can +be used. + + + + + +GStaticPrivate my_private = G_STATIC_PRIVATE_INIT; + + + + + + + + +Works like g_private_get() only for a #GStaticPrivate. + + + +This function also works, if g_thread_init() has not yet been called. + + +@private_key: a #GStaticPrivate. +@Returns: the corresponding pointer. + + + + +Sets the pointer keyed to @private_key for the current thread and the +function @notify to be called with that pointer (NULL or non-NULL), +whenever the pointer is set again or whenever the current thread ends. + + + +This function also works, if g_thread_init() has not yet been +called. If g_thread_init() is called later, the @data keyed to +@private_key will be inherited only by the main thread, i.e. the one that +called g_thread_init(). + + + + +The @notify is working quite differently from @destructor in +g_private_new(). + + + +@private_key: a #GStaticPrivate. +@data: the new pointer. +@notify: a function to be called with the pointer, whenever the +current thread ends or sets this pointer again. + + diff --git a/docs/reference/glib/tmpl/timers.sgml b/docs/reference/glib/tmpl/timers.sgml new file mode 100644 index 00000000..840a0bc9 --- /dev/null +++ b/docs/reference/glib/tmpl/timers.sgml @@ -0,0 +1,75 @@ + +Timers + + +functions to time operations. + + + +Timers can be used to time operations, in a similar way to a stopwatch. +Call g_timer_new () to create the timer, g_timer_start () to start it, +g_timer_elapsed () to determine the time which has elapsed since the timer +was started, and g_timer_stop () to stop the timer. + + + + + + + + +An opaque data structure which holds the timer information. + + + + + +Creates a new timer. + + +@Returns: the new timer. + + + + +Starts the timer. + + +@timer: the timer. + + + + +Stops the timer. + + +@timer: the timer. + + + + + + + +@timer: the timer. +@microseconds: if non-NULL, this will be set to the microseconds component +of the elapsed time (it does not include the number of seconds elapsed). +@Returns: the elapsed time in seconds, as a double. + + + + +Resets the elapsed time to 0, leaving the timer running. + + +@timer: the timer. + + + + +Destroys the timer, freeing the memory allocated for it. + + +@timer: the timer. + + diff --git a/docs/reference/glib/tmpl/trees-binary.sgml b/docs/reference/glib/tmpl/trees-binary.sgml new file mode 100644 index 00000000..ef2f9e11 --- /dev/null +++ b/docs/reference/glib/tmpl/trees-binary.sgml @@ -0,0 +1,228 @@ + +Balanced Binary Trees + + +a sorted collection of key/value pairs optimised for searching +and traversing in order. + + + +The #GTree structure and its associated functions provide a sorted collection +of key/value pairs optimised for searching and traversing in order. + + +To create a new #GTree use g_tree_new(). + + +To insert a key/value pair into a #GTree use g_tree_insert(). + + +To lookup the value corresponding to a given key, use g_tree_lookup(). + + +To find out the number of nodes in a #GTree, use g_tree_nnodes(). +To get the height of a #GTree, use g_tree_height(). + + +To traverse a #GTree, calling a function for each node visited in the +traversal, use g_tree_traverse(). + + +To remove a key/value pair use g_tree_remove(). + + +To destroy a #GTree, use g_tree_destroy(). + + + + + + + + + +The #GTree struct is an opaque data structure representing a +Balanced Binary Tree. +It should be accessed only by using the following functions. + + + + + +Creates a new GTree. + + +@key_compare_func: the function used to order the nodes in the #GTree. +It should return values similar to the standard strcmp() +function - +0 if the two arguments are equal, a negative value if the first argument comes +before the second, or a positive value if the first argument comes after the +second. +@Returns: a new #GTree. + + + + +Inserts a key/value pair into a #GTree. +If the given key already exists in the #GTree it is set to the new value. +(If you are using dynamically allocated keys and values you should be careful +to ensure that the old values are freed.) + + +The tree is automatically 'balanced' as new key/value pairs are added, +so that the distance from the root to every leaf is as small as possible. + + +@tree: a #GTree. +@key: the key to insert. +@value: the value corresponding to the key. + + + + +Gets the number of nodes in a #GTree. + + +@tree: a #GTree. +@Returns: the number of nodes in the #GTree. + + + + +Gets the height of a #GTree. + + +If the #GTree contains no nodes, the height is 0. +If the #GTree contains only one root node the height is 1. +If the root node has children the height is 2, etc. + + +@tree: a #GTree. +@Returns: the height of the #GTree. + + + + +Gets the value corresponding to the given key. +Since a #GTree is automatically balanced as key/value pairs are +added, key lookup is very fast. + + +@tree: a #GTree. +@key: the key to look up. +@Returns: the value corresponding to the key. + + + + +Searches a #GTree using an alternative form of the comparison function. + + +This function is not as useful as it sounds. +It allows you to use a different function for performing the lookup of +a key. However, since the tree is ordered according to the @key_compare_func +function passed to g_tree_new(), the function you pass to g_tree_search() must +return exactly the same value as would be returned by the comparison function, +for each pair of tree nodes, or the search will not work. + + +To search for a specific value, you can use g_tree_traverse(). + + +@tree: a #GTree. +@search_func: the comparison function used to search the #GTree. +@data: the data passed as the second argument to the @search_func function. +@Returns: the value corresponding to the found key, or NULL if the key is +not found. + + + + +Specifies the type of function passed to g_tree_search(). + + +@key: a key from a #GTree. +@data: the data to compare with the key. +@Returns: 0 if the desired key has been found, a negative number if the +desired key comes before @key in the sort order of the #GTree, or a positive +value if the desired key comes after @key. + + + + +Calls the given function for each node in the GTree. + + +@tree: a #GTree. +@traverse_func: the function to call for each node visited. If this function +returns TRUE, the traversal is stopped. +@traverse_type: the order in which nodes are visited, one of %G_IN_ORDER, +%G_PRE_ORDER and %G_POST_ORDER. +@data: user data to pass to the traverse function. + + + + +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. + + +@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. + + + + +Specifies the type of traveral performed by g_tree_traverse(), +g_node_traverse() and g_node_find(). + + +%G_PRE_ORDER visits a node, then its children. + + +%G_IN_ORDER vists a node's left child first, then the node itself, then its +right child. This is the one to use if you want the output sorted according +to the compare function. + + +%G_POST_ORDER visits the node's children, then the node itself. + + +%G_LEVEL_ORDER is not implemented for +Balanced Binary Trees. +For N-ary Trees +it calls the function for each child of the node, then it recursively visits +each child. + + + + +@G_IN_ORDER: +@G_PRE_ORDER: +@G_POST_ORDER: +@G_LEVEL_ORDER: + + + +Removes a key/value pair from a #GTree. +If the key or value is dynamically allocated you must remember to free them +yourself. + + +@tree: a #GTree. +@key: the key to remove. + + + + +Destroys the #GTree, freeing all of the memory allocated. +But it doesn't free keys or values. + + +@tree: a #GTree. + + diff --git a/docs/reference/glib/tmpl/trees-nary.sgml b/docs/reference/glib/tmpl/trees-nary.sgml new file mode 100644 index 00000000..d4568312 --- /dev/null +++ b/docs/reference/glib/tmpl/trees-nary.sgml @@ -0,0 +1,493 @@ + +N-ary Trees + + +trees of data with any number of branches. + + + +The #GNode struct and its associated functions provide a N-ary tree data +structure, where nodes in the tree can contain arbitrary data. + + +To create a new tree use g_node_new(). + + +To insert a node into a tree use g_node_insert(), g_node_insert_before(), +g_node_append() and g_node_prepend(). + + +To create a new node and insert it into a tree use g_node_insert_data(), +g_node_insert_data_before(), g_node_append_data() and g_node_prepend_data(). + + +To reverse the children of a node use g_node_reverse_children(). + + +To find a node use g_node_get_root(), g_node_find(), g_node_find_child(), +g_node_child_index(), g_node_child_position(), +g_node_first_child(), g_node_last_child(), +g_node_nth_child(), g_node_first_sibling(), g_node_prev_sibling(), +g_node_next_sibling() or g_node_last_sibling(). + + +To get information about a node or tree use G_NODE_IS_LEAF(), +G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(), g_node_n_children(), +g_node_is_ancestor() or g_node_max_height(). + + +To traverse a tree, calling a function for each node visited in the +traversal, use g_node_traverse() or g_node_children_foreach(). + + +To remove a node or subtree from a tree use g_node_unlink() or +g_node_destroy(). + + + + + + + + + +The #GNode struct represents one node in a +N-ary Tree. +The data field contains the actual data of the node. +The next and prev +fields point to the node's siblings (a sibling is another #GNode with the +same parent). +The parent field points to the parent of the #GNode, +or is NULL if the #GNode is the root of the tree. +The children field points to the first child of the +#GNode. The other children are accessed by using the +next pointer of each child. + + +@data: +@next: +@prev: +@parent: +@children: + + + +Creates a new #GNode containing the given data. +Used to create the first node in a tree. + + +@data: the data of the new node. +@Returns: a new #GNode. + + + + +Inserts a #GNode beneath the parent at the given position. + + +@parent: the #GNode to place @node under. +@position: the position to place @node at, with respect to its siblings. +If position is -1, @node is inserted as the last child of @parent. +@node: the #GNode to insert. +@Returns: the inserted #GNode. + + + + +Inserts a #GNode beneath the parent before the given sibling. + + +@parent: the #GNode to place @node under. +@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. + + + + +Inserts a #GNode as the last child of the given parent. + + +@parent: the #GNode to place the new #GNode under. +@node: the #GNode to insert. +@Returns: the inserted #GNode. + + + + +Inserts a #GNode as the first child of the given parent. + + +@parent: the #GNode to place the new #GNode under. +@node: the #GNode to insert. +@Returns: the inserted #GNode. + + + + +Inserts a new #GNode at the given position. + + +@parent: the #GNode to place the new #GNode under. +@position: the position to place the new #GNode at. +If position is -1, the new #GNode is inserted as the last child of @parent. +@data: the data for the new #GNode. +@Returns: the new #GNode. + + + + +Inserts a new #GNode before the given sibling. + + +@parent: the #GNode to place the new #GNode under. +@sibling: the sibling #GNode to place the new #GNode before. +@data: the data for the new #GNode. +@Returns: the new #GNode. + + + + +Inserts a new #GNode as the last child of the given parent. + + +@parent: the #GNode to place the new #GNode under. +@data: the data for the new #GNode. +@Returns: the new #GNode. + + + + +Inserts a new #GNode as the first child of the given parent. + + +@parent: the #GNode to place the new #GNode under. +@data: the data for the new #GNode. +@Returns: the new #GNode. + + + + +Reverses the order of the children of a #GNode. +(It doesn't change the order of the grandchildren.) + + +@node: a #GNode. + + + + +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. + + +@root: the root #GNode of the tree to traverse. +@order: the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER, +%G_POST_ORDER, or %G_LEVEL_ORDER. +@flags: which types of children are to be visited, one of %G_TRAVERSE_ALL, +%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS. +@max_depth: the maximum depth of the traversal. Nodes below this +depth will not be visited. If max_depth is -1 all nodes in the tree are +visited. If depth is 1, only the root is visited. If depth is 2, the root +and its children are visited. And so on. +@func: the function to call for each visited #GNode. +@data: user data to pass to the function. + + + + +Specifies which nodes are visited during several of the tree functions, +including g_node_traverse() and g_node_find(). + + +%G_TRAVERSE_LEAFS specifies that only leaf nodes should be visited. + + +%G_TRAVERSE_NON_LEAFS specifies that only non-leaf nodes should be visited. + + +%G_TRAVERSE_ALL specifies that all nodes should be visited. + + + + +@G_TRAVERSE_LEAFS: +@G_TRAVERSE_NON_LEAFS: +@G_TRAVERSE_ALL: +@G_TRAVERSE_MASK: + + + +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. + + +@node: a #GNode. +@data: user data passed to g_node_traverse(). +@Returns: TRUE to stop the traversal. + + + + +Calls a function for each of the children of a #GNode. +Note that it doesn't descend beneath the child nodes. + + +@node: a #GNode. +@flags: which types of children are to be visited, one of %G_TRAVERSE_ALL, +%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS. +@func: the function to call for each visited node. +@data: user data to pass to the function. + + + + +Specifies the type of function passed to g_node_children_foreach(). +The function is called with each child node, together with the user data +passed to g_node_children_foreach(). + + +@node: a #GNode. +@data: user data passed to g_node_children_foreach(). + + + + +Gets the root of a tree. + + +@node: a #GNode. +@Returns: the root of the tree. + + + + +Finds a #GNode in a tree. + + +@root: the root #GNode of the tree to search. +@order: the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER, +%G_POST_ORDER, or %G_LEVEL_ORDER. +@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. + + + + +Finds the first child of a #GNode with the given data. + + +@node: a #GNode. +@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. + + + + +Gets the position of the first child of a #GNode which contains the given data. + + +@node: a #GNode. +@data: the data to find. +@Returns: the index of the child of @node which contains @data, or -1 +if the data is not found. + + + + +Gets the position of a #GNode with respect to its siblings. +@child must be a child of @node. +The first child is numbered 0, the second 1, and so on. + + +@node: a #GNode. +@child: a child of @node. +@Returns: the position of @child with respect to its siblings. + + + + +Gets the first child of a #GNode. + + +@node: a #GNode. +@Returns: the last child of @node, or NULL if @node is NULL or has no children. + + + + +Gets the last child of a #GNode. + + +@node: a #GNode (must not be NULL). +@Returns: the last child of @node, or NULL if @node has no children. + + + + +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. + + +@node: a #GNode. +@n: the index of the desired child. +@Returns: the child of @node at index @n. + + + + +Gets the first sibling of a #GNode. +This could possibly be the node itself. + + +@node: a #GNode. +@Returns: the first sibling of @node. + + + + +Gets the next sibling of a #GNode. + + +@node: a #GNode. +@Returns: the next sibling of @node, or NULL if @node is NULL. + + + + +Gets the previous sibling of a #GNode. + + +@node: a #GNode. +@Returns: the previous sibling of @node, or NULL if @node is NULL. + + + + +Gets the last sibling of a #GNode. +This could possibly be the node itself. + + +@node: a #GNode. +@Returns: the last sibling of @node. + + + + +Returns TRUE if a #GNode is a leaf node. + + +@node: a #GNode. +@Returns: TRUE if the #GNode is a leaf node (i.e. it has no children). + + + + +Returns TRUE if a #GNode is the root of a tree. + + +@node: a #GNode. +@Returns: TRUE if the #GNode is the root of a tree (i.e. it has no parent +or siblings). + + + + +Gets the depth of a #GNode. + + +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. + + +@node: a #GNode. +@Returns: the depth of the #GNode. + + + + +Gets the number of nodes in a tree. + + +@root: a #GNode. +@flags: which types of children are to be counted, one of %G_TRAVERSE_ALL, +%G_TRAVERSE_LEAFS and %G_TRAVERSE_NON_LEAFS. +@Returns: the number of nodes in the tree. + + + + +Gets the number of children of a #GNode. + + +@node: a #GNode. +@Returns: the number of children of @node. + + + + +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. + + +@node: a #GNode. +@descendant: a #GNode. +@Returns: TRUE if @node is an ancestor of @descendant. + + + + +Gets the maximum height of all branches beneath a #GNode. +This is the maximum distance from the #GNode to all leaf nodes. + + +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. + + +@root: a #GNode. +@Returns: the maximum height of the tree beneath @root. + + + + +Unlinks a #GNode from a tree, resulting in two separate trees. + + +@node: the #GNode to unlink, which becomes the root of a new tree. + + + + +Removes the #GNode and its children from the tree, freeing any memory +allocated. + + +@root: the root of the tree/subtree to destroy. + + + + + + + + + + + + + + +@allocator: + + diff --git a/docs/reference/glib/tmpl/type_conversion.sgml b/docs/reference/glib/tmpl/type_conversion.sgml new file mode 100644 index 00000000..45138be5 --- /dev/null +++ b/docs/reference/glib/tmpl/type_conversion.sgml @@ -0,0 +1,78 @@ + +Type Conversion Macros + + +a portable method for storing #gint & #guint values in #gpointer variables. + + + +These macros provide a portable method of storing #gint and #guint values in +#gpointer variables. + + +Many of the GLib data types are based on storing #gpointer values, +e.g. #GHashTable, #GList, #GSList, #GTree, and #GNode. +By using the type conversion macros described below you can store #gint and +#guint values inside a #gpointer. So you can, for example, create +a hash table of #gint values, or a linked list of #guint values. + + +The type conversion macros are necessary because the size of a #gpointer can +vary across different platforms. So the type conversion has to be done +carefully. + + +Note that the reverse operation, storing #gpointer values in +integer variables, is not supported, since an integer is not guaranteed to +be large enough to store #gpointer values across all platforms. + + +To convert an integer value, a #gint, to a #gpointer, use #GINT_TO_POINTER. +To convert it back to a #gint, use #GPOINTER_TO_INT. + + +To convert an unsigned integer, a #guint, to a #gpointer, use +#GUINT_TO_POINTER. To convert it back to a #guint, use #GPOINTER_TO_UINT. + + + + + + + + + +Converts a #gint to a #gpointer. + + +@i: a #gint value. +@Returns: the value converted to a #gpointer. + + + + +Converts a #gpointer to a #gint. + + +@p: a #gpointer value. +@Returns: the value converted to a #gint. + + + + +Converts a #guint to a #gpointer. + + +@u: a #guint value. +@Returns: the value converted to a #gpointer. + + + + +Converts a #gpointer to a #guint. + + +@p: a #gpointer value. +@Returns: the value converted to a #guint. + + diff --git a/docs/reference/glib/tmpl/types.sgml b/docs/reference/glib/tmpl/types.sgml new file mode 100644 index 00000000..b3d63a40 --- /dev/null +++ b/docs/reference/glib/tmpl/types.sgml @@ -0,0 +1,216 @@ + +Basic Types + + +standard GLib types, defined for ease-of-use and portability. + + + +GLib defines a number of commonly used types, which can be divided into +4 groups: + + + +New types which are not part of standard C - #gboolean, #gsize, #gssize. + + + +Integer types which are guaranteed to be the same size across all platforms - +#gint8, #guint8, #gint16, #guint16, #gint32, #guint32, #gint64, #guint64. + + + +Types which are easier to use than their standard C counterparts - +#gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong. + + + +Types which correspond exactly to standard C types, but are included +for completeness - #gchar, #gint, #gshort, #glong, #gfloat, #gdouble. + + + + + + + + + + + + +A standard boolean type. +Variables of this type should only contain the value #TRUE or #FALSE. + + + + + +An untyped pointer. +#gpointer looks better and is easier to use than void*. + + + + + +An untyped pointer to constant data. +The data pointed to should not be changed. + + +This is typically used in function prototypes to indicate that the +data pointed to will not be altered by the function. + + + + + +Corresponds to the standard C char type. + + + + + +Corresponds to the standard C unsigned char type. + + + + + +Corresponds to the standard C int type. +Values of this type can range from #G_MININT to #G_MAXINT. + + + + + +Corresponds to the standard C unsigned int type. + + + + + +Corresponds to the standard C short type. +Values of this type can range from #G_MINSHORT to #G_MAXSHORT. + + + + + +Corresponds to the standard C unsigned short type. + + + + + +Corresponds to the standard C long type. +Values of this type can range from #G_MINLONG to #G_MAXLONG. + + + + + +Corresponds to the standard C unsigned long type. + + + + + +A signed integer guaranteed to be 8 bits on all platforms. +Values of this type can range from -128 to 127. + + + + + +An unsigned integer guaranteed to be 8 bits on all platforms. +Values of this type can range from 0 to 255. + + + + + +A signed integer guaranteed to be 16 bits on all platforms. +Values of this type can range from -32,768 to 32,767. + + + + + +An unsigned integer guaranteed to be 16 bits on all platforms. +Values of this type can range from 0 to 65,535. + + + + + +A signed integer guaranteed to be 32 bits on all platforms. +Values of this type can range from -2,147,483,648 to 2,147,483,647. + + + + + +An unsigned integer guaranteed to be 32 bits on all platforms. +Values of this type can range from 0 to 4,294,967,295. + + + + + +This macro is defined if 64-bit signed and unsigned integers are available +on the platform. + + + + + + +A signed integer guaranteed to be 64 bits on all platforms on which it is +available (see #G_HAVE_GINT64). +Values of this type can range from -9,223,372,036,854,775,808 to +9,223,372,036,854,775,807. + + + + + +An unsigned integer guaranteed to be 64 bits on all platforms on which it is +available (see #G_HAVE_GINT64). +Values of this type can range from 0 to 18,446,744,073,709,551,615. + + + + + +This macro is used to insert 64-bit integer literals into the source code. + + +@val: a literal integer value, e.g. 0x1d636b02300a7aa7U. + + + + +Corresponds to the standard C float type. +Values of this type can range from #G_MINFLOAT to #G_MAXFLOAT. + + + + + +Corresponds to the standard C double type. +Values of this type can range from #G_MINDOUBLE to #G_MAXDOUBLE. + + + + + +An unsigned 32-bit integer intended to represent sizes of data structures. + + + + + +A signed 32-bit integer intended to represent sizes of data structures. + + + diff --git a/docs/reference/glib/tmpl/warnings.sgml b/docs/reference/glib/tmpl/warnings.sgml new file mode 100644 index 00000000..2cca1526 --- /dev/null +++ b/docs/reference/glib/tmpl/warnings.sgml @@ -0,0 +1,187 @@ + +Message Output and Debugging Functions + + +functions to output messages and help debug applications. + + + +These functions provide support for outputting messages. + + + + + + + + + +Outputs a formatted message via the print handler. +The default print handler simply outputs the message to stdout. + + +g_print() should not be used from within libraries for debugging messages, +since it may be redirected by applications to special purpose message +windows or even files. +Instead, libraries should use g_log(), or the convenience functions +g_message(), g_warning() and g_error(). + + +@format: the message format. See the printf() +documentation. +@Varargs: the parameters to insert into the format string. + + + + +Sets the print handler. +Any messages passed to g_print() will be output via the new handler. +The default handler simply outputs the message to stdout. +By providing your own handler you can redirect the output, to a GTK +widget or a log file for example. + + +@func: the new print handler. +@Returns: the old print handler. + + + + +Specifies the type of the print handler functions. +These are called with the complete formatted string to output. + + +@string: the message to be output. + + + + +Outputs a formatted message via the error message handler. +The default handler simply outputs the message to stderr. + + +g_printerr() should not be used from within libraries. Instead g_log() should +be used, or the convenience functions g_message(), g_warning() and g_error(). + + +@format: the message format. See the printf() +documentation. +@Varargs: the parameters to insert into the format string. + + + + +Sets the handler for printing error messages. +Any messages passed to g_printerr() will be output via the new handler. +The default handler simply outputs the message to stderr. +By providing your own handler you can redirect the output, to a GTK +widget or a log file for example. + + +@func: the new error message handler. +@Returns: the old error message handler. + + + + +Returns from the current function if the expression is not true. +If the expression evaluates to FALSE, a critical message is logged and +the function returns. This can only be used in functions which do not return +a value. + + +@expr: the expression to check. + + + + +Returns from the current function, returning the value @val, if the expression +is not true. +If the expression evaluates to FALSE, a critical message is logged and +@val is returned. + + +@expr: the expression to check. +@val: the value to return from the current function if the expression is not +true. + + + + +Debugging macro to terminate the application if the assertion fails. +If the assertion fails (i.e. the expression is not true), an error message +is logged and the application is terminated. + + +The macro can be turned off in final releases of code by defining +G_DISABLE_ASSERT when compiling the application. + + +@expr: the expression to check. + + + + +Debugging macro to terminate the application if it is ever reached. +If it is reached, an error message is logged and the application is terminated. + + +The macro can be turned off in final releases of code by defining +G_DISABLE_ASSERT when compiling the application. + + + + + + +Prompts the user with "[E]xit, [H]alt, show [S]tack trace or [P]roceed". +This function is intended to be used for debugging use only. +FIXME: How do you set it up? + + +If Exit is selected, the application terminates with a call to +_exit(0). + + +If Halt is selected, the application enters an infinite loop. +The infinite loop can only be stopped by killing the application, +or by setting glib_on_error_halt to FALSE (possibly via a debugger). + + +If Stack trace is selected, g_on_error_stack_trace() is called. This +invokes gdb, which attaches to the current process and shows a stack trace. +The prompt is then shown again. + + +If Proceed is selected, the function returns. + + +This function may cause different actions on non-unix platforms. + + +@prg_name: the program name, needed by gdb for the [S]tack trace option. +If @prg_name is NULL, g_get_prgname() is called to get the program name +(which will work correctly if gdk_init() or gtk_init() has been called). + + + + +Invokes gdb, which attaches to the current process and shows a stack trace. +Called by g_on_error_query() when the [S]tack trace option is selected. + + +This function may cause different actions on non-unix platforms. + + +@prg_name: the program name, needed by gdb for the [S]tack trace option. +If @prg_name is NULL, g_get_prgname() is called to get the program name +(which will work correctly if gdk_init() or gtk_init() has been called). + + + + +Inserts a breakpoint instruction into the code (on x86 machines only). + + + + diff --git a/docs/reference/glib/tmpl/windows.sgml b/docs/reference/glib/tmpl/windows.sgml new file mode 100644 index 00000000..475782f8 --- /dev/null +++ b/docs/reference/glib/tmpl/windows.sgml @@ -0,0 +1,170 @@ + +Windows Compatability Functions + + +functions to support portability to the Windows environment. + + + +These functions and macros are provided in the GLib library when compiled +on the Windows platform. + + +Many of the macros simply rename available windows functions +so that they use the same name as the standard Unix functions. +This means that code written for the Unix platform will work without change +under Windows. + + +A few additional constants, types, and functions are also provided, +to provide a common base set of functions across both the Unix and Windows +environments. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +@phandles: + + + + + + + + + + + + + + + + + + + + + + + + + + + + +@fd: +@size: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -- 2.34.1