1<?xml version="1.0" encoding="UTF-8"?> 2 3<section id="gdbm"><title>GDBM - The GNU database manager</title> 4 5<para>This is an interface to the &gdbm;, which extends the standard 6 &unix; <filename role="unix">ndbm.h</filename>.</para> 7<simpara>When this module is present, &features-my; contains the 8 symbol <constant>:GDBM</constant>.</simpara> 9 10<simpara>See <filename role="clisp-cvs">modules/gdbm/test.tst</filename> 11 for sample usage.</simpara> 12 13<variablelist id="gdbm-api"><title>GDBM module API</title> 14 <varlistentry id="gdbm-version"><term><code>(GDBM:GDBM-VERSION)</code></term> 15 <listitem><para>Return the version string.</para></listitem></varlistentry> 16 <varlistentry id="gdbm-open"><term><code>(GDBM:GDBM-OPEN &filename-r; 17 &key-amp; :BLOCKSIZE :READ-WRITE :OPTIONS 18 :MODE :DEFAULT-KEY-TYPE :DEFAULT-VALUE-TYPE)</code></term> 19 <listitem><para>Open &filename-r; database file. 20 The return value is a <type>GDBM</type> structure. 21 <constant>:READ-WRITE</constant> can have one of following values: 22 <simplelist><member>&reader-k;</member><member>&writer-k;</member> 23 <member><constant>:WRCREAT</constant></member> 24 <member><constant>:NEWDB</constant></member> 25 </simplelist></para> 26 <para><constant>:OPTIONS</constant> is a combination of <simplelist> 27 <member><constant>:FAST</constant></member> 28 <member><constant>:SYNC</constant></member> 29 <member><constant>:NOLOCK</constant></member> 30 <member><constant>:NOMMAP</constant></member> 31 <member><constant>:CLOEXEC</constant></member> 32 <member><constant>:BSEXACT</constant></member> 33 </simplelist></para> 34 <para><constant>:MODE</constant> is the numeric file permission mode 35 (cf. <function role="unix">open</function>), use 36 <link linkend="convert-mode"><function>POSIX:CONVERT-MODE</function></link> 37 to extract it from a list of keywords.</para> 38 <para>&clisp; can store and retrieve values of the 39 following types:<simplelist><member>&string-t;</member> 40 <member>&vector-t; (meaning anything that can be &coerce;d to 41 &ubyte-vec;)</member> 42 <member><literal role="type">EXT:32BIT-VECTOR</literal> (meaning 43 <literal role="type">(&vector-t; &ubyte-32;)</literal>)</member> 44 <member>&integer-t;</member><member>&single-float-t;</member> 45 <member>&double-float-t;</member></simplelist> 46 and <constant>:DEFAULT-KEY-TYPE</constant> 47 and <constant>:DEFAULT-VALUE-TYPE</constant> should be one of 48 those. If not specified (or &nil;), the &type-k; 49 argument is required in the access functions below.</para> 50 <para>If &filename-r; is actually an existing <type>GDBM</type> structure, 51 then it is re-opened (if it has been closed), and returned as is.</para> 52 <para>The return value is &finalize;d with 53 <link linkend="gdbm-close"><function>GDBM-CLOSE</function></link>.</para> 54 </listitem></varlistentry> 55 <varlistentry id="gdbm-path"> 56 <term><code>(GDBM:GDBM-PATH &db-r;)</code></term> 57 <listitem><para>Return the original &filename-r; passed to .</para> 58 </listitem></varlistentry> 59 <varlistentry id="gdbm-close"> 60 <term><code>(GDBM:GDBM-CLOSE &db-r;)</code></term> 61 <listitem><simpara>Close the database. 62 </simpara></listitem></varlistentry> 63 <varlistentry id="gdbm-open-p"> 64 <term><code>(GDBM:GDBM-OPEN-P &db-r;)</code></term> 65 <listitem><simpara>Check whether &db-r; has been already closed.</simpara> 66 <warning><simpara>Only the above functions accept closed databases, 67 the following functions &sig-err; when passed a closed database. 68 </simpara></warning></listitem></varlistentry> 69 <varlistentry id="gdbm-store"> 70 <term><code>(GDBM:GDBM-STORE &db-r; &key-r; &cont-r; &key-amp; 71 :FLAG)</code></term> 72 <listitem><para>&db-r; is the <type>GDBM</type> structure returned by 73 &gdbm-open;. &key-r; is the key datum. 74 &cont-r; is the data to be associated with the key. 75 <constant>:FLAG</constant> can have one of following values: 76 <simplelist><member><constant>:INSERT</constant></member> 77 <member><constant>:REPLACE</constant></member></simplelist> 78 </para></listitem></varlistentry> 79 <varlistentry id="gdbm-fetch"> 80 <term><code>(GDBM:GDBM-FETCH &db-r; &key-r; &key-amp; 81 (TYPE (GDBM:GDBM-OPT &db-r; :DEFAULT-VALUE-TYPE)))</code></term> 82 <listitem><simpara>Search the database. 83 The &type-k; argument specifies the return type. 84 </simpara></listitem></varlistentry> 85 <varlistentry id="gdbm-delete"> 86 <term><code>(GDBM:GDBM-DELETE &db-r; &key-r;)</code></term> 87 <listitem><simpara>Delete &key-r; and its contents. 88 </simpara></listitem></varlistentry> 89 <varlistentry id="gdbm-exists"> 90 <term><code>(GDBM:GDBM-EXISTS &db-r; &key-r;)</code></term> 91 <listitem><simpara>Search data without retrieving it. 92 </simpara></listitem></varlistentry> 93 <varlistentry id="gdbm-firstkey"> 94 <term><code>(GDBM:GDBM-FIRSTKEY &db-r; &key-amp; 95 (TYPE (GDBM:GDBM-OPT &db-r; :DEFAULT-KEY-TYPE)))</code></term> 96 <listitem><simpara>Return the key of the first entry, as &type-k;. 97 If the database has no entries, the return value is &nil;. 98 </simpara></listitem></varlistentry> 99 <varlistentry id="gdbm-nextkey"> 100 <term><code>(GDBM:GDBM-NEXTKEY &db-r; &key-r; &key-amp; 101 (TYPE (GDBM:GDBM-OPT &db-r; :DEFAULT-KEY-TYPE)))</code></term> 102 <listitem><simpara>Return the key that follows &key-r;, as &type-k;, 103 or &nil; if there are no further entries. 104 </simpara></listitem></varlistentry> 105 <varlistentry id="gdbm-reorganize"> 106 <term><code>(GDBM:GDBM-REORGANIZE &db-r;)</code></term> 107 <listitem><simpara>Reorganize the database. 108 </simpara></listitem></varlistentry> 109 <varlistentry id="gdbm-sync"> 110 <term><code>(GDBM:GDBM-SYNC &db-r;)</code></term> 111 <listitem><simpara>Syncronize the in-memory state of the database to 112 the disk file.</simpara></listitem></varlistentry> 113 <varlistentry id="gdbm-opt"> 114 <term><code>(GDBM:GDBM-OPT &db-r; &option-r;)</code></term> 115 <term><code>(&setf; (GDBM:GDBM-OPT &db-r; &option-r;) &value-r;)</code></term> 116 <listitem><para>Set or retrieve options of an already open database. 117 &option-r; is one of following: 118 <variablelist> 119 <varlistentry><term><constant>:FLAGS</constant></term> 120 <listitem><simpara>Retrieve the <constant>:READ-WRITE</constant> 121 and <constant>:OPTIONS</constant> passed to &gdbm-open; 122 (read-only).</simpara></listitem></varlistentry> 123 <varlistentry><term><constant>:CACHESIZE</constant></term> 124 <listitem><simpara>Retrieve and set the size of the internal 125 bucket cache.</simpara></listitem></varlistentry> 126 <varlistentry><term><constant>:MAXMAPSIZE</constant></term> 127 <listitem><simpara>Retrieve and set the maximum size of a memory 128 mapped region.</simpara></listitem></varlistentry> 129 <varlistentry><term><constant>:BLOCKSIZE</constant></term> 130 <listitem><simpara>Retrieve the block size in bytes (read-only). 131 </simpara></listitem></varlistentry> 132 <varlistentry><term><constant>:MMAP</constant></term> 133 <listitem><simpara>Retrieve and enable or disable memory mapping mode. 134 </simpara></listitem></varlistentry> 135 <varlistentry><term><constant>:SYNCMODE</constant></term> 136 <listitem><simpara>Retrieve or set file system synchronization mode. 137 </simpara></listitem></varlistentry> 138 <varlistentry><term><constant>:CENTFREE</constant></term> 139 <listitem><simpara>Retrieve or set central free block pool handling. 140 </simpara></listitem></varlistentry> 141 <varlistentry><term><constant>:COALESCEBLKS</constant></term> 142 <listitem><simpara>Retrieve or set free block merging. 143 </simpara></listitem></varlistentry> 144 <varlistentry><term><constant>:DBNAME</constant></term> 145 <listitem><simpara>Retrieve the namestring of the database (read-only). 146 </simpara></listitem></varlistentry> 147 <varlistentry><term><constant>:DEFAULT-VALUE-TYPE</constant></term> 148 <term><constant>:DEFAULT-KEY-TYPE</constant></term> 149 <listitem><simpara>The default data conversion types, see &gdbm-open;. 150 </simpara></listitem></varlistentry> 151 </variablelist></para></listitem></varlistentry> 152 <varlistentry id="gdbm-file-size"> 153 <term><code>(GDBM:GDBM-FILE-SIZE &db-r;)</code></term> 154 <listitem><simpara>Return the underlying file size using 155 <function role="unix">lseek</function>.</simpara></listitem></varlistentry> 156 <varlistentry id="gdbm-count"> 157 <term><code>(GDBM:GDBM-COUNT &db-r;)</code></term> 158 <listitem><simpara>Return the number of records in the database. 159 </simpara></listitem></varlistentry> 160 <varlistentry id="gdbm-do-db"> 161 <term><code>(GDBM:DO-DB (&key-r; &db-r; &rest-amp; &options-r;) 162 &body-amp; &body-r;)</code></term> 163 <listitem><simpara>Iterate over the database keys, &options-r; are 164 passed to <function>GDBM-FIRSTKEY</function> 165 and <function>GDBM-NEXTKEY</function>. 166 &body-r; is passed to &loop;, so you can use all the standard loop 167 contructs, e.g., <code>(do-db (k db) :collect (list k (gdbm-fetch 168 k)))</code> will convert the database to an &alist;. 169 </simpara></listitem></varlistentry> 170 <varlistentry id="gdbm-with-open-db"> 171 <term><code>(GDBM:WITH-OPEN-DB (&db-r; &filename-r; &rest-amp; &options-r;) 172 &body-amp; &body-r;)</code></term> 173 <listitem><simpara>Open the &filename-r;, execute the &body-r;, close 174 the database.</simpara></listitem></varlistentry> 175</variablelist> 176 177</section> 178