gdbm.html

开源的数据库管理系统 说明文档！ gdbm 适用场合很多

<p>The function <code>gdbm_store</code> inserts or replaces records in the database.

<pre class="example">     ret = gdbm_store(dbf, key, content, flag);
     </pre>

   <p>The parameters are:

     <dl>
<dt>GDBM_FILE dbf
     <dd>The pointer returned by <code>gdbm_open</code>. 
<br><dt>datum key
     <dd>The <code>key</code> data. 
<br><dt>datum content
     <dd>The data to be associated with the key. 
<br><dt>int flag
     <dd>Defines the action to take when the key is already in the database. The value
GDBM_REPLACE (defined in <code>gdbm.h</code>) asks that the old data be replaced by
the new <code>content</code>. The value GDBM_INSERT asks that an error be returned
and no action taken if the <code>key</code> already exists. 
</dl>

   <p>The values returned in <code>ret</code> are:

     <dl>
<dt>-1
     <dd>The item was not stored in the database because the caller was not an
official writer or either <code>key</code> or <code>content</code> have a NULL dptr field. 
Both <code>key</code> and <code>content</code> must have the dptr field be a non-NULL value. 
Since a NULL dptr field is used by other functions to indicate an error, a NULL
field cannot be valid data. 
<br><dt>+1
     <dd>The item was not stored because the argument <code>flag</code> was GDBM_INSERT and
the <code>key</code> was already in the database. 
<br><dt>0
     <dd>No error. <code>content</code> is keyed by <code>key</code>. The file on disk is updated
to reflect the structure of the new database before returning from this
function. 
</dl>

   <p>If you store data for a <code>key</code> that is already in the data base,
<code>gdbm</code> replaces the old data with the new data if called with
GDBM_REPLACE. You do not get two data items for the same <code>key</code> and you do
not get an error from <code>gdbm_store</code>.

   <p>The size in <code>gdbm</code> is not restricted like <code>dbm</code> or <code>ndbm</code>. Your
data can be as large as you want.

<div class="node">
<p><hr>
Node:&nbsp;<a name="Fetch">Fetch</a>,
Next:&nbsp;<a rel="next" accesskey="n" href="#Delete">Delete</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="#Store">Store</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
<br>
</div>

<h2 class="chapter">7 Searching for records in the database.</h2>

<p>Looks up a given <code>key</code> and returns the information associated with that
key. The pointer in the structure that is  returned is a pointer to dynamically
allocated memory block. To search for some data:

<pre class="example">     content = gdbm_fetch(dbf, key);
     </pre>

   <p>The parameters are:

     <dl>
<dt>GDBM_FILE dbf
     <dd>The pointer returned by <code>gdbm_open</code>. 
<br><dt>datum key
     <dd>The <code>key</code> data. 
</dl>

   <p>The datum returned in <code>content</code> is a pointer to the data found. If the
dptr is NULL, no data was found. If dptr is not NULL, then it points
to data allocated by malloc. <code>gdbm</code> does not automatically free this data. 
The user must free this storage when done using it. This eliminates the
need to copy the result to save it for later use (you just save the pointer).

   <p>You may also search for a particular key without retrieving it, using:

<pre class="example">     ret = gdbm_exists(dbf, key);
     </pre>

   <p>The parameters are:

     <dl>
<dt>GDBM_FILE dbf
     <dd>The pointer returned by <code>gdbm_open</code>. 
<br><dt>datum key
     <dd>The <code>key</code> data. 
</dl>

   <p>Unlike <code>gdbm_fetch</code>, this routine does not allocate any memory, and
simply returns true or false, depending on whether the <code>key</code> exists,
or not.

<div class="node">
<p><hr>
Node:&nbsp;<a name="Delete">Delete</a>,
Next:&nbsp;<a rel="next" accesskey="n" href="#Sequential">Sequential</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="#Fetch">Fetch</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
<br>
</div>

<h2 class="chapter">8 Removing records from the database.</h2>

<p>To remove some data from the database:

<pre class="example">     ret = gdbm_delete(dbf, key);
     </pre>

   <p>The parameters are:

     <dl>
<dt>GDBM_FILE dbf
     <dd>The pointer returned by <code>gdbm_open</code>. 
<br><dt>datum key
     <dd>The <code>key</code> data. 
</dl>

   <p>The ret value is -1 if the item is not present or the requester is a reader. 
The ret value is 0 if there was a successful delete.

   <p><code>gdbm_delete</code> removes the keyed item and the <code>key</code> from the database
<code>dbf</code>. The file on disk is updated to reflect the structure of the new
database before returning from this function.

<div class="node">
<p><hr>
Node:&nbsp;<a name="Sequential">Sequential</a>,
Next:&nbsp;<a rel="next" accesskey="n" href="#Reorganization">Reorganization</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="#Delete">Delete</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
<br>
</div>

<h2 class="chapter">9 Sequential access to records.</h2>

<p>The next two functions allow for accessing all items in the database. This
access is not <code>key</code> sequential, but it is guaranteed to visit every
<code>key</code> in the database once. The order has to do with the hash values. 
<code>gdbm_firstkey</code> starts the visit of all keys in the database. 
<code>gdbm_nextkey</code> finds and reads the next entry in the hash structure for
<code>dbf</code>.

<pre class="example">     key = gdbm_firstkey(dbf);
     
     nextkey = gdbm_nextkey(dbf, key);
     </pre>

   <p>The parameters are:

     <dl>
<dt>GDBM_FILE dbf
     <dd>The pointer returned by <code>gdbm_open</code>. 
<br><dt>datum <code>key</code>
     <dd><br><dt>datum nextkey
     <dd>The <code>key</code> data. 
</dl>

   <p>The return values are both datum. If <code>key</code>.dptr or nextkey.dptr is NULL,
there is no first <code>key</code> or next <code>key</code>. Again notice that dptr points to
data allocated by malloc and <code>gdbm</code> will not free it for you.

   <p>These functions were intended to visit the database in read-only algorithms,
for instance, to validate the database or similar operations.

   <p>File <code>visiting</code> is based on a <code>hash table</code>. <code>gdbm_delete</code>
re-arranges the hash table to make sure that any collisions in the table do not
leave some item <code>un-findable</code>. The original key order is NOT guaranteed to
remain unchanged in ALL instances. It is possible that some key will not be
visited if a loop like the following is executed:

<pre class="example">        key = gdbm_firstkey ( dbf );
        while ( key.dptr ) {
           nextkey = gdbm_nextkey ( dbf, key );
           if ( some condition ) {
              gdbm_delete ( dbf, key );
              free ( key.dptr );
           }
           key = nextkey;
        }
     </pre>

<div class="node">
<p><hr>
Node:&nbsp;<a name="Reorganization">Reorganization</a>,
Next:&nbsp;<a rel="next" accesskey="n" href="#Sync">Sync</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="#Sequential">Sequential</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
<br>
</div>

<h2 class="chapter">10 Database reorganization.</h2>

<p>The following function should be used very seldom.

<pre class="example">     ret = gdbm_reorganize(dbf);
     </pre>

   <p>The parameter is:

     <dl>
<dt>GDBM_FILE dbf
     <dd>The pointer returned by <code>gdbm_open</code>. 
</dl>

   <p>If you have had a lot of deletions and would like to shrink the space
used by the <code>gdbm</code> file, this function will reorganize the database. 
<code>gdbm</code> will not shorten the length of a <code>gdbm</code> file (deleted file space will be
reused) except by using this reorganization.

   <p>This reorganization requires creating a new file and inserting all the elements
in the old file <code>dbf</code> into the new file. The new file is then renamed to
the same name as the old file and <code>dbf</code> is updated to contain all the
correct information about the new file. If an error is detected, the return
value is negative. The value zero is returned after a successful
reorganization.

<div class="node">
<p><hr>
Node:&nbsp;<a name="Sync">Sync</a>,
Next:&nbsp;<a rel="next" accesskey="n" href="#Errors">Errors</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="#Reorganization">Reorganization</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
<br>
</div>

<h2 class="chapter">11 Database Synchronization</h2>

<p>Unless your database was opened with the GDBM_SYNC flag, <code>gdbm</code> does not
wait for writes to be flushed to the disk before continuing.  This allows
faster writing of databases at the risk of having a corrupted database if
the application terminates in an abnormal fashion.  The following function
allows the programmer to make sure the disk version of the
database has been completely updated with all changes to the current time.

<pre class="example">     gdbm_sync(dbf);
     </pre>

   <p>The parameter is:

     <dl>
<dt>GDBM_FILE dbf
     <dd>The pointer returned by <code>gdbm_open</code>. 
</dl>

   <p>This would usually be called after a complete set of changes have been
made to the database and before some long waiting time. 
<code>gdbm_close</code> automatically calls the equivalent of <code>gdbm_sync</code>
so no call is needed if the database is to be closed immediately after
the set of changes have been made.

<div class="node">
<p><hr>
Node:&nbsp;<a name="Errors">Errors</a>,
Next:&nbsp;<a rel="next" accesskey="n" href="#Options">Options</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="#Sync">Sync</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
<br>
</div>

<h2 class="chapter">12 Error strings.</h2>

<p>To convert a <code>gdbm</code> error code into English text, use this routine:

<pre class="example">     ret = gdbm_strerror(errno)
     </pre>

   <p>The parameter is:

     <dl>
<dt>gdbm_error errno
     <dd>The <code>gdbm</code> error code, usually <code>gdbm_errno</code>. 
</dl>

   <p>The appropiate phrase for reading by humans is returned.