gdbm.3.html

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

<p> 
<p> To search for some data, without retrieving
it: 
<p>   ret = gdbm_exists ( dbf, key )<br>
 
<p> <i>Dbf</i> is the pointer returned by <b>gdbm_open</b>.  <i>Key</i> is the key data to search
for. 
<p> If the <i>key</i> is found within the database, the return value <i>ret</i> will
be true.  If nothing appropiate is found, <i>ret</i> will be false. This routine
is useful for checking for the existance of a record, without performing
the memory allocation done by <b>gdbm_fetch</b>. 
<p> 
<p> To remove some data from the
database: 
<p>   ret = gdbm_delete ( dbf, key )<br>
 
<p> <i>Dbf</i> is the pointer returned by <b>gdbm_open</b>.  <i>Key</i> is the key data. 
<p> The return
value is -1 if the item is not present or the requester is a reader. The
return value is 0 if there was a successful delete. 
<p> 
<p> The next two routines
allow for accessing all items in the database.  This  access is not key
sequential, but it is guaranteed to visit every key in the database once.
 (The order has to do with the hash values.) 
<p>   key = gdbm_firstkey ( dbf
)<br>
 
<p>   nextkey = gdbm_nextkey ( dbf, key )<br>
 
<p> <i>Dbf</i> is the pointer returned by <b>gdbm_open</b>. <i>Key</i> is the key data. 
<p> The return
values are both of type <b>datum</b>.  If the <i>dptr</i> element of the return value
is NULL, there is no first key or next key. Again notice that <i>dptr</i> points
to data allocated by <a href='malloc.3C.html'><b>malloc(3C)</b></a>
 and <b>gdbm</b> 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 &lsquo;visiting&rsquo;
is based on a &lsquo;hash table&rsquo;.  <i>gdbm_delete</i> re-arranges the hash table to make
sure that any collisions in the table do not leave some item &lsquo;un-findable&rsquo;.
 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: 
<p>    key = gdbm_firstkey ( dbf );<br>
    while ( key.dptr ) {<br>
       nextkey = gdbm_nextkey ( dbf, key );<br>
       if ( some condition ) {<br>
          gdbm_delete ( dbf, key );<br>
          free ( key.dptr );<br>
       }<br>
       key = nextkey;<br>
    }<br>
 
<p> 
<p> The following routine should be used very infrequently.   <br>
   ret = gdbm_reorganize ( dbf )<br>
 
<p> If you have had a lot of deletions and would like to shrink the space
used by the <b>gdbm</b> file, this routine will reorganize the database. <b>Gdbm</b> will
not shorten the length of a <b>gdbm</b> file except by using this reorganization.
 (Deleted file space will be reused.) 
<p> 
<p> Unless your database was opened
with the GDBM_SYNC flag, gdbm does not wait for writes to be flushed to
the disk before continuing. The following routine can be used to guarantee
that the database is physically written to the disk file. 
<p>   gdbm_sync (
dbf )<br>
 
<p> It will not return until the disk file state is syncronized with the
in-memory state of the database. 
<p> 
<p> To convert a <b>gdbm</b> error code into English
text, use this routine: 
<p>   ret = gdbm_strerror ( errno )<br>
 
<p> Where <i>errno</i> is of type <i>gdbm_error</i>, usually the global variable <i>gdbm_errno</i>.
 The appropiate phrase is returned. 
<p> 
<p> <b>Gdbm</b> now supports the ability to set
certain options on an already open database. 
<p>   ret = gdbm_setopt ( dbf,
option, value, size )<br>
 
<p> Where <i>dbf</i> is the return value from a previous call to <b>gdbm_open</b>, and
<i>option</i> specifies which option to set.  The valid options are currently:

<p>   <b>GDBM_CACHESIZE</b> - Set the size of the internal bucket<br>
   cache. This option may only be set once on each <i>GDBM_FILE</i><br>
   descriptor, and is set automatically to 100 upon the first<br>
   access to the database.<br>
 
<p>   <b>GDBM_FASTMODE</b> - Set <b>fast mode</b> to either on or off.  This<br>
   allows <b>fast mode</b> to be toggled on an already open and<br>
   active database. <i>value</i> (see below) should be set to either<br>
   TRUE or FALSE.  <i>This option is now obsolete.</i><br>
 
<p>   <b>GDBM_SYNCMODE</b> - Turn on or off file system synchronization operations.<br>
   This setting defaults to off; <i>value</i> (see below) should be set to either<br>
   TRUE or FALSE.<br>
 
<p>   <b>GDBM_CENTFREE</b> - Set <b>central free block pool</b> to either on or off.<br>
   The default is off, which is how previous versions of <b>Gdbm</b><br>
   handled free blocks. If set, this option causes all subsequent free<br>
   blocks to be placed in the <b>global</b> pool, allowing (in thoery)<br>
   more file space to be reused more quickly. <i>value</i> (see below) should<br>
   be set to either TRUE or FALSE.<br>
   <i>NOTICE: This feature is still under study.</i><br>
 
<p>   <b>GDBM_COALESCEBLKS</b> - Set <b>free block merging</b> to either on or off.<br>
   The default is off, which is how previous versions of <b>Gdbm</b><br>
   handled free blocks. If set, this option causes adjacent free blocks<br>
   to be merged. This can become a CPU expensive process with time, though,<br>
   especially if used in conjunction with <b>GDBM_CENTFREE</b>. <i>value</i><br>
   (see below) should be set to either TRUE or FALSE.<br>
   <i>NOTICE: This feature is still under study.</i><br>
 
<p> <i>value</i> is the value to set <i>option</i> to, specified as an integer pointer.
 <i>size</i> is the size of the data pointed to by <i>value</i>. The return value will
be -1 upon failure, or 0 upon success.  The global variable <i>gdbm_errno</i> will
be set upon failure. 
<p> For instance, to set a database to use a cache of
10, after opening it with <b>gdbm_open</b>, but prior to accessing it in any way,
the following code could be used: 
<p>   int value = 10;<br>
   <br>
   ret = gdbm_setopt( dbf, GDBM_CACHESIZE, &amp;value, sizeof(int));<br>
 
<p> 
<p> If the database was opened with the <b>GDBM_NOLOCK</b> flag, the user may wish
to perform their own file locking on the database file in order to prevent
multiple writers operating on the same file simultaneously. 
<p> In order to
support this, the <i>gdbm_fdesc</i> routine is provided. 
<p>   ret = gdbm_fdesc (
dbf )<br>
 
<p> Where <i>dbf</i> is the return value from a previous call to <b>gdbm_open</b>. The return
value will be the file descriptor of the database. 
<p> The following two external
variables may be useful: 
<p> <i>gdbm_errno</i> is the variable that contains more
information about gdbm errors.  (gdbm.h has the definitions of the error
values and defines gdbm_errno as an external variable.) <br>
<i>gdbm_version</i> is the string containing the version information. 
<p> 
<p> There are
a few more things of interest.  First, <b>gdbm</b> files are not "sparse".  You
can copy them with the UNIX <a href='cp.1.html'><b>cp(1)</b></a>
 command and they will not expand in the
copying process.  Also, there is a compatibility mode for use with programs
that already use UNIX <b>dbm</b>.  In this compatibility mode, no gdbm file pointer
is required by the programmer, and only one file may be opened at a time.
All users in compatibility mode are assumed to be writers.  If the <b>gdbm</b>
file is a read only, it will fail as a writer, but will also try to open
it as a reader.  All returned pointers in datum structures point to data
that <b>gdbm</b> WILL free.  They should be treated as static pointers (as standard
UNIX <b>dbm</b> does). 
<p> 
<p> 
<h2><a name='sect3' href='#toc3'>Linking</a></h2>
This library is accessed by specifying <i>-lgdbm</i> as
the last parameter to the compile line, e.g.: <p>
<tt> </tt>&nbsp;<tt> </tt>&nbsp;gcc -o prog prog.c -lgdbm<br>
 
<p> If you wish to use the <b>dbm</b> or <b>ndbm</b> compatibility routines, you must link
in the <i>gdbm_compat</i> library as well.  For example: <p>
<tt> </tt>&nbsp;<tt> </tt>&nbsp;gcc -o prog proc.c -lgdbm
-lgdbm_compat<br>
 
<p> 
<h2><a name='sect4' href='#toc4'>Bugs</a></h2>

<p> 
<h2><a name='sect5' href='#toc5'>See Also</a></h2>
dbm, ndbm 
<p> 
<h2><a name='sect6' href='#toc6'>Author</a></h2>
by Philip A. Nelson and Jason Downs. Copyright
(C) 1990 - 1999 Free Software Foundation, Inc. 
<p> GDBM is free software; you
can redistribute it and/or modify it under the terms of the GNU General
Public License as published by the Free Software Foundation; either version
1, or (at your option) any later version. 
<p> GDBM is distributed in the hope
that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details. 
<p> You should have received a
copy of the GNU General Public License along with GDBM; see the file COPYING.
 If not, write to the Free Software Foundation, 675 Mass Ave, Cambridge,
MA 02139, USA. 
<p> You may contact the original author by: <br>
   e-mail:  [e-mail]<br>
 <br>
  us-mail:  Philip A. Nelson<br>
 <br>
Computer Science Department <br>
Western Washington University <br>
Bellingham, WA 98226 
<p> You may contact the current maintainer by: <br>
   e-mail:  [e-mail]<br>
 
<p> <p>

<hr><p>
<a name='toc'><b>Table of Contents</b></a><p>
<ul>
<li><a name='toc0' href='#sect0'>Name</a></li>
<li><a name='toc1' href='#sect1'>Synopsis</a></li>
<li><a name='toc2' href='#sect2'>Description</a></li>
<li><a name='toc3' href='#sect3'>Linking</a></li>
<li><a name='toc4' href='#sect4'>Bugs</a></li>
<li><a name='toc5' href='#sect5'>See Also</a></li>
<li><a name='toc6' href='#sect6'>Author</a></li>
</ul>
</body>
</html>