Main Page | Class List | Directories | File List | Class Members | File Members

glib.h

Go to the documentation of this file.
00001 /* GLIB - Library of useful routines for C programming
00002  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
00003  *
00004  * This library is free software; you can redistribute it and/or
00005  * modify it under the terms of the GNU Library General Public
00006  * License as published by the Free Software Foundation; either
00007  * version 2 of the License, or (at your option) any later version.
00008  *
00009  * This library is distributed in the hope that it will be useful,
00010  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00011  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00012  * Library General Public License for more details.
00013  *
00014  * You should have received a copy of the GNU Library General Public
00015  * License along with this library; if not, write to the
00016  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
00017  * Boston, MA 02111-1307, USA.
00018  */
00019 
00020 /*
00021  * Modified by the GLib Team and others 1997-1999.  See the AUTHORS
00022  * file for a list of people on the GLib Team.  See the ChangeLog
00023  * files for a list of changes.  These files are distributed with
00024  * GLib at ftp://ftp.gtk.org/pub/gtk/. 
00025  */
00026 
00027 #ifndef __G_LIB_H__
00028 #define __G_LIB_H__
00029 
00030 /* system specific config file glibconfig.h provides definitions for
00031  * the extrema of many of the standard types. These are:
00032  *
00033  *  G_MINSHORT, G_MAXSHORT
00034  *  G_MININT, G_MAXINT
00035  *  G_MINLONG, G_MAXLONG
00036  *  G_MINFLOAT, G_MAXFLOAT
00037  *  G_MINDOUBLE, G_MAXDOUBLE
00038  *
00039  * It also provides the following typedefs:
00040  *
00041  *  gint8, guint8
00042  *  gint16, guint16
00043  *  gint32, guint32
00044  *  gint64, guint64
00045  *
00046  * It defines the G_BYTE_ORDER symbol to one of G_*_ENDIAN (see later in
00047  * this file). 
00048  *
00049  * And it provides a way to store and retrieve a `gint' in/from a `gpointer'.
00050  * This is useful to pass an integer instead of a pointer to a callback.
00051  *
00052  *  GINT_TO_POINTER(i), GUINT_TO_POINTER(i)
00053  *  GPOINTER_TO_INT(p), GPOINTER_TO_UINT(p)
00054  *
00055  * Finally, it provide the following wrappers to STDC functions:
00056  *
00057  *  g_ATEXIT
00058  *    To register hooks which are executed on exit().
00059  *    Usually a wrapper for STDC atexit.
00060  *
00061  *  void *g_memmove(void *dest, const void *src, guint count);
00062  *    A wrapper for STDC memmove, or an implementation, if memmove doesn't
00063  *    exist.  The prototype looks like the above, give or take a const,
00064  *    or size_t.
00065  */
00066 #include <glibconfig.h>
00067 
00068 /* include varargs functions for assertment macros
00069  */
00070 #include <stdarg.h>
00071 
00072 /* optionally feature DMALLOC memory allocation debugger
00073  */
00074 #ifdef USE_DMALLOC
00075 #include "dmalloc.h"
00076 #endif
00077 
00078 
00079 #ifdef NATIVE_WIN32
00080 
00081 /* On native Win32, directory separator is the backslash, and search path
00082  * separator is the semicolon.
00083  */
00084 #define G_DIR_SEPARATOR '\\'
00085 #define G_DIR_SEPARATOR_S "\\"
00086 #define G_SEARCHPATH_SEPARATOR ';'
00087 #define G_SEARCHPATH_SEPARATOR_S ";"
00088 
00089 #else  /* !NATIVE_WIN32 */
00090 
00091 #ifndef __EMX__
00092 /* Unix */
00093 
00094 #define G_DIR_SEPARATOR '/'
00095 #define G_DIR_SEPARATOR_S "/"
00096 #define G_SEARCHPATH_SEPARATOR ':'
00097 #define G_SEARCHPATH_SEPARATOR_S ":"
00098 
00099 #else
00100 /* EMX/OS2 */
00101 
00102 #define G_DIR_SEPARATOR '/'
00103 #define G_DIR_SEPARATOR_S "/"
00104 #define G_SEARCHPATH_SEPARATOR ';'
00105 #define G_SEARCHPATH_SEPARATOR_S ";"
00106 
00107 #endif
00108 
00109 #endif /* !NATIVE_WIN32 */
00110 
00111 #ifdef __cplusplus
00112 extern "C" {
00113 #endif /* __cplusplus */
00114 
00115 
00116 /* Provide definitions for some commonly used macros.
00117  *  Some of them are only provided if they haven't already
00118  *  been defined. It is assumed that if they are already
00119  *  defined then the current definition is correct.
00120  */
00121 #ifndef NULL
00122 #define NULL    ((void*) 0)
00123 #endif
00124 
00125 #ifndef FALSE
00126 #define FALSE   (0)
00127 #endif
00128 
00129 #ifndef TRUE
00130 #define TRUE    (!FALSE)
00131 #endif
00132 
00133 #undef  MAX
00134 #define MAX(a, b)  (((a) > (b)) ? (a) : (b))
00135 
00136 #undef  MIN
00137 #define MIN(a, b)  (((a) < (b)) ? (a) : (b))
00138 
00139 #undef  ABS
00140 #define ABS(a)     (((a) < 0) ? -(a) : (a))
00141 
00142 #undef  CLAMP
00143 #define CLAMP(x, low, high)  (((x) > (high)) ? (high) : (((x) < (low)) ? (low) : (x)))
00144 
00145 
00146 /* Define G_VA_COPY() to do the right thing for copying va_list variables.
00147  * glibconfig.h may have already defined G_VA_COPY as va_copy or __va_copy.
00148  */
00149 #if !defined (G_VA_COPY)
00150 #  if defined (__GNUC__) && defined (__PPC__) && (defined (_CALL_SYSV) || defined (_WIN32))
00151 #  define G_VA_COPY(ap1, ap2)     (*(ap1) = *(ap2))
00152 #  elif defined (G_VA_COPY_AS_ARRAY)
00153 #  define G_VA_COPY(ap1, ap2)     g_memmove ((ap1), (ap2), sizeof (va_list))
00154 #  else /* va_list is a pointer */
00155 #  define G_VA_COPY(ap1, ap2)     ((ap1) = (ap2))
00156 #  endif /* va_list is a pointer */
00157 #endif /* !G_VA_COPY */
00158 
00159 
00160 /* Provide convenience macros for handling structure
00161  * fields through their offsets.
00162  */
00163 #define G_STRUCT_OFFSET(struct_type, member)    \
00164     ((gulong) ((gchar*) &((struct_type*) 0)->member))
00165 #define G_STRUCT_MEMBER_P(struct_p, struct_offset)   \
00166     ((gpointer) ((gchar*) (struct_p) + (gulong) (struct_offset)))
00167 #define G_STRUCT_MEMBER(member_type, struct_p, struct_offset)   \
00168     (*(member_type*) G_STRUCT_MEMBER_P ((struct_p), (struct_offset)))
00169 
00170 
00171 /* inlining hassle. for compilers that don't allow the `inline' keyword,
00172  * mostly because of strict ANSI C compliance or dumbness, we try to fall
00173  * back to either `__inline__' or `__inline'.
00174  * we define G_CAN_INLINE, if the compiler seems to be actually
00175  * *capable* to do function inlining, in which case inline function bodys
00176  * do make sense. we also define G_INLINE_FUNC to properly export the
00177  * function prototypes if no inlining can be performed.
00178  * we special case most of the stuff, so inline functions can have a normal
00179  * implementation by defining G_INLINE_FUNC to extern and G_CAN_INLINE to 1.
00180  */
00181 #ifndef G_INLINE_FUNC
00182 #  define G_CAN_INLINE 1
00183 #endif
00184 #ifdef G_HAVE_INLINE
00185 #  if defined (__GNUC__) && defined (__STRICT_ANSI__)
00186 #    undef inline
00187 #    define inline __inline__
00188 #  endif
00189 #else /* !G_HAVE_INLINE */
00190 #  undef inline
00191 #  if defined (G_HAVE___INLINE__)
00192 #    define inline __inline__
00193 #  else /* !inline && !__inline__ */
00194 #    if defined (G_HAVE___INLINE)
00195 #      define inline __inline
00196 #    else /* !inline && !__inline__ && !__inline */
00197 #      define inline /* don't inline, then */
00198 #      ifndef G_INLINE_FUNC
00199 #        undef G_CAN_INLINE
00200 #      endif
00201 #    endif
00202 #  endif
00203 #endif
00204 #ifndef G_INLINE_FUNC
00205 #  ifdef __GNUC__
00206 #    ifdef __OPTIMIZE__
00207 #      define G_INLINE_FUNC extern inline
00208 #    else
00209 #      undef G_CAN_INLINE
00210 #      define G_INLINE_FUNC extern
00211 #    endif
00212 #  else /* !__GNUC__ */
00213 #    ifdef G_CAN_INLINE
00214 #      define G_INLINE_FUNC static inline
00215 #    else
00216 #      define G_INLINE_FUNC extern
00217 #    endif
00218 #  endif /* !__GNUC__ */
00219 #endif /* !G_INLINE_FUNC */
00220 
00221 
00222 /* Provide simple macro statement wrappers (adapted from Perl):
00223  *  G_STMT_START { statements; } G_STMT_END;
00224  *  can be used as a single statement, as in
00225  *  if (x) G_STMT_START { ... } G_STMT_END; else ...
00226  *
00227  *  For gcc we will wrap the statements within `({' and `})' braces.
00228  *  For SunOS they will be wrapped within `if (1)' and `else (void) 0',
00229  *  and otherwise within `do' and `while (0)'.
00230  */
00231 #if !(defined (G_STMT_START) && defined (G_STMT_END))
00232 #  if defined (__GNUC__) && !defined (__STRICT_ANSI__) && !defined (__cplusplus)
00233 #    define G_STMT_START        (void)(
00234 #    define G_STMT_END          )
00235 #  else
00236 #    if (defined (sun) || defined (__sun__))
00237 #      define G_STMT_START      if (1)
00238 #      define G_STMT_END        else (void)0
00239 #    else
00240 #      define G_STMT_START      do
00241 #      define G_STMT_END        while (0)
00242 #    endif
00243 #  endif
00244 #endif
00245 
00246 
00247 /* Provide macros to feature the GCC function attribute.
00248  */
00249 #if     __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 4)
00250 #define G_GNUC_PRINTF( format_idx, arg_idx )    \
00251   __attribute__((format (printf, format_idx, arg_idx)))
00252 #define G_GNUC_SCANF( format_idx, arg_idx )     \
00253   __attribute__((format (scanf, format_idx, arg_idx)))
00254 #define G_GNUC_FORMAT( arg_idx )                \
00255   __attribute__((format_arg (arg_idx)))
00256 #define G_GNUC_NORETURN                         \
00257   __attribute__((noreturn))
00258 #define G_GNUC_CONST                            \
00259   __attribute__((const))
00260 #define G_GNUC_UNUSED                           \
00261   __attribute__((unused))
00262 #else   /* !__GNUC__ */
00263 #define G_GNUC_PRINTF( format_idx, arg_idx )
00264 #define G_GNUC_SCANF( format_idx, arg_idx )
00265 #define G_GNUC_FORMAT( arg_idx )
00266 #define G_GNUC_NORETURN
00267 #define G_GNUC_CONST
00268 #define G_GNUC_UNUSED
00269 #endif  /* !__GNUC__ */
00270 
00271 
00272 /* Wrap the gcc __PRETTY_FUNCTION__ and __FUNCTION__ variables with
00273  * macros, so we can refer to them as strings unconditionally.
00274  */
00275 #ifdef  __GNUC__
00276 #define G_GNUC_FUNCTION         __FUNCTION__
00277 #define G_GNUC_PRETTY_FUNCTION  __PRETTY_FUNCTION__
00278 #else   /* !__GNUC__ */
00279 #define G_GNUC_FUNCTION         ""
00280 #define G_GNUC_PRETTY_FUNCTION  ""
00281 #endif  /* !__GNUC__ */
00282 
00283 /* we try to provide a usefull equivalent for ATEXIT if it is
00284  * not defined, but use is actually abandoned. people should
00285  * use g_atexit() instead.
00286  */
00287 #ifndef ATEXIT
00288 # define ATEXIT(proc)   g_ATEXIT(proc)
00289 #else
00290 # define G_NATIVE_ATEXIT
00291 #endif /* ATEXIT */
00292 
00293 /* Hacker macro to place breakpoints for elected machines.
00294  * Actual use is strongly deprecated of course ;)
00295  */
00296 #if defined (__i386__) && defined (__GNUC__) && __GNUC__ >= 2
00297 #define G_BREAKPOINT()          G_STMT_START{ __asm__ __volatile__ ("int $03"); }G_STMT_END
00298 #elif defined (__alpha__) && defined (__GNUC__) && __GNUC__ >= 2
00299 #define G_BREAKPOINT()          G_STMT_START{ __asm__ __volatile__ ("bpt"); }G_STMT_END
00300 #else   /* !__i386__ && !__alpha__ */
00301 #define G_BREAKPOINT()
00302 #endif  /* __i386__ */
00303 
00304 
00305 /* Provide macros for easily allocating memory. The macros
00306  *  will cast the allocated memory to the specified type
00307  *  in order to avoid compiler warnings. (Makes the code neater).
00308  */
00309 
00310 #ifdef __DMALLOC_H__
00311 #  define g_new(type, count)            (ALLOC (type, count))
00312 #  define g_new0(type, count)           (CALLOC (type, count))
00313 #  define g_renew(type, mem, count)     (REALLOC (mem, type, count))
00314 #else /* __DMALLOC_H__ */
00315 #  define g_new(type, count)      \
00316       ((type *) g_malloc ((unsigned) sizeof (type) * (count)))
00317 #  define g_new0(type, count)     \
00318       ((type *) g_malloc0 ((unsigned) sizeof (type) * (count)))
00319 #  define g_renew(type, mem, count)       \
00320       ((type *) g_realloc (mem, (unsigned) sizeof (type) * (count)))
00321 #endif /* __DMALLOC_H__ */
00322 
00323 #define g_mem_chunk_create(type, pre_alloc, alloc_type) ( \
00324   g_mem_chunk_new (#type " mem chunks (" #pre_alloc ")", \
00325                    sizeof (type), \
00326                    sizeof (type) * (pre_alloc), \
00327                    (alloc_type)) \
00328 )
00329 #define g_chunk_new(type, chunk)        ( \
00330   (type *) g_mem_chunk_alloc (chunk) \
00331 )
00332 #define g_chunk_new0(type, chunk)       ( \
00333   (type *) g_mem_chunk_alloc0 (chunk) \
00334 )
00335 #define g_chunk_free(mem, mem_chunk)    G_STMT_START { \
00336   g_mem_chunk_free ((mem_chunk), (mem)); \
00337 } G_STMT_END
00338 
00339 
00340 #define g_string(x) #x
00341 
00342 
00343 /* Provide macros for error handling. The "assert" macros will
00344  *  exit on failure. The "return" macros will exit the current
00345  *  function. Two different definitions are given for the macros
00346  *  if G_DISABLE_ASSERT is not defined, in order to support gcc's
00347  *  __PRETTY_FUNCTION__ capability.
00348  */
00349 
00350 #ifdef G_DISABLE_ASSERT
00351 
00352 #define g_assert(expr)
00353 #define g_assert_not_reached()
00354 
00355 #else /* !G_DISABLE_ASSERT */
00356 
00357 #ifdef __GNUC__
00358 
00359 #define g_assert(expr)                  G_STMT_START{           \
00360      if (!(expr))                                               \
00361        g_log (G_LOG_DOMAIN,                                     \
00362               G_LOG_LEVEL_ERROR,                                \
00363               "file %s: line %d (%s): assertion failed: (%s)",  \
00364               __FILE__,                                         \
00365               __LINE__,                                         \
00366               __PRETTY_FUNCTION__,                              \
00367               #expr);                   }G_STMT_END
00368 
00369 #define g_assert_not_reached()          G_STMT_START{           \
00370      g_log (G_LOG_DOMAIN,                                       \
00371             G_LOG_LEVEL_ERROR,                                  \
00372             "file %s: line %d (%s): should not be reached",     \
00373             __FILE__,                                           \
00374             __LINE__,                                           \
00375             __PRETTY_FUNCTION__);       }G_STMT_END
00376 
00377 #else /* !__GNUC__ */
00378 
00379 #define g_assert(expr)                  G_STMT_START{           \
00380      if (!(expr))                                               \
00381        g_log (G_LOG_DOMAIN,                                     \
00382               G_LOG_LEVEL_ERROR,                                \
00383               "file %s: line %d: assertion failed: (%s)",       \
00384               __FILE__,                                         \
00385               __LINE__,                                         \
00386               #expr);                   }G_STMT_END
00387 
00388 #define g_assert_not_reached()          G_STMT_START{   \
00389      g_log (G_LOG_DOMAIN,                               \
00390             G_LOG_LEVEL_ERROR,                          \
00391             "file %s: line %d: should not be reached",  \
00392             __FILE__,                                   \
00393             __LINE__);          }G_STMT_END
00394 
00395 #endif /* __GNUC__ */
00396 
00397 #endif /* !G_DISABLE_ASSERT */
00398 
00399 
00400 #ifdef G_DISABLE_CHECKS
00401 
00402 #define g_return_if_fail(expr)
00403 #define g_return_val_if_fail(expr,val)
00404 
00405 #else /* !G_DISABLE_CHECKS */
00406 
00407 #ifdef __GNUC__
00408 
00409 #define g_return_if_fail(expr)          G_STMT_START{                   \
00410      if (!(expr))                                                       \
00411        {                                                                \
00412          g_log (G_LOG_DOMAIN,                                           \
00413                 G_LOG_LEVEL_CRITICAL,                                   \
00414                 "file %s: line %d (%s): assertion `%s' failed.",        \
00415                 __FILE__,                                               \
00416                 __LINE__,                                               \
00417                 __PRETTY_FUNCTION__,                                    \
00418                 #expr);                                                 \
00419          return;                                                        \
00420        };                               }G_STMT_END
00421 
00422 #define g_return_val_if_fail(expr,val)  G_STMT_START{                   \
00423      if (!(expr))                                                       \
00424        {                                                                \
00425          g_log (G_LOG_DOMAIN,                                           \
00426                 G_LOG_LEVEL_CRITICAL,                                   \
00427                 "file %s: line %d (%s): assertion `%s' failed.",        \
00428                 __FILE__,                                               \
00429                 __LINE__,                                               \
00430                 __PRETTY_FUNCTION__,                                    \
00431                 #expr);                                                 \
00432          return val;                                                    \
00433        };                               }G_STMT_END
00434 
00435 #else /* !__GNUC__ */
00436 
00437 #define g_return_if_fail(expr)          G_STMT_START{           \
00438      if (!(expr))                                               \
00439        {                                                        \
00440          g_log (G_LOG_DOMAIN,                                   \
00441                 G_LOG_LEVEL_CRITICAL,                           \
00442                 "file %s: line %d: assertion `%s' failed.",     \
00443                 __FILE__,                                       \
00444                 __LINE__,                                       \
00445                 #expr);                                         \
00446          return;                                                \
00447        };                               }G_STMT_END
00448 
00449 #define g_return_val_if_fail(expr, val) G_STMT_START{           \
00450      if (!(expr))                                               \
00451        {                                                        \
00452          g_log (G_LOG_DOMAIN,                                   \
00453                 G_LOG_LEVEL_CRITICAL,                           \
00454                 "file %s: line %d: assertion `%s' failed.",     \
00455                 __FILE__,                                       \
00456                 __LINE__,                                       \
00457                 #expr);                                         \
00458          return val;                                            \
00459        };                               }G_STMT_END
00460 
00461 #endif /* !__GNUC__ */
00462 
00463 #endif /* !G_DISABLE_CHECKS */
00464 
00465 
00466 /* Provide type definitions for commonly used types.
00467  *  These are useful because a "gint8" can be adjusted
00468  *  to be 1 byte (8 bits) on all platforms. Similarly and
00469  *  more importantly, "gint32" can be adjusted to be
00470  *  4 bytes (32 bits) on all platforms.
00471  */
00472 
00473 typedef char   gchar;
00474 typedef short  gshort;
00475 typedef long   glong;
00476 typedef int    gint;
00477 typedef gint   gboolean;
00478 
00479 typedef unsigned char   guchar;
00480 typedef unsigned short  gushort;
00481 typedef unsigned long   gulong;
00482 typedef unsigned int    guint;
00483 
00484 typedef float   gfloat;
00485 typedef double  gdouble;
00486 
00487 /* HAVE_LONG_DOUBLE doesn't work correctly on all platforms.
00488  * Since gldouble isn't used anywhere, just disable it for now */
00489 
00490 #if 0
00491 #ifdef HAVE_LONG_DOUBLE
00492 typedef long double gldouble;
00493 #else /* HAVE_LONG_DOUBLE */
00494 typedef double gldouble;
00495 #endif /* HAVE_LONG_DOUBLE */
00496 #endif /* 0 */
00497 
00498 typedef void* gpointer;
00499 typedef const void *gconstpointer;
00500 
00501 
00502 typedef gint32  gssize;
00503 typedef guint32 gsize;
00504 typedef guint32 GQuark;
00505 typedef gint32  GTime;
00506 
00507 
00508 /* Portable endian checks and conversions
00509  *
00510  * glibconfig.h defines G_BYTE_ORDER which expands to one of
00511  * the below macros.
00512  */
00513 #define G_LITTLE_ENDIAN 1234
00514 #define G_BIG_ENDIAN    4321
00515 #define G_PDP_ENDIAN    3412            /* unused, need specific PDP check */   
00516 
00517 
00518 /* Basic bit swapping functions
00519  */
00520 #define GUINT16_SWAP_LE_BE_CONSTANT(val)        ((guint16) ( \
00521     (((guint16) (val) & (guint16) 0x00ffU) << 8) | \
00522     (((guint16) (val) & (guint16) 0xff00U) >> 8)))
00523 #define GUINT32_SWAP_LE_BE_CONSTANT(val)        ((guint32) ( \
00524     (((guint32) (val) & (guint32) 0x000000ffU) << 24) | \
00525     (((guint32) (val) & (guint32) 0x0000ff00U) <<  8) | \
00526     (((guint32) (val) & (guint32) 0x00ff0000U) >>  8) | \
00527     (((guint32) (val) & (guint32) 0xff000000U) >> 24)))
00528 
00529 /* Intel specific stuff for speed
00530  */
00531 #if defined (__i386__) && defined (__GNUC__) && __GNUC__ >= 2
00532 #  define GUINT16_SWAP_LE_BE_X86(val) \
00533      (__extension__                                     \
00534       ({ register guint16 __v;                          \
00535          if (__builtin_constant_p (val))                \
00536            __v = GUINT16_SWAP_LE_BE_CONSTANT (val);     \
00537          else                                           \
00538            __asm__ __const__ ("rorw $8, %w0"            \
00539                               : "=r" (__v)              \
00540                               : "0" ((guint16) (val))); \
00541         __v; }))
00542 #  define GUINT16_SWAP_LE_BE(val) (GUINT16_SWAP_LE_BE_X86 (val))
00543 #  if !defined(__i486__) && !defined(__i586__) \
00544       && !defined(__pentium__) && !defined(__i686__) && !defined(__pentiumpro__)
00545 #     define GUINT32_SWAP_LE_BE_X86(val) \
00546         (__extension__                                          \
00547          ({ register guint32 __v;                               \
00548             if (__builtin_constant_p (val))                     \
00549               __v = GUINT32_SWAP_LE_BE_CONSTANT (val);          \
00550           else                                                  \
00551             __asm__ __const__ ("rorw $8, %w0\n\t"               \
00552                                "rorl $16, %0\n\t"               \
00553                                "rorw $8, %w0"                   \
00554                                : "=r" (__v)                     \
00555                                : "0" ((guint32) (val)));        \
00556         __v; }))
00557 #  else /* 486 and higher has bswap */
00558 #     define GUINT32_SWAP_LE_BE_X86(val) \
00559         (__extension__                                          \
00560          ({ register guint32 __v;                               \
00561             if (__builtin_constant_p (val))                     \
00562               __v = GUINT32_SWAP_LE_BE_CONSTANT (val);          \
00563           else                                                  \
00564             __asm__ __const__ ("bswap %0"                       \
00565                                : "=r" (__v)                     \
00566                                : "0" ((guint32) (val)));        \
00567         __v; }))
00568 #  endif /* processor specific 32-bit stuff */
00569 #  define GUINT32_SWAP_LE_BE(val) (GUINT32_SWAP_LE_BE_X86 (val))
00570 #else /* !__i386__ */
00571 #  define GUINT16_SWAP_LE_BE(val) (GUINT16_SWAP_LE_BE_CONSTANT (val))
00572 #  define GUINT32_SWAP_LE_BE(val) (GUINT32_SWAP_LE_BE_CONSTANT (val))
00573 #endif /* __i386__ */
00574 
00575 #ifdef G_HAVE_GINT64
00576 #  define GUINT64_SWAP_LE_BE_CONSTANT(val)      ((guint64) ( \
00577       (((guint64) (val) &                                               \
00578         (guint64) G_GINT64_CONSTANT(0x00000000000000ffU)) << 56) |      \
00579       (((guint64) (val) &                                               \
00580         (guint64) G_GINT64_CONSTANT(0x000000000000ff00U)) << 40) |      \
00581       (((guint64) (val) &                                               \
00582         (guint64) G_GINT64_CONSTANT(0x0000000000ff0000U)) << 24) |      \
00583       (((guint64) (val) &                                               \
00584         (guint64) G_GINT64_CONSTANT(0x00000000ff000000U)) <<  8) |      \
00585       (((guint64) (val) &                                               \
00586         (guint64) G_GINT64_CONSTANT(0x000000ff00000000U)) >>  8) |      \
00587       (((guint64) (val) &                                               \
00588         (guint64) G_GINT64_CONSTANT(0x0000ff0000000000U)) >> 24) |      \
00589       (((guint64) (val) &                                               \
00590         (guint64) G_GINT64_CONSTANT(0x00ff000000000000U)) >> 40) |      \
00591       (((guint64) (val) &                                               \
00592         (guint64) G_GINT64_CONSTANT(0xff00000000000000U)) >> 56)))
00593 #  if defined (__i386__) && defined (__GNUC__) && __GNUC__ >= 2
00594 #    define GUINT64_SWAP_LE_BE_X86(val) \
00595         (__extension__                                          \
00596          ({ union { guint64 __ll;                               \
00597                     guint32 __l[2]; } __r;                      \
00598             if (__builtin_constant_p (val))                     \
00599               __r.__ll = GUINT64_SWAP_LE_BE_CONSTANT (val);     \
00600             else                                                \
00601               {                                                 \
00602                 union { guint64 __ll;                           \
00603                         guint32 __l[2]; } __w;                  \
00604                 __w.__ll = ((guint64) val);                     \
00605                 __r.__l[0] = GUINT32_SWAP_LE_BE (__w.__l[1]);   \
00606                 __r.__l[1] = GUINT32_SWAP_LE_BE (__w.__l[0]);   \
00607               }                                                 \
00608           __r.__ll; }))
00609 #    define GUINT64_SWAP_LE_BE(val) (GUINT64_SWAP_LE_BE_X86 (val))
00610 #  else /* !__i386__ */
00611 #    define GUINT64_SWAP_LE_BE(val) (GUINT64_SWAP_LE_BE_CONSTANT(val))
00612 #  endif
00613 #endif
00614 
00615 #define GUINT16_SWAP_LE_PDP(val)        ((guint16) (val))
00616 #define GUINT16_SWAP_BE_PDP(val)        (GUINT16_SWAP_LE_BE (val))
00617 #define GUINT32_SWAP_LE_PDP(val)        ((guint32) ( \
00618     (((guint32) (val) & (guint32) 0x0000ffffU) << 16) | \
00619     (((guint32) (val) & (guint32) 0xffff0000U) >> 16)))
00620 #define GUINT32_SWAP_BE_PDP(val)        ((guint32) ( \
00621     (((guint32) (val) & (guint32) 0x00ff00ffU) << 8) | \
00622     (((guint32) (val) & (guint32) 0xff00ff00U) >> 8)))
00623 
00624 /* The G*_TO_?E() macros are defined in glibconfig.h.
00625  * The transformation is symmetric, so the FROM just maps to the TO.
00626  */
00627 #define GINT16_FROM_LE(val)     (GINT16_TO_LE (val))
00628 #define GUINT16_FROM_LE(val)    (GUINT16_TO_LE (val))
00629 #define GINT16_FROM_BE(val)     (GINT16_TO_BE (val))
00630 #define GUINT16_FROM_BE(val)    (GUINT16_TO_BE (val))
00631 #define GINT32_FROM_LE(val)     (GINT32_TO_LE (val))
00632 #define GUINT32_FROM_LE(val)    (GUINT32_TO_LE (val))
00633 #define GINT32_FROM_BE(val)     (GINT32_TO_BE (val))
00634 #define GUINT32_FROM_BE(val)    (GUINT32_TO_BE (val))
00635 
00636 #ifdef G_HAVE_GINT64
00637 #define GINT64_FROM_LE(val)     (GINT64_TO_LE (val))
00638 #define GUINT64_FROM_LE(val)    (GUINT64_TO_LE (val))
00639 #define GINT64_FROM_BE(val)     (GINT64_TO_BE (val))
00640 #define GUINT64_FROM_BE(val)    (GUINT64_TO_BE (val))
00641 #endif
00642 
00643 #define GLONG_FROM_LE(val)      (GLONG_TO_LE (val))
00644 #define GULONG_FROM_LE(val)     (GULONG_TO_LE (val))
00645 #define GLONG_FROM_BE(val)      (GLONG_TO_BE (val))
00646 #define GULONG_FROM_BE(val)     (GULONG_TO_BE (val))
00647 
00648 #define GINT_FROM_LE(val)       (GINT_TO_LE (val))
00649 #define GUINT_FROM_LE(val)      (GUINT_TO_LE (val))
00650 #define GINT_FROM_BE(val)       (GINT_TO_BE (val))
00651 #define GUINT_FROM_BE(val)      (GUINT_TO_BE (val))
00652 
00653 
00654 /* Portable versions of host-network order stuff
00655  */
00656 #define g_ntohl(val) (GUINT32_FROM_BE (val))
00657 #define g_ntohs(val) (GUINT16_FROM_BE (val))
00658 #define g_htonl(val) (GUINT32_TO_BE (val))
00659 #define g_htons(val) (GUINT16_TO_BE (val))
00660 
00661 
00662 /* Glib version.
00663  * we prefix variable declarations so they can
00664  * properly get exported in windows dlls.
00665  */
00666 #ifdef NATIVE_WIN32
00667 #  ifdef GLIB_COMPILATION
00668 #    define GUTILS_C_VAR __declspec(dllexport)
00669 #  else /* !GLIB_COMPILATION */
00670 #    define GUTILS_C_VAR extern __declspec(dllimport)
00671 #  endif /* !GLIB_COMPILATION */
00672 #else /* !NATIVE_WIN32 */
00673 #  define GUTILS_C_VAR extern
00674 #endif /* !NATIVE_WIN32 */
00675 
00676 GUTILS_C_VAR const guint glib_major_version;
00677 GUTILS_C_VAR const guint glib_minor_version;
00678 GUTILS_C_VAR const guint glib_micro_version;
00679 GUTILS_C_VAR const guint glib_interface_age;
00680 GUTILS_C_VAR const guint glib_binary_age;
00681 
00682 #define GLIB_CHECK_VERSION(major,minor,micro)    \
00683     (GLIB_MAJOR_VERSION > (major) || \
00684      (GLIB_MAJOR_VERSION == (major) && GLIB_MINOR_VERSION > (minor)) || \
00685      (GLIB_MAJOR_VERSION == (major) && GLIB_MINOR_VERSION == (minor) && \
00686       GLIB_MICRO_VERSION >= (micro)))
00687 
00688 /* Forward declarations of glib types.
00689  */
00690 typedef struct _GAllocator      GAllocator;
00691 typedef struct _GArray          GArray;
00692 typedef struct _GByteArray      GByteArray;
00693 typedef struct _GCache          GCache;
00694 typedef struct _GCompletion     GCompletion;
00695 typedef struct _GData           GData;
00696 typedef struct _GDebugKey       GDebugKey;
00697 typedef struct _GHashTable      GHashTable;
00698 typedef struct _GHook           GHook;
00699 typedef struct _GHookList       GHookList;
00700 typedef struct _GList           GList;
00701 typedef struct _GMemChunk       GMemChunk;
00702 typedef struct _GNode           GNode;
00703 typedef struct _GPtrArray       GPtrArray;
00704 typedef struct _GRelation       GRelation;
00705 typedef struct _GScanner        GScanner;
00706 typedef struct _GScannerConfig  GScannerConfig;
00707 typedef struct _GSList          GSList;
00708 typedef struct _GString         GString;
00709 typedef struct _GStringChunk    GStringChunk;
00710 typedef struct _GTimer          GTimer;
00711 typedef struct _GTree           GTree;
00712 typedef struct _GTuples         GTuples;
00713 typedef union  _GTokenValue     GTokenValue;
00714 typedef struct _GIOChannel      GIOChannel;
00715 
00716 /* Tree traverse flags */
00717 typedef enum
00718 {
00719   G_TRAVERSE_LEAFS      = 1 << 0,
00720   G_TRAVERSE_NON_LEAFS  = 1 << 1,
00721   G_TRAVERSE_ALL        = G_TRAVERSE_LEAFS | G_TRAVERSE_NON_LEAFS,
00722   G_TRAVERSE_MASK       = 0x03
00723 } GTraverseFlags;
00724 
00725 /* Tree traverse orders */
00726 typedef enum
00727 {
00728   G_IN_ORDER,
00729   G_PRE_ORDER,
00730   G_POST_ORDER,
00731   G_LEVEL_ORDER
00732 } GTraverseType;
00733 
00734 /* Log level shift offset for user defined
00735  * log levels (0-7 are used by GLib).
00736  */
00737 #define G_LOG_LEVEL_USER_SHIFT  (8)
00738 
00739 /* Glib log levels and flags.
00740  */
00741 typedef enum
00742 {
00743   /* log flags */
00744   G_LOG_FLAG_RECURSION          = 1 << 0,
00745   G_LOG_FLAG_FATAL              = 1 << 1,
00746   
00747   /* GLib log levels */
00748   G_LOG_LEVEL_ERROR             = 1 << 2,       /* always fatal */
00749   G_LOG_LEVEL_CRITICAL          = 1 << 3,
00750   G_LOG_LEVEL_WARNING           = 1 << 4,
00751   G_LOG_LEVEL_MESSAGE           = 1 << 5,
00752   G_LOG_LEVEL_INFO              = 1 << 6,
00753   G_LOG_LEVEL_DEBUG             = 1 << 7,
00754   
00755   G_LOG_LEVEL_MASK              = ~(G_LOG_FLAG_RECURSION | G_LOG_FLAG_FATAL)
00756 } GLogLevelFlags;
00757 
00758 /* GLib log levels that are considered fatal by default */
00759 #define G_LOG_FATAL_MASK        (G_LOG_FLAG_RECURSION | G_LOG_LEVEL_ERROR)
00760 
00761 
00762 typedef gpointer        (*GCacheNewFunc)        (gpointer       key);
00763 typedef gpointer        (*GCacheDupFunc)        (gpointer       value);
00764 typedef void            (*GCacheDestroyFunc)    (gpointer       value);
00765 typedef gint            (*GCompareFunc)         (gconstpointer  a,
00766                                                  gconstpointer  b);
00767 typedef gchar*          (*GCompletionFunc)      (gpointer);
00768 typedef void            (*GDestroyNotify)       (gpointer       data);
00769 typedef void            (*GDataForeachFunc)     (GQuark         key_id,
00770                                                  gpointer       data,
00771                                                  gpointer       user_data);
00772 typedef void            (*GFunc)                (gpointer       data,
00773                                                  gpointer       user_data);
00774 typedef guint           (*GHashFunc)            (gconstpointer  key);
00775 typedef void            (*GFreeFunc)            (gpointer       data);
00776 typedef void            (*GHFunc)               (gpointer       key,
00777                                                  gpointer       value,
00778                                                  gpointer       user_data);
00779 typedef gboolean        (*GHRFunc)              (gpointer       key,
00780                                                  gpointer       value,
00781                                                  gpointer       user_data);
00782 typedef gint            (*GHookCompareFunc)     (GHook          *new_hook,
00783                                                  GHook          *sibling);
00784 typedef gboolean        (*GHookFindFunc)        (GHook          *hook,
00785                                                  gpointer        data);
00786 typedef void            (*GHookMarshaller)      (GHook          *hook,
00787                                                  gpointer        data);
00788 typedef gboolean        (*GHookCheckMarshaller) (GHook          *hook,
00789                                                  gpointer        data);
00790 typedef void            (*GHookFunc)            (gpointer        data);
00791 typedef gboolean        (*GHookCheckFunc)       (gpointer        data);
00792 typedef void            (*GHookFreeFunc)        (GHookList      *hook_list,
00793                                                  GHook          *hook);
00794 typedef void            (*GLogFunc)             (const gchar   *log_domain,
00795                                                  GLogLevelFlags log_level,
00796                                                  const gchar   *message,
00797                                                  gpointer       user_data);
00798 typedef gboolean        (*GNodeTraverseFunc)    (GNode         *node,
00799                                                  gpointer       data);
00800 typedef void            (*GNodeForeachFunc)     (GNode         *node,
00801                                                  gpointer       data);
00802 typedef gint            (*GSearchFunc)          (gpointer       key,
00803                                                  gpointer       data);
00804 typedef void            (*GScannerMsgFunc)      (GScanner      *scanner,
00805                                                  gchar         *message,
00806                                                  gint           error);
00807 typedef gint            (*GTraverseFunc)        (gpointer       key,
00808                                                  gpointer       value,
00809                                                  gpointer       data);
00810 typedef void            (*GVoidFunc)            (void);
00811 
00812 
00813 struct _GList
00814 {
00815   gpointer data;
00816   GList *next;
00817   GList *prev;
00818 };
00819 
00820 struct _GSList
00821 {
00822   gpointer data;
00823   GSList *next;
00824 };
00825 
00826 struct _GString
00827 {
00828   gchar *str;
00829   gint len;
00830 };
00831 
00832 struct _GArray
00833 {
00834   gchar *data;
00835   guint len;
00836 };
00837 
00838 struct _GByteArray
00839 {
00840   guint8 *data;
00841   guint   len;
00842 };
00843 
00844 struct _GPtrArray
00845 {
00846   gpointer *pdata;
00847   guint     len;
00848 };
00849 
00850 struct _GTuples
00851 {
00852   guint len;
00853 };
00854 
00855 struct _GDebugKey
00856 {
00857   gchar *key;
00858   guint  value;
00859 };
00860 
00861 
00862 /* Doubly linked lists
00863  */
00864 void   g_list_push_allocator    (GAllocator     *allocator);
00865 void   g_list_pop_allocator     (void);
00866 GList* g_list_alloc             (void);
00867 void   g_list_free              (GList          *list);
00868 void   g_list_free_1            (GList          *list);
00869 GList* g_list_append            (GList          *list,
00870                                  gpointer        data);
00871 GList* g_list_prepend           (GList          *list,
00872                                  gpointer        data);
00873 GList* g_list_insert            (GList          *list,
00874                                  gpointer        data,
00875                                  gint            position);
00876 GList* g_list_insert_sorted     (GList          *list,
00877                                  gpointer        data,
00878                                  GCompareFunc    func);
00879 GList* g_list_concat            (GList          *list1,
00880                                  GList          *list2);
00881 GList* g_list_remove            (GList          *list,
00882                                  gpointer        data);
00883 GList* g_list_remove_link       (GList          *list,
00884                                  GList          *llink);
00885 GList* g_list_reverse           (GList          *list);
00886 GList* g_list_copy              (GList          *list);
00887 GList* g_list_nth               (GList          *list,
00888                                  guint           n);
00889 GList* g_list_find              (GList          *list,
00890                                  gpointer        data);
00891 GList* g_list_find_custom       (GList          *list,
00892                                  gpointer        data,
00893                                  GCompareFunc    func);
00894 gint   g_list_position          (GList          *list,
00895                                  GList          *llink);
00896 gint   g_list_index             (GList          *list,
00897                                  gpointer        data);
00898 GList* g_list_last              (GList          *list);
00899 GList* g_list_first             (GList          *list);
00900 guint  g_list_length            (GList          *list);
00901 void   g_list_foreach           (GList          *list,
00902                                  GFunc           func,
00903                                  gpointer        user_data);
00904 GList* g_list_sort              (GList          *list,
00905                                  GCompareFunc    compare_func);
00906 gpointer g_list_nth_data        (GList          *list,
00907                                  guint           n);
00908 #define g_list_previous(list)   ((list) ? (((GList *)(list))->prev) : NULL)
00909 #define g_list_next(list)       ((list) ? (((GList *)(list))->next) : NULL)
00910 
00911 
00912 /* Singly linked lists
00913  */
00914 void    g_slist_push_allocator  (GAllocator     *allocator);
00915 void    g_slist_pop_allocator   (void);
00916 GSList* g_slist_alloc           (void);
00917 void    g_slist_free            (GSList         *list);
00918 void    g_slist_free_1          (GSList         *list);
00919 GSList* g_slist_append          (GSList         *list,
00920                                  gpointer        data);
00921 GSList* g_slist_prepend         (GSList         *list,
00922                                  gpointer        data);
00923 GSList* g_slist_insert          (GSList         *list,
00924                                  gpointer        data,
00925                                  gint            position);
00926 GSList* g_slist_insert_sorted   (GSList         *list,
00927                                  gpointer        data,
00928                                  GCompareFunc    func);
00929 GSList* g_slist_concat          (GSList         *list1,
00930                                  GSList         *list2);
00931 GSList* g_slist_remove          (GSList         *list,
00932                                  gpointer        data);
00933 GSList* g_slist_remove_link     (GSList         *list,
00934                                  GSList         *llink);
00935 GSList* g_slist_reverse         (GSList         *list);
00936 GSList* g_slist_copy            (GSList         *list);
00937 GSList* g_slist_nth             (GSList         *list,
00938                                  guint           n);
00939 GSList* g_slist_find            (GSList         *list,
00940                                  gpointer        data);
00941 GSList* g_slist_find_custom     (GSList         *list,
00942                                  gpointer        data,
00943                                  GCompareFunc    func);
00944 gint    g_slist_position        (GSList         *list,
00945                                  GSList         *llink);
00946 gint    g_slist_index           (GSList         *list,
00947                                  gpointer        data);
00948 GSList* g_slist_last            (GSList         *list);
00949 guint   g_slist_length          (GSList         *list);
00950 void    g_slist_foreach         (GSList         *list,
00951                                  GFunc           func,
00952                                  gpointer        user_data);
00953 GSList*  g_slist_sort           (GSList          *list,
00954                                  GCompareFunc    compare_func);
00955 gpointer g_slist_nth_data       (GSList         *list,
00956                                  guint           n);
00957 #define g_slist_next(slist)     ((slist) ? (((GSList *)(slist))->next) : NULL)
00958 
00959 
00960 /* Hash tables
00961  */
00962 GHashTable* g_hash_table_new            (GHashFunc       hash_func,
00963                                          GCompareFunc    key_compare_func);
00964 void        g_hash_table_destroy        (GHashTable     *hash_table);
00965 void        g_hash_table_insert         (GHashTable     *hash_table,
00966                                          gpointer        key,
00967                                          gpointer        value);
00968 void        g_hash_table_remove         (GHashTable     *hash_table,
00969                                          gconstpointer   key);
00970 gpointer    g_hash_table_lookup         (GHashTable     *hash_table,
00971                                          gconstpointer   key);
00972 gboolean    g_hash_table_lookup_extended(GHashTable     *hash_table,
00973                                          gconstpointer   lookup_key,
00974                                          gpointer       *orig_key,
00975                                          gpointer       *value);
00976 void        g_hash_table_freeze         (GHashTable     *hash_table);
00977 void        g_hash_table_thaw           (GHashTable     *hash_table);
00978 void        g_hash_table_foreach        (GHashTable     *hash_table,
00979                                          GHFunc          func,
00980                                          gpointer        user_data);
00981 guint       g_hash_table_foreach_remove (GHashTable     *hash_table,
00982                                          GHRFunc         func,
00983                                          gpointer        user_data);
00984 guint       g_hash_table_size           (GHashTable     *hash_table);
00985 
00986 
00987 /* Caches
00988  */
00989 GCache*  g_cache_new           (GCacheNewFunc      value_new_func,
00990                                 GCacheDestroyFunc  value_destroy_func,
00991                                 GCacheDupFunc      key_dup_func,
00992                                 GCacheDestroyFunc  key_destroy_func,
00993                                 GHashFunc          hash_key_func,
00994                                 GHashFunc          hash_value_func,
00995                                 GCompareFunc       key_compare_func);
00996 void     g_cache_destroy       (GCache            *cache);
00997 gpointer g_cache_insert        (GCache            *cache,
00998                                 gpointer           key);
00999 void     g_cache_remove        (GCache            *cache,
01000                                 gpointer           value);
01001 void     g_cache_key_foreach   (GCache            *cache,
01002                                 GHFunc             func,
01003                                 gpointer           user_data);
01004 void     g_cache_value_foreach (GCache            *cache,
01005                                 GHFunc             func,
01006                                 gpointer           user_data);
01007 
01008 
01009 /* Balanced binary trees
01010  */
01011 GTree*   g_tree_new      (GCompareFunc   key_compare_func);
01012 void     g_tree_destroy  (GTree         *tree);
01013 void     g_tree_insert   (GTree         *tree,
01014                           gpointer       key,
01015                           gpointer       value);
01016 void     g_tree_remove   (GTree         *tree,
01017                           gpointer       key);
01018 gpointer g_tree_lookup   (GTree         *tree,
01019                           gpointer       key);
01020 void     g_tree_traverse (GTree         *tree,
01021                           GTraverseFunc  traverse_func,
01022                           GTraverseType  traverse_type,
01023                           gpointer       data);
01024 gpointer g_tree_search   (GTree         *tree,
01025                           GSearchFunc    search_func,
01026                           gpointer       data);
01027 gint     g_tree_height   (GTree         *tree);
01028 gint     g_tree_nnodes   (GTree         *tree);
01029 
01030 
01031 
01032 /* N-way tree implementation
01033  */
01034 struct _GNode
01035 {
01036   gpointer data;
01037   GNode   *next;
01038   GNode   *prev;
01039   GNode   *parent;
01040   GNode   *children;
01041 };
01042 
01043 #define  G_NODE_IS_ROOT(node)   (((GNode*) (node))->parent == NULL && \
01044                                  ((GNode*) (node))->prev == NULL && \
01045                                  ((GNode*) (node))->next == NULL)
01046 #define  G_NODE_IS_LEAF(node)   (((GNode*) (node))->children == NULL)
01047 
01048 void     g_node_push_allocator  (GAllocator       *allocator);
01049 void     g_node_pop_allocator   (void);
01050 GNode*   g_node_new             (gpointer          data);
01051 void     g_node_destroy         (GNode            *root);
01052 void     g_node_unlink          (GNode            *node);
01053 GNode*   g_node_insert          (GNode            *parent,
01054                                  gint              position,
01055                                  GNode            *node);
01056 GNode*   g_node_insert_before   (GNode            *parent,
01057                                  GNode            *sibling,
01058                                  GNode            *node);
01059 GNode*   g_node_prepend         (GNode            *parent,
01060                                  GNode            *node);
01061 guint    g_node_n_nodes         (GNode            *root,
01062                                  GTraverseFlags    flags);
01063 GNode*   g_node_get_root        (GNode            *node);
01064 gboolean g_node_is_ancestor     (GNode            *node,
01065                                  GNode            *descendant);
01066 guint    g_node_depth           (GNode            *node);
01067 GNode*   g_node_find            (GNode            *root,
01068                                  GTraverseType     order,
01069                                  GTraverseFlags    flags,
01070                                  gpointer          data);
01071 
01072 /* convenience macros */
01073 #define g_node_append(parent, node)                             \
01074      g_node_insert_before ((parent), NULL, (node))
01075 #define g_node_insert_data(parent, position, data)              \
01076      g_node_insert ((parent), (position), g_node_new (data))
01077 #define g_node_insert_data_before(parent, sibling, data)        \
01078      g_node_insert_before ((parent), (sibling), g_node_new (data))
01079 #define g_node_prepend_data(parent, data)                       \
01080      g_node_prepend ((parent), g_node_new (data))
01081 #define g_node_append_data(parent, data)                        \
01082      g_node_insert_before ((parent), NULL, g_node_new (data))
01083 
01084 /* traversal function, assumes that `node' is root
01085  * (only traverses `node' and its subtree).
01086  * this function is just a high level interface to
01087  * low level traversal functions, optimized for speed.
01088  */
01089 void     g_node_traverse        (GNode            *root,
01090                                  GTraverseType     order,
01091                                  GTraverseFlags    flags,