Man Linux: Main Page and Category List


       libgg - Handy, portable wrappers for several basic OS features


       LibGG  provides  a  portable,  unified  interface to various very basic
       operating system features, making it easy to  write  portable  programs
       without  locking  the author into a restricted, bloated, or overbearing
       development  paradigm.    By  abstracting  the   most   commonly   used
       functionality  in  an  operating-system-independent fashion, relying on
       prepackaged LibGG distributions can  also  can  reduce  the  complexity
       involved  in  maintaining  a portability suite (e.g. autotools) for the
       application’s development.

       Originally LibGG came into being as  part  of  the  GGI  Project,  when
       LibGII input functionality was separated from LibGGI into a stand-alone
       library, and a place  was  needed  to  put  functions  needed  by  both
       libraries.   (Since  then,  we  have  forgotten what "GG" stood for, so
       don’t ask.)

       The master upstream source of LibGG is still  distributed  as  part  of
       LibGII,  however  it  is  itself a separately-distributable stand-alone
       package  of  utilities  that  can  be  very  useful   to   applications

       LibGG  provides  the following groups of functions and/or macros.  Some
       may not be possible to implement on some operating systems, some may be
       possible,  just  nobody  has  done  so  yet.   We  try to make them all
       available where we can find the time and expertise:

       Time functions (ggCurTime(3), ggUSleep(3) and ggUSlumber(3)) to  handle
       high-resolution timing and delays without busy-looping.

       Cleanup    callbacks   (ggRegisterCleanup(3),   ggUnregisterCleanup(3),
       ggCleanupForceExit(3)) to allow your application to  perform  emergency
       actions before a program is terminated abnormally.

       Timer  callbacks  (ggAddTask(3), ggDelTask(3), ggTimeBase(3)) provide a
       (non-realtime) wall-clock periodic/one-shot callback scheduler that can
       be  shared between many different areas of the application code without
       fear of interference.

       Locking  Functions   (ggLock(3),   ggLockCreate(3),   ggLockDestroy(3),
       ggTryLock(3),   ggUnlock(3))   which   are   thread-safe   in  threaded

       System and CPU detection  utilities  (ggGetSwarType(3),  GG_HAVE_INT64,
       GG_LITTLE_ENDIAN)  to  allow  you  to  detect  CPU  endianness  and the
       presence of features such as SWAR (SIMD) instruction sets  (e.g.  MMX),
       and to turn on/off or change SWARs for testing or as a workaround.

       Very basic overrun-proof string operations (ggstrlcpy(3), ggstrlcat(3))
       which are a horrible mess for cross-platform programs  to  map  to  OS-
       local string functions/headers.

       Dynamic  symbol  management  functions  (ggGetScope(3),  ggDelScope(3),
       ggFromScope(3), ggNewScope(3)) allows you to create  a  plug-in  system
       where  code  is either dynamically loaded into and out of your program,
       or statically linked in the library or program.

       An option parser (ggParseOpts, ggSystemOpts) and  plugin  configuration
       system      (ggGetUserDir(3),      ggParseTarget,      ggLoadConfig(3),
       ggFreeConfig(3),  ggMatchConfig,  ggConfigExpandAlias)  which  are  by-
       products  of  the  pluggable module support but can be useful for other
       things if you like the format.

       LibGG provides a few additionnal tools that  are  used  internaly,  for
       other  GGI  libraries  and  that  can also be useful to the application
       programmer: macros for managing data structures such as lists,  queues,
       trees,  a  simple  iterator  scheme.   These features are mostly macro-


       The following outlines the  environment  variables,  intended  for  the
       user, which affect the behaviour of LibGG:

              LibGG  uses  the environment variable GG_OPTS, and expects it to
              contain a valid option string as documented in the  manpage  for
              ggParseOpts.   The  available  options are documented along with
              the LibGG API functions which they most affect.

              The debug level for LibGII:

              ·   0 or unset : debug output is off; debugging is off

              ·   255 : all debug output is on

              You may also bitwise ’or’ any of the following together:

              ·   2  : debug core

              ·   4  : misc debugging output

              ·   8  : debug locking code

              ·   16 : debug task subsystem

              ·   32 : debug scope code (dynamic library and symbol lookup)

              ·   64 : debug api code (not there yet)

              Turn on synchronous debug output, flushing  the  output  buffers
              before returning from DPRINT calls.


       LibGG   requires   the  exclusive  use  of  one  signal  under  certain
       environments.  This signal defaults to SIGPROF,  where  available,  but
       may  be  configured  through  the  GG_OPTS  option  -signum=n  where  n
       represents the numerical value of  the  signal  to  use.   This  signal
       should  not  be  one  of the fatal signals handled by the LibGG cleanup
       facilities, and must be a signal onto which a handler may be  assigned.
       Applications should not install handlers or alter the signal handler in
       any way for this signal.


       There is still  some  legacy  to  LibGGI  in  some  of  the  namespace,
       especially   GGI_LITTLE_ENDIAN   is   currently   the   real  name  for
       GG_LITTLE_ENDIAN, which is  an  unofficial  new  addition  destined  to
       replace  it.   Deprecation will take a few revisions as it must be done
       in an orderly fashion.

       Likewise the header file is included as <ggi/gg.h> but we will probably
       keep  that  as-is  because of the way LibGG is distributed and to avoid
       adding more clutter in system include directories than is necessary.

       Several features are incomplete, for example, code is still  needed  to
       detect SWAR on many of the more obscure architectures.