====================
LibGG Documentation
====================


.. include:: libgg-functions.txt


LibGG Library
=============

Handy, portable wrappers for several basic OS features
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 7 libgg

Description
-----------


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


`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`, `ggUSleep` and `ggUSlumber`) to handle 
high-resolution timing and delays without busy-looping.


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


Timer callbacks (`ggAddTask`, `ggDelTask`, `ggTimeBase`) 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`, `ggLockCreate`, `ggLockDestroy`, `ggTryLock`, 
`ggUnlock`) which are thread-safe in threaded environments.


System and CPU detection utilities (`ggGetSwarType`, `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`, `ggstrlcat`)
which are a horrible mess for cross-platform programs to map to 
OS-local string functions/headers.


Pluggable module management functions (`ggLoadModule`, `ggMLoadModule`,
`ggGetSymbolAddress`, `ggFreeModule`) that allow you to create a plugin
system where code is dynamically loaded into and out of your program.
(Support for statically linked emulation for embedded systems is also
provided.)


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


Environment Variable:
---------------------

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.


BUGS:
-----

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.
