25.2. Basic Operations 25.2.1. Opening a qdbm File The dpopen() library function is used to open db files. #include <depot.h> DB * dpopen(const char * filename, int omode, int bnum);
The first argument is the name of the file to use for the database.[4] The omode specifies how the file should be accessed, and should be DP_OREADER or DP_OWRITER, depending on whether the program wants read or write access to the database. By default, the database is locked to allow multiple programs read access or a single program write access. If the application does not want qdbm to perform any locking, DP_ONOLCK may be bitwise OR'ed with omode. [4] Unlike some database libraries that use multiple files, commonly ending with .pag and .dir,the Depot library uses a single file.
When applications are creating new databases, they should also bitwise OR DP_CREAT to tell qdbm to create a new file if it does not already exist. The DP_OTRUNC flag causes whatever contents filename originally contained to be erased and replaced with an empty database. The final parameter for dpopen(), bnum, tells qdbm how many buckets to use in the hash array. The lower this number is, the smaller the database; the larger it is, the faster it is, due to reducing the number of hash collisions. The qdbm documentation recommends that this number be anywhere from half to four times the number of items that are expected to be in the database.[5] If you are not sure what number to use, zero gives a default value.[6] [5] For a good introduction to hash tables, see [Cormen, 1992].
[6] This value can be changed only by optimizing the database with dpoptimize(), which is documented on the qdbm Web site.
dpopen() returns a pointer to a DEPOT structure, which is passed into the rest of the Depot functions. If an error occurs, dpopen() returns NULL and sets dpecode. 25.2.2. Closing a Database Database files are closed through dpclose(). int dpclose(DEPOT * depot);
The dpclose() function returns zero on success, and nonzero if it fails, which can occur if the database's buffers cannot be flushed for any reason. Here is an example program that opens a database file in the current directory and immediately closes it: 1: /* qdbmsimple.c */ 2: 3: #include <depot.h> 4: #include <errno.h> 5: #include <fcntl.h> 6: #include <stdio.h> 7: 8: int main(void) { 9: DEPOT * dp; 10: 11: dp = dpopen("test.db", DP_OWRITER | DP_OCREAT, 0); 12: if (!dp) { 13: printf("error: %s\n", dperrmsg(dpecode)); 14: return 1; 15: } 16: 17: dpclose(dp); 18: 19: return 0; 20: }
25.2.3. Obtaining the File Descriptor While qdbm provides automatic locking, some programs may wish to substitute their own locking logic. To enable this, qdbm provides access to the file descriptor that refers to the database. int dpfdesc(DEPOT * depot);
This function returns the file descriptor the database referred to by depot.[7] [7] While qdbm makes the file descriptor available, be careful how you use it. All reading and writing to the file should be done through the qdbm library; operations that do not modify the data of the file, such as locking or setting the close-on-exec flag are acceptable.
25.2.4. Syncing the Database Qdbm caches data in RAM to provide faster database access, and the Linux kernel caches disk writes for low-latency write() calls. An application can ensure that the on-disk database is consistent with the buffered structures by syncing the database. When a database is synced, qdbm flushes all its internal buffers and calls fsync() on the file descriptor. int dpsync(DEPOT * depot);
| 
