Man Linux: Main Page and Category List

NAME

       ggInit, ggExit - Initialize and uninitialize LibGG

SYNOPSIS

       #include <ggi/gg.h>

       int ggInit();

       int ggExit();

DESCRIPTION

       ggInit  initializes  LibGG  for  use, allocates resources, examines the
       runtime environment for options, and performs initializations necessary
       to  provide  the  LibGG  API.   This  function  must  be  called by the
       application (or by proxy by another library used  by  the  application)
       and  must  return  successfully  before using any other LibGG function;
       otherwise  the  results  of  invoking  LibGG  API  functions  will   be
       undefined.

       ggInit  allows  multiple  invocations.   Unless  ggExit  is  called  as
       described below, subsequent calls to ggInit will do nothing other  than
       increment  a  reference  counter  which LibGG uses to keep track of how
       many times  it  has  been  initialized.   This  allows  using  multiple
       libraries which call ggInit together without conflict.

       ggExit decrements the reference counter which ggInit increments.  Until
       this counter indicates that ggExit has been called  as  many  times  as
       ggInit it will do nothing else.

       That is, to free resources used by LibGG, ggExit must be called as many
       times as ggInit has been called beforehand (including any calls made by
       libraries  that  depend  on LibGG.)  After ggExit returns 0, indicating
       LibGG is deinitialized, ggInit may  be  called  again  to  reinitialize
       LibGG.

       When  ggExit determines that it has been called as many times as ggInit
       it performs the following actions (order is not guaranteed.)  Any tasks
       scheduled  with  ggAddTask(3)  are  canceled  (no task handlers will be
       called after ggExit returns.)  Any  cleanup  handlers  registered  with
       ggRegisterCleanup(3)  are  invoked  (no cleanup handlers will be called
       after   ggExit   returns.)    If   any   cleanup    handlers    invoked
       ggCleanupForceExit(3),  the  current  process will be terminated before
       ggExit returns.  Otherwise, all resources used by  LibGG  are  released
       for  use  by the application or operating system before ggExit returns.
       After the "last" ggExit is so  invoked,  any  GG  functions  (including
       ggExit  and  ggInit)  invoked  will  result  in undefined, and probably
       undesirable, behavior.  After ggExit returns 0, it  is  again  safe  to
       invoke ggInit.

       ggInit and ggExit are threadsafe functions with a few small exceptions.
       First, do not call ggInit at the same  time  from  two  threads  unless
       LibGG is already initialized.  This is easily avoided by calling ggInit
       once before threads that might call it are started.   Secondly,  it  is
       illegal  to  call  ggExit  after  the  "last"  ggExit  is invoked (note
       specifically, "invoked,"  not  "has  returned").   Naturally  you  must
       prevent  threads  from doing so, which is easy if you never call ggExit
       more times than ggInit.  Finally, it is not safe  to  cancel  a  thread
       while it is calling either of the two functions.

       ggInit  and ggExit are not guaranteed to be safe to call in any special
       context, such as a signal handler or asyncronous procedure call.   They
       are not safe to use in LibGG task handlers.

       Note  that,  if ggInit is used in a library (like LibGII or LibGGI) and
       the application also calls ggInit itself, cleanup handlers installed by
       ggRegisterCleanup(3)   may   not   execute   when  expected.   See  the
       ggRegisterCleanup(3) manpage for more detail on this subject.  The same
       applies  to  cancelation of tasks scheduled with ggAddTask(3).  See the
       ggAddTask(3) manpage for more detail on that subject.

RETURN VALUE

       ggInit returns:

       ·   GGI_OK on success;

       ·   GGI_EARGINVAL if the GG_OPTS variable is defined  but  the  options
           could not be parsed correctly;

       ·   GGI_EUNKNOWN if the global libgg lock could not be created.

       ggExit returns:

       ·   GGI_OK when LibGG has been completely, successfully, deinitialized;

       ·   >0 the number of open ggInit calls, if there has been more than one
           call  to  ggInit.   As  ggInit  and ggExit must be used in properly
           nested pairs, for example, the first ggExit after  two  giiInit(3)s
           will return 1;

       ·   GGI_ENOTALLOC  if  ggExit  has  been invoked more times than ggInit
           has.

SEE ALSO

       gg-error(3)