1libgg(7) GGI libgg(7)
2
6 libgg : Handy, portable wrappers for several basic OS features
7
9 LibGG provides a portable, unified interface to various very basic
10 operating system features, making it easy to write portable programs
11 without locking the author into a restricted, bloated, or overbearing
12 development paradigm. By abstracting the most commonly used function‐
13 ality in an operating-system-independent fashion, relying on prepack‐
14 aged LibGG distributions can also can reduce the complexity involved in
15 maintaining a portability suite (e.g. autotools) for the application's
16 development.
17 Originally LibGG came into being as part of the GGI Project, when
19 LibGII input functionality was separated from LibGGI into a stand-alone
20 library, and a place was needed to put functions needed by both
21 libraries. (Since then, we have forgotten what "GG" stood for, so
22 don't ask.)
23 The master upstream source of LibGG is still distributed as part of
25 LibGII, however it is itself a separately-distributable stand-alone
26 package of utilities that can be very useful to applications develop‐
27 ers.
28 LibGG provides the following groups of functions and/or macros. Some
30 may not be possible to implement on some operating systems, some may be
31 possible, just nobody has done so yet. We try to make them all avail‐
32 able where we can find the time and expertise:
33 Time functions (ggCurTime(3), ggUSleep(3) and ggUSlumber(3)) to handle
35 high-resolution timing and delays without busy-looping.
36 Cleanup callbacks (ggRegisterCleanup(3), ggUnregisterCleanup(3),
38 ggCleanupForceExit(3)) to allow your application to perform emergency
39 actions before a program is terminated abnormally.
40 Timer callbacks (ggAddTask(3), ggDelTask(3), ggTimeBase(3)) provide a
42 (non-realtime) wall-clock periodic/one-shot callback scheduler that can
43 be shared between many different areas of the application code without
44 fear of interference.
45 Locking Functions (ggLock(3), ggLockCreate(3), ggLockDestroy(3), ggTry‐
47 Lock(3), ggUnlock(3)) which are thread-safe in threaded environments.
48 System and CPU detection utilities (ggGetSwarType(3), GG_HAVE_INT64,
50 GG_LITTLE_ENDIAN) to allow you to detect CPU endianness and the pres‐
51 ence of features such as SWAR (SIMD) instruction sets (e.g. MMX), and
52 to turn on/off or change SWARs for testing or as a workaround.
53 Very basic overrun-proof string operations (ggstrlcpy(3), ggstrlcat(3))
55 which are a horrible mess for cross-platform programs to map to OS-
56 local string functions/headers.
57 Dynamic symbol management functions (ggGetScope(3), ggDelScope(3),
59 ggFromScope(3), ggNewScope(3)) allows you to create a plug-in system
60 where code is either dynamically loaded into and out of your program,
61 or statically linked in the library or program.
62 An option parser (ggParseOpts, ggSystemOpts) and plugin configuration
64 system (ggGetUserDir(3), ggParseTarget, ggLoadConfig(3), ggFreeCon‐
65 fig(3), ggMatchConfig, ggConfigExpandAlias) which are by-products of
66 the pluggable module support but can be useful for other things if you
67 like the format.
68 LibGG provides a few additionnal tools that are used internaly, for
70 other GGI libraries and that can also be useful to the application pro‐
71 grammer: macros for managing data structures such as lists, queues,
72 trees, a simple iterator scheme. These features are mostly macro-
73 based.
74
76 The following outlines the environment variables, intended for the
77 user, which affect the behaviour of LibGG:
78 GG_OPTS
80 LibGG uses the environment variable GG_OPTS, and expects it to
81 contain a valid option string as documented in the manpage for
82 ggParseOpts. The available options are documented along with
83 the LibGG API functions which they most affect.
84 GG_DEBUG
87 The debug level for LibGII:
88 · 0 or unset : debug output is off; debugging is off
90 · 255 : all debug output is on
92 You may also bitwise 'or' any of the following together:
94 · 2 : debug core
96 · 4 : misc debugging output
98 · 8 : debug locking code
100 · 16 : debug task subsystem
102 · 32 : debug scope code (dynamic library and symbol lookup)
104 · 64 : debug api code (not there yet)
106 GG_DEBUGSYNC
108 Turn on synchronous debug output, flushing the output buffers
109 before returning from DPRINT calls.
110
113 LibGG requires the exclusive use of one signal under certain environ‐
114 ments. This signal defaults to SIGPROF, where available, but may be
115 configured through the GG_OPTS option -signum=n where n represents the
116 numerical value of the signal to use. This signal should not be one of
117 the fatal signals handled by the LibGG cleanup facilities, and must be
118 a signal onto which a handler may be assigned. Applications should not
119 install handlers or alter the signal handler in any way for this sig‐
120 nal.
121
123 There is still some legacy to LibGGI in some of the namespace, espe‐
124 cially GGI_LITTLE_ENDIAN is currently the real name for GG_LIT‐
125 TLE_ENDIAN, which is an unofficial new addition destined to replace it.
126 Deprecation will take a few revisions as it must be done in an orderly
127 fashion.
128 Likewise the header file is included as <ggi/gg.h> but we will probably
130 keep that as-is because of the way LibGG is distributed and to avoid
131 adding more clutter in system include directories than is necessary.
132 Several features are incomplete, for example, code is still needed to
134 detect SWAR on many of the more obscure architectures.
135libgg-1.0.x 2005-08-06 libgg(7)