1ggInit(3) GGI ggInit(3)
2
6 ggInit, ggExit : Initialize and uninitialize LibGG
7
9 #include <ggi/gg.h>
10 int ggInit();
12 int ggExit();
14
17 ggInit initializes LibGG for use, allocates resources, examines the
18 runtime environment for options, and performs initializations necessary
19 to provide the LibGG API. This function must be called by the applica‐
20 tion (or by proxy by another library used by the application) and must
21 return successfully before using any other LibGG function; otherwise
22 the results of invoking LibGG API functions will be undefined.
23 ggInit allows multiple invocations. Unless ggExit is called as
25 described below, subsequent calls to ggInit will do nothing other than
26 increment a reference counter which LibGG uses to keep track of how
27 many times it has been initialized. This allows using multiple
28 libraries which call ggInit together without conflict.
29 ggExit decrements the reference counter which ggInit increments. Until
31 this counter indicates that ggExit has been called as many times as
32 ggInit it will do nothing else.
33 That is, to free resources used by LibGG, ggExit must be called as many
35 times as ggInit has been called beforehand (including any calls made by
36 libraries that depend on LibGG.) After ggExit returns 0, indicating
37 LibGG is deinitialized, ggInit may be called again to reinitialize
38 LibGG.
39 When ggExit determines that it has been called as many times as ggInit
41 it performs the following actions (order is not guaranteed.) Any tasks
42 scheduled with ggAddTask(3) are canceled (no task handlers will be
43 called after ggExit returns.) Any cleanup handlers registered with
44 ggRegisterCleanup(3) are invoked (no cleanup handlers will be called
45 after ggExit returns.) If any cleanup handlers invoked ggCleanupForce‐
46 Exit(3), the current process will be terminated before ggExit returns.
47 Otherwise, all resources used by LibGG are released for use by the
48 application or operating system before ggExit returns. After the
49 "last" ggExit is so invoked, any GG functions (including ggExit and
50 ggInit) invoked will result in undefined, and probably undesirable,
51 behavior. After ggExit returns 0, it is again safe to invoke ggInit.
52 ggInit and ggExit are threadsafe functions with a few small exceptions.
54 First, do not call ggInit at the same time from two threads unless
55 LibGG is already initialized. This is easily avoided by calling ggInit
56 once before threads that might call it are started. Secondly, it is
57 illegal to call ggExit after the "last" ggExit is invoked (note specif‐
58 ically, "invoked," not "has returned"). Naturally you must prevent
59 threads from doing so, which is easy if you never call ggExit more
60 times than ggInit. Finally, it is not safe to cancel a thread while it
61 is calling either of the two functions.
62 ggInit and ggExit are not guaranteed to be safe to call in any special
64 context, such as a signal handler or asyncronous procedure call. They
65 are not safe to use in LibGG task handlers.
66 Note that, if ggInit is used in a library (like LibGII or LibGGI) and
68 the application also calls ggInit itself, cleanup handlers installed by
69 ggRegisterCleanup(3) may not execute when expected. See the ggRegis‐
70 terCleanup(3) manpage for more detail on this subject. The same
71 applies to cancelation of tasks scheduled with ggAddTask(3). See the
72 ggAddTask(3) manpage for more detail on that subject.
73
75 ggInit returns:
76 · GGI_OK on success;
78 · GGI_EARGINVAL if the GG_OPTS variable is defined but the options
80 could not be parsed correctly;
81 · GGI_EUNKNOWN if the global libgg lock could not be created.
83 ggExit returns:
85 · GGI_OK when LibGG has been completely, successfully, deinitialized;
87 · >0 the number of open ggInit calls, if there has been more than one
89 call to ggInit. As ggInit and ggExit must be used in properly
90 nested pairs, for example, the first ggExit after two giiInit(3)s
91 will return 1;
92 · GGI_ENOTALLOC if ggExit has been invoked more times than ggInit
94 has.
95
97 gg-error(3)
98libgg-1.0.x 2005-08-26 ggInit(3)