NAME¶
libgg - Handy, portable wrappers for several basic OS features
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(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 environments.
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-based.
ENVIRONMENT VARIABLE:¶
The following outlines the environment variables, intended for the user, which
affect the behaviour of LibGG:
- GG_OPTS
- 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.
- GG_DEBUG
- 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)
- GG_DEBUGSYNC
- Turn on synchronous debug output, flushing the output
buffers before returning from DPRINT calls.
RESERVED SIGNAL:¶
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.
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.