25.1. Overview Qdbm provides quite a few different APIs. The most basic of them, Depot, is the lowest-level API and the one we discuss here. The Curia interface allows the database to be split into multiple files (for better scalability or to work around file system limits) and the Villa functions provide both B-Trees and a transaction model. Inverted indexes[3] are available through the Odeon API. The final two APIs are Relic and Hovel, which provide reimplementations of the ndbm and gdbm APIs. [3] Inverted indexes are a data structure designed for full text searches The Depot functions provide basic key/value operations, where a key is used to retrieve the value. Both the key and value are arbitrary binary streams that have their size passed separately from the data; the library does not need to know anything about their structure. However, Depot has a couple of features that make using strings as both keys and data items more convenient. First, whenever the size of a key or data item is passed into the library, -1 can be passed instead, which tells Depot to use strlen() to calculate the size to use. Second, most functions that read keys and data items automatically append a 0 byte to the returned value. This extra character is not included in the size returned, so it can be ignored if the value is not a string. If it is a string, the returned value can be treated as a string without the application having to NULL-terminate it. Depot uses the global integer dpecode to store error codes; when Depot functions return failures, dpecode tells what went wrong (this is just like the errno variable used by system calls and the C library). Text error messages are provided by dperrmsg(). #include <depot.h> const char * dperrmsg(int ecode); Like strerror(), dperrmsg() takes an error code (normally from dpecode) and returns a string describing what went wrong. The functions in the Depot API use a pointer to a DEPOT structure. This structure is opaque (programs that use Depot cannot inspect the values in the structure itself), but contains all of the information the library uses to maintain the on-disk file. |