ggInit(3)

1ggInit(3)                             GGI                            ggInit(3)
2
3
4

NAME

6       ggInit, ggExit : Initialize and uninitialize LibGG
7

SYNOPSIS

9       #include <ggi/gg.h>
10
11       int ggInit();
12
13       int ggExit();
14
15

DESCRIPTION

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
24       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
30       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
34       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
40       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
53       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
63       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
67       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

RETURN VALUE

75       ggInit returns:
76
77       ·   GGI_OK on success;
78
79       ·   GGI_EARGINVAL if the GG_OPTS variable is defined  but  the  options
80           could not be parsed correctly;
81
82       ·   GGI_EUNKNOWN if the global libgg lock could not be created.
83
84       ggExit returns:
85
86       ·   GGI_OK when LibGG has been completely, successfully, deinitialized;
87
88       ·   >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
93       ·   GGI_ENOTALLOC if ggExit has been invoked  more  times  than  ggInit
94           has.
95

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

SEE ALSO