1
.TH "libgg" 7 "2004-05-26" "libgg-0.8.x" GGI
1
.TH "libgg" 7 "2005-08-06" "libgg-1.0.x" GGI
3
3
\fBlibgg\fR : Handy, portable wrappers for several basic OS features
5
5
\fBLibGG\fR provides a portable, unified interface to various very basic
6
system features, making it easy to write portable programs without
7
locking the author into a bloated or overbearing development paradigm.
6
operating system features, making it easy to write portable programs without
7
locking the author into a restricted, bloated, or overbearing development
8
paradigm. By abstracting the most commonly used functionality in an
9
operating-system-independent fashion, relying on prepackaged \fBLibGG\fR
10
distributions can also can reduce the complexity involved in maintaining
11
a portability suite (e.g. autotools) for the application's development.
9
13
Originally \fBLibGG\fR came into being as part of the GGI Project, when
10
14
\fBLibGII\fR input functionality was separated from \fBLibGGI\fR into a stand-alone
11
15
library, and a place was needed to put functions needed by both libraries.
12
16
(Since then, we have forgotten what "GG" stood for, so don't ask.)
14
\fBLibGG\fR is still distributed as part of \fBLibGII\fR, however it is itself a
15
stand-alone package of utilities that can be very useful to anyone
16
writing applications that need to be portable across many different
17
operating systems environments.
18
The master upstream source of \fBLibGG\fR is still distributed as part of
19
\fBLibGII\fR, however it is itself a separately-distributable stand-alone
20
package of utilities that can be very useful to applications developers.
19
22
\fBLibGG\fR provides the following groups of functions and/or macros. Some
20
23
may not be possible to implement on some operating systems, some may
21
24
be possible, just nobody has done so yet. We try to make them all
22
available where we can find the time and/or expertise:
24
Time functions (\fBggUSleep\fR) to handle high-resolution timing without
27
Cleanup callbacks (\fBggRegisterCleanup\fR, \fBggUnregisterCleanup\fR,
28
\fBggCleanupForceExit\fR) to allow your application to perform emergency
29
actions when the program is terminated abnormally.
31
Timer callbacks (API in development) are in the works to provide
32
a threads or signal-based periodic/one-shot callback scheduler that
33
can be shared between many different areas of the application code
34
without fear of interference.
36
Locking Functions (\fBggLock\fR, \fBggLockCreate\fR, \fBggLockDestroy\fR, \fBggTryLock\fR,
37
\fBggUnlock\fR) which are thread-safe mutexes in threaded environments.
39
System and CPU detection utilities (\fBggGetSwarType\fR, \fBGG_HAVE_INT64\fR,
25
available where we can find the time and expertise:
27
Time functions (\fBggCurTime(3)\fR, \fBggUSleep(3)\fR and \fBggUSlumber(3)\fR) to handle
28
high-resolution timing and delays without busy-looping.
30
Cleanup callbacks (\fBggRegisterCleanup(3)\fR, \fBggUnregisterCleanup(3)\fR,
31
\fBggCleanupForceExit(3)\fR) to allow your application to perform emergency
32
actions before a program is terminated abnormally.
34
Timer callbacks (\fBggAddTask(3)\fR, \fBggDelTask(3)\fR, \fBggTimeBase(3)\fR) provide a
35
(non-realtime) wall-clock periodic/one-shot callback scheduler that can
36
be shared between many different areas of the application code without
39
Locking Functions (\fBggLock(3)\fR, \fBggLockCreate(3)\fR, \fBggLockDestroy(3)\fR, \fBggTryLock(3)\fR,
40
\fBggUnlock(3)\fR) which are thread-safe in threaded environments.
42
System and CPU detection utilities (\fBggGetSwarType(3)\fR, \fBGG_HAVE_INT64\fR,
40
43
\fBGG_LITTLE_ENDIAN\fR) to allow you to detect CPU endianness and the
41
presence of features such as SIMD instruction sets (e.g. MMX), and
42
to turn on/off or change SWARs for testing or as a workaround.
44
Pluggable module management functions (\fBggLoadModule\fR, \fBggMLoadModule\fR,
45
\fBggGetSymbolAddress\fR, \fBggFreeModule\fR) that allow you to create a plugin
46
system where code is dynamically loaded into and out of your program.
47
(Support for statically linked emulation for embedded systems is
48
planned for the future.)
50
An option parser (\fBggParseOptions\fR) and configuration file system
51
(\fBggGetUserDir\fR, \fBggGetFileOpt\fR, \fBggParseTarget\fR, \fBggLoadConfig\fR,
52
\fBggFreeConfig\fR, \fBggMatchConfig\fR, \fBggConfigExpandAlias\fR) which is a
53
by-product of the pluggable module support but can be useful for other
54
things if you like the format. (Note this will be undergoing some
55
major changes and enhancements soon.)
44
presence of features such as SWAR (SIMD) instruction sets (e.g. MMX),
45
and to turn on/off or change SWARs for testing or as a workaround.
47
Very basic overrun-proof string operations (\fBggstrlcpy(3)\fR, \fBggstrlcat(3)\fR)
48
which are a horrible mess for cross-platform programs to map to
49
OS-local string functions/headers.
51
Dynamic symbol management functions (\fBggGetScope(3)\fR, \fBggDelScope(3)\fR,
52
\fBggFromScope(3)\fR, \fBggNewScope(3)\fR) allows you to create a plug-in system
53
where code is either dynamically loaded into and out of your program,
54
or statically linked in the library or program.
56
An option parser (\fBggParseOpts\fR, \fBggSystemOpts\fR) and plugin configuration
57
system (\fBggGetUserDir(3)\fR, \fBggParseTarget\fR, \fBggLoadConfig(3)\fR, \fBggFreeConfig(3)\fR,
58
\fBggMatchConfig\fR, \fBggConfigExpandAlias\fR) which are by-products of the
59
pluggable module support but can be useful for other things if you like
62
LibGG provides a few additionnal tools that are used internaly, for
63
other GGI libraries and that can also be useful to the application
64
programmer: macros for managing data structures such as lists, queues,
65
trees, a simple iterator scheme. These features are mostly
67
.SH ENVIRONMENT VARIABLE:
68
The following outlines the environment variables, intended for the
69
user, which affect the behaviour of LibGG:
72
LibGG uses the environment variable \fIGG_OPTS\fR, and
73
expects it to contain a valid option string as documented in the
74
manpage for \fBggParseOpts\fR. The available options are documented
75
along with the LibGG API functions which they most affect.
79
The debug level for LibGII:
82
0 or unset : debug output is off; debugging is off
84
255 : all debug output is on
86
You may also bitwise 'or' any of the following together:
90
4 : misc debugging output
92
8 : debug locking code
94
16 : debug task subsystem
96
32 : debug scope code (dynamic library and symbol lookup)
98
64 : debug api code (not there yet)
104
Turn on synchronous debug output, flushing the output buffers
105
before returning from \fBDPRINT\fR calls.
109
LibGG requires the exclusive use of one signal under certain
110
environments. This signal defaults to SIGPROF, where available, but
111
may be configured through the GG_OPTS option \f(CW-signum=n\fR where
112
\fIn\fR represents the numerical value of the signal to use. This
113
signal should not be one of the fatal signals handled by the LibGG
114
cleanup facilities, and must be a signal onto which a handler may be
115
assigned. Applications should not install handlers or alter the
116
signal handler in any way for this signal.
57
118
There is still some legacy to \fBLibGGI\fR in some of the namespace,
58
119
especially \fBGGI_LITTLE_ENDIAN\fR is currently the real name for
59
\fBGG_LITTLE_ENDIAN\fR, which is an unofficial, new addition destined
120
\fBGG_LITTLE_ENDIAN\fR, which is an unofficial new addition destined
60
121
to replace it. Deprecation will take a few revisions as it must
61
122
be done in an orderly fashion.
added
removed
doc/man/libgg.7
