Home | History | Annotate | Download | only in man3
      1 <!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
      2 <!--ArborText, Inc., 1988-1999, v.4002-->
      3 <!ENTITY cmd "libggz">
      4 <!ENTITY % commonents SYSTEM "smancommon.ent">
      5 %commonents;
      6 <!ENTITY % booktitles SYSTEM "booktitles.ent">
      7 %booktitles;
      8 <!ENTITY suncopy "Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.">
      9 ]>
     10 <?Pub UDT _bookmark _target>
     11 <?Pub Inc>
     12 <refentry id="libggz-3">
     13 <!-- %Z%%M% %I% %E% SMI; -->
     14 <refmeta>
     15    <refentrytitle>libggz</refentrytitle><manvolnum>3</manvolnum>
     16    <refmiscinfo class="date">29 May 2008</refmiscinfo>
     17    <refmiscinfo class="sectdesc">&man3;</refmiscinfo>
     18    <refmiscinfo class="software">&release;</refmiscinfo>
     19    <refmiscinfo class="arch">generic</refmiscinfo>
     20    <refmiscinfo class="copyright">&suncopy;</refmiscinfo>
     21 </refmeta>
     22 
     23 <indexterm><primary>libggz</primary></indexterm>
     24 <indexterm><primary>The GGZ Gaming Zone base library</primary></indexterm>
     25 
     26 <refnamediv id="libggz-3-name">
     27    <refname>libggz</refname>
     28    <refpurpose>
     29 The GGZ Gaming Zone base library
     30    </refpurpose>
     31 </refnamediv>
     32 
     33 <refsect1 id="libggz-3-desc">
     34    <title>&desc-tt;</title>
     35    <para>
     36 &cmd; is used by GGZ Gaming Zone server, the ggzcore library and other
     37 components. This library handles networking, configuration files, structure
     38 management functions and wrappers around glibc functions.
     39    </para>
     40    <para>
     41 The <filename>libggz</filename> library contains different groups of functions:
     42    </para>
     43 <refsect2 id="libggz-3-exde-optb-func">
     44 <title>FUNCTION GROUPS</title>
     45    <para>
     46 <variablelist termlength="long">
     47 <varlistentry><term><literal>Memory handling</literal></term><listitem>
     48 <para>
     49 These functions provide an alternative to the normal C library functions for 
     50 dynamically allocating memory. They keep track of memory allocated by storing
     51 the name of the function and file in which they were called similar to glibc but 
     52 are more convenient to use. For instance, ggz_strdup(NULL) returns NULL instead 
     53 of crashing, and ggz_malloc() includes a reference counter to be used for 
     54 debugging in combination with ggz_free(). With enabled MEMORY debugging the 
     55 function ggz_memory_check() may be called to make sure all allocated memory has 
     56 been freed.
     57 </listitem>
     58 </varlistentry>
     59 <varlistentry><term><literal>Configuration file management</literal></term><listitem>
     60 This group of functions is used for XML configuration file routines to store
     61 and retrieve values. For example, the ggz_conf_parse() function can be used to
     62 open a config file. To create such file automatically the GGZ_CONF_CREATE must
     63 be specified. If exactly the same configuration pathname is being opened more
     64 than one time, the original handle is being returned and only one copy is
     65 retained within memory.
     66 
     67 Configuration values are stored using a system of sections and keys. A key must
     68 be unique within a section and cannot be both an integer and a string within the
     69 same key. Section and key names may contain any characters except an equal sign.
     70 Although keys may not have leading or trailing whitespace, section names may
     71 have them.  It is suggested that any whitespace (other than possibly internal
     72 spaces) be avoided when specifying section and key names.  
     73 
     74 For writing the values to the physical file, the ggz_conf_commit() function must
     75 be called, otherwise all values are in the memory only, which makes writing 
     76 multiple values in rapid succession more efficient, as the entire file must be 
     77 regenerated in order to be written to the flat-file format of the configuration 
     78 file.
     79 
     80 The string and list reading functions return dynamically allocated memory to
     81 the caller.  The user is responsible for calling ggz_free() on this memory when
     82 they no longer need the returned values.
     83 
     84 All memory used internally by the configuration functions will be released when 
     85 ggz_conf_cleanup() is called.  Note that this does not commit any changes made 
     86 to the configuration files, so the ggz_conf_commit() have to be called to do 
     87 such commit. The ggz_conf_cleanup() is expected to call this at program 
     88 termination, but it may be called at any time earlier than termination and new 
     89 files may be subsequently opened.
     90 </listitem>
     91 </varlistentry>
     92 <varlistentry><term><literal>Debug functions</literal></term><listitem>
     93 The functions allow switching on and off debug messages for a certain tag.
     94 </listitem>
     95 </varlistentry>
     96 <varlistentry><term><literal>Network functions</literal></term><listitem>
     97 Those functions, historically known as the easysock library, permits the
     98 creation of server or client sockets, compatible with IPv6, as well as reading
     99 and writing basic datatypes such as integers or strings.
    100 </listitem>
    101 </varlistentry>
    102 </varlistentry>
    103 <varlistentry><term><literal>Security functions</literal></term><listitem>
    104 This group of functions are for both cryptographic hash creation and comparison 
    105 using the gcrypt library, and for TLS encryption for network channels using 
    106 OpenSSL. 
    107 </listitem>
    108 </varlistentry>
    109    </para>
    110 </refsect2>
    111 </para>
    112 </refsect1>
    113 
    114 <refsect1 id="libggz-3-file">
    115    <title>&file-tt;</title>
    116    <para>The following files are used by this library:</para>
    117    <variablelist termlength="wide">
    118       <varlistentry>
    119          <term><filename>/usr/lib/&cmd;.so</filename> </term>
    120          <listitem>
    121             <para>The base GGZ Gaming Zone shared library</para>
    122          </listitem>
    123       </varlistentry>
    124    </variablelist>
    125 </refsect1>
    126 
    127 <refsect1 id="libggz-3-attr">
    128    <title>&attr-tt;</title>
    129    <para>See <olink targetdocent="REFMAN5" localinfo="attributes-5"><citerefentry>
    130 <refentrytitle>attributes</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    131 </olink> for descriptions of the following attributes:
    132    </para>
    133    <informaltable frame="all">
    134       <tgroup cols="2" colsep="1" rowsep="1">
    135          <colspec colname="COLSPEC0" colwidth="1*">
    136          <colspec colname="COLSPEC1" colwidth="1*">
    137          <thead>
    138             <row>
    139                <entry align="center" valign="middle">ATTRIBUTE TYPE</entry>
    140                <entry align="center" valign="middle">ATTRIBUTE VALUE</entry>
    141             </row>
    142          </thead>
    143          <tbody>
    144             <row>
    145                <entry><para>Availability</para></entry>
    146                <entry><para>SUNWgnome-games</para></entry>
    147             </row>
    148             <row>
    149                <entry colname="COLSPEC0"><para>Interface stability</para></entry>
    150                <entry colname="COLSPEC1"><para>Volatile</para></entry>
    151             </row>
    152          </tbody>
    153       </tgroup>
    154    </informaltable>
    155 </refsect1>
    156 
    157 <refsect1 id="libggz-3-also"><title>&also-tt;</title>
    158    <!--Reference to another man page-->
    159    <!--Reference to a Help manual-->
    160    <!--Reference to a book.-->
    161 <para>
    162 <citerefentry><refentrytitle>ggz_h</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
    163 <citerefentry><refentrytitle>ggzcore_h</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
    164 <citerefentry><refentrytitle>ggzmod_h</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
    165 <citerefentry><refentrytitle>libggzcore</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
    166 <citerefentry><refentrytitle>libggzmod</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
    167 <citerefentry><refentrytitle>attributes</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
    168 <citerefentry><refentrytitle>ggz.modules</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
    169 <citerefentry><refentrytitle>gnome-interfaces</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
    170 <citerefentry><refentrytitle>ggz</refentrytitle><manvolnum>6</manvolnum></citerefentry>,
    171 <citerefentry><refentrytitle>ggz-config</refentrytitle><manvolnum>6</manvolnum></citerefentry>,
    172 <citerefentry><refentrytitle>ggz</refentrytitle><manvolnum>7</manvolnum></citerefentry>
    173 </para>
    174 <variablelist termlength="wholeline">
    175 <varlistentry>
    176 <term><filename>GGZ Gaming Zone:</filename></term>
    177 <listitem><para>
    178 <programlisting>
    179 <literal>http://www.ggzgamingzone.org/</literal>
    180 <literal>http://www.ggzgamingzone.org/docs/api/libggz/</literal>
    181 <literal>http://www.ggzgamingzone.org/docs/api/ggzcore/</literal>
    182 <literal>http://www.ggzgamingzone.org/docs/api/ggzmod/</literal>
    183 </programlisting></para>
    184 </listitem>
    185 </varlistentry>
    186 </variablelist>
    187 </refsect1>
    188 
    189 <refsect1 id="libggz-3-note"><title>&note-tt;</title>
    190    <para>Written by Michal Pryc, Sun Microsystems Inc., 2008.</para>
    191 </refsect1>
    192 </refentry>
    193