C Library Functions                                     libggz(3)



NAME
     libggz - The GZ Gaming Zone base library


DESCRIPTION
     libggz is used  by  GZ  Gaming  Zone  server,  the  ggzcore
     library  and other components. This library handles network-
     ing, configuration files, structure management functions and
     wrappers around glibc functions.


     The libggz library contains different groups of functions:


  FUNCTION GROUPS
     Memory handling

         These functions provide an alternative to the  normal  C
         library  functions  for  dynamically  allocating memory.
         They keep track of memory allocated by storing the  name
         of the function and file in which they were called simi-
         lar to  glibc  but  are  more  convenient  to  use.  For
         instance,   ggzstrdup(NUL)  returns  NUL  instead  of
         crashing, and ggzmalloc() includes a reference  counter
         to be used for debugging in combination with ggzfree().
         With   enabled    MEMORY    debugging    the    function
         ggzmemorycheck()  may be called to make sure all allo-
         cated memory has been freed.



     Configuration file management

         This group of functions is used  for  XML  configuration
         file routines to store and retrieve values. For example,
         the ggzconfparse() function can be used to open a con-
         fig   file.   To  create  such  file  automatically  the
         GZCONFCREATE must be specified. If exactly  the  same
         configuration  pathname  is  being  opened more than one
         time, the original handle is being returned and only one
         copy is retained within memory.

         Configuration values are stored using a system  of  sec-
         tions  and  keys.  A key must be unique within a section
         and cannot be both an integer and a  string  within  the
         same  key. Section and key names may contain any charac-
         ters except an equal sign.  Although keys may  not  have
         leading  or  trailing whitespace, section names may have
         them.  It is suggested that any whitespace  (other  than
         possibly  internal  spaces)  be  avoided when specifying
         section and key names.




SunOS 5.11          Last change: 29 May 2008                    1






C Library Functions                                     libggz(3)



         For  writing  the  values  to  the  physical  file,  the
         ggzconfcommit() function must be called, otherwise all
         values are in the memory only, which makes writing  mul-
         tiple  values in rapid succession more efficient, as the
         entire file must be regenerated in order to  be  written
         to the flat-file format of the configuration file.

         The string and list reading functions return dynamically
         allocated memory to the caller.  The user is responsible
         for calling ggzfree()  on  this  memory  when  they  no
         longer need the returned values.

         All memory used internally by  the  configuration  func-
         tions   will  be  released  when  ggzconfcleanup()  is
         called.  Note that this does not commit any changes made
         to  the  configuration  files,  so the ggzconfcommit()
         have   to   be   called   to   do   such   commit.   The
         ggzconfcleanup()  is  expected to call this at program
         termination, but it may be called at  any  time  earlier
         than  termination  and  new  files  may  be subsequently
         opened.


     Debug functions

         The functions allow switching on and off debug  messages
         for a certain tag.


     Network functions

         Those functions,  historically  known  as  the  easysock
         library,  permits the creation of server or client sock-
         ets, compatible with IPv6, as well as reading and  writ-
         ing basic datatypes such as integers or strings.


     Security functions

         This group of functions are for both cryptographic  hash
         creation  and  comparison  using the gcrypt library, and
         for TLS encryption for network channels using OpenSL.



FILES
     The following files are used by this library:

     /usr/lib/libggz.so              The  base  GZ  Gaming  Zone
                                     shared library





SunOS 5.11          Last change: 29 May 2008                    2






C Library Functions                                     libggz(3)



ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:


     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Availability                 SUNWgnome-games             
    
     Interface stability          Volatile                    
    


SEE ALSO
     ggzh(3),    ggzcoreh(3),    ggzmodh(3),    libggzcore(3),
     libggzmod(3),    attributes(5),    ggz.modules(5),    gnome-
     interfaces(5), ggz(6), ggz-config(6), ggz(7)

     GZ Gaming Zone:


         http:/www.ggzgamingzone.org/
         http:/www.ggzgamingzone.org/docs/api/libggz/
         http:/www.ggzgamingzone.org/docs/api/ggzcore/
         http:/www.ggzgamingzone.org/docs/api/ggzmod/




NOTES
     Written by Michal Pryc, Sun Microsystems Inc., 2008.























SunOS 5.11          Last change: 29 May 2008                    3