source: branches/samba-3.2.x/docs-xml/Samba3-Developers-Guide/gencache.xml@ 231

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
<chapter id="gencache">
<chapterinfo>
        <author>
                <firstname>Rafal</firstname><surname>Szczesniak</surname>
        </author>
        <pubdate>April 2003</pubdate>
</chapterinfo>

<title>General cache mechanism and API</title>

<sect1>
<title>Abstract</title>
<para>
General cache (gencache) was designed to combine various kinds of caching
mechanisms into one, defined by a simple API. This way, anyone can use it
to create their own caching layer on top of gencache. An example of
such approach is the netbios name cache.
</para>
</sect1>

<sect1>
<title>The mechanism</title>
<para>
Gencache utilises <emphasise>tdb</emphasise> database, like many other
parts of Samba. As its origins are in Berkeley DB implementation, it
uses key/value pairs stored in binary file. The values gencache
operates on are string-based, however. This makes very easy to use it
in command line environment eg. to quickly take a look at what's in
the cache or set some value.
</para>

<para>
All the data is stored in <filename>gencache.tdb</filename>
file. Records put there are in key/value format as mentioned below,
but as it's a cache, the timeout plays also important role and has a
special place in the key/value pair, as well as API.
</para>
</sect1>


<sect1>
<title>The data structure</title>
<para>
The record stored in <filename>gencache.tdb</filename> file consists
of the key, the value and the expiration timeout. While the first part
is stored completely independent from the others, the last two are
kept together. The form the record has is:
</para>

<para><programlisting>
key:     &lt;string&gt;
value:   &lt;12-digit timeout&gt;/&lt;string&gt;
</programlisting></para>

<para>The timeout part is the ASCII representation of
<emphasis>time_t</emphasis> value of the time when the cache entry
expires. Obviously the API, the programmer is provided with, hides this detail,
so that you don't have to care about checking it. Simply watch
carefully the return status of the function.
</para>
</sect1>

<sect1>
<title>The API</title>

<para><programlisting>
BOOL gencache_init()
</programlisting></para>