Provided by: libgii1_1.0.2-2_i386 bug

NAME

       ggGetScope,  ggFromScope, ggDelScope, ggNewScope - Portable code module
       loading facilities

SYNOPSIS

       #include <ggi/gg.h>

       gg_scope ggGetScope(const char *location);

       void ggDelScope(gg_scope scope);

       void *ggFromScope(gg_scope, const char *symbol);

       typedef  void *(*ggfunc_scope_get)(void * handle, const char * symbol);
       typedef  void (*ggfunc_scope_del)(void * handle);

       gg_scope ggNewScope(const char * location, void * handle,
                           ggfunc_scope_get get, ggfunc_scope_del del)

DESCRIPTION

       LibGG abstracts dynamic code loading (and emulates dynamic code loading
       for  statically  linked  embedded  binaries) through a simple API which
       represents the very  lowest  level  required  of  any  loadable  module
       system.   The  actual  underlying  mechanisms used in various operating
       systems to load additional code into  an  application  on  demand  vary
       drastically,  however, minus OS-specific frills, they can all be mapped
       to the above three LibGG API functions.

       ggGetScope finds a loadable collection of symbols known by its location
       through  whatever  system  is available on the operating system.  Those
       symbols were once supposed to be  code  from  modules,  but  the  scope
       abstraction  does  not  impose  this  restriction.  The scopes can have
       different implementations and are not restricted to dynamic  libraries.
       They   could  also  be  used  as  an  interface  to  a  attribute/value
       configuration system.

       Note that when a scope happens to be dynamic library, the  symbols  are
       loaded  into  the  address  space  of  the  caller,  but libgg does not
       guarantee that the imported symbols will be seen by other modules.

       ggDelScope unloads the symbol  collection  represented  by  the  handle
       scope,  which  must have been previously loaded with ggGetScope  (scope
       should  be  a  return  value  from  a  previous  call  to  ggGetScope.)
       Reference  counts  are  kept  to  ensure that redundantly loaded symbol
       collections are not discarded until their  last  owner  releases  them.
       Calling ggDelScope on a handle too many times, or on an invalid handle,
       may produce undefined results.  Accessing symbols after the collections
       they  were  contained  in  are  unloaded  will  produce undesirable and
       undefined results.

       ggFromScope searches the symbol collection represented  by  the  handle
       scope, which has been loaded with ggGetScope (and not yet unloaded with
       ggDelScope,  of  course)  for  a  symbol  named  symbol,  so  that  the
       application may use the item associated with the symbol.  The parameter
       scope should be a return value from a previous call to ggDelScope.   As
       ggFromScope  may have no way of knowing what the symbol represents, the
       application must take the  responsibility  for  assigning  the  item  a
       correct C type.

       ggNewScope  allows  to  register  a  custom scope to libgg. The primary
       purpose is to allow libraries  to  provide  builtin  modules  that  are
       accessible  through the same interface as dynamic ones. location is the
       string at which the scope can be retreived. handle is a opaque  pointer
       provided  by  the caller that will be passed to the callbacks. get is a
       function that take an opaque handle,  a  symbol  name,  and  that  must
       return  the  requested  symbol  address, or NULL if not found. del is a
       function that will take the provided handler,  and  that  must  cleanup
       everything  before  the  scope is removed from the scope registry. This
       scheme allows to implement all kind of scopes in a very  flexible  way.
       Note that ggNewScope will take a reference on the scope.

RETURN VALUE

       On   success,   ggGetScope  returns  an  opaque  pointer  to  a  handle
       representing a newly loaded symbol collection (which must  be  retained
       in  order  to  use  or  free  the  collection.)  These pointers are not
       guaranteed to be unique.  On failure, ggGetScope returns NULL.

       ggFromScope returns the address of  the  item  that  the  named  symbol
       represents,  if  it  has  been  loaded into the caller’s address space.
       Otherwise it returns NULL. Note that the value associated to  a  symbol
       really  depends  on  the  scope itself and the caller must know what is
       behind it. So a NULL value does not necessarily means failure. It could
       be a valid value for a specific scope.

       ggNewScope  returns  an  opaque  pointer  to  a handle representing the
       custom scope.  On failure, ggNewScope returns NULL.