QDBM 基本调用API规范
VERSION 1
（此文档非正式文档，仅仅是我自己为了便于自己理解qdbm api 接口调用顺便翻译。转载请注明出处！-20161018-lgm）
概述
QDBM 是一个常规的管理型数据库调用库。这个数据库是一种简单的记录型数据库，每一条记录是一个包含key 和value的键值对.每一对key和value是一个可变长的字节序.二进制形式和字符串形式都可以作为他的key和value.它是一个没有表格也没有数据类型的一种数据库形式。每条记录以hash表或者B+ 树的形式组织。
关于这种hash表形式的数据库，每一个key在数据库中必须是唯一，因此不可能存在两个或多个key 完全一样的记录.以下我们提供了一系列的方法来访问数据库，比如：通过一个key和value存储一条记录,通过一个key删除一条记录，通过一个key检索一条记录，此外，遍历每一条记录，当然顺序是随意的我们不进行排序。在linux中访问数据库的方法和大多数的DBM （NDBM ，GDBM）具有类似的接口定义。QDBM 是一个好的方式去替代其它数据库，因为它具有较好的性能表现。
相对于hash 表，B+树形式存储，它是可以存储重复的key值记录的。同样的增加，删除，遍历，查找的我们也提供类似hash表的API调用。记录可以通过用户定义排序方法顺序的存储。我们可以通过一个游标以升序或者降序的形式访问，根据这种机制呢，我们可以做一个字符串的匹配的查询，或者实现一个整数范围内的查询。此外，遍历数据库记录在B+ 树也是可用的。
QDBM是用C写的一个数据库，提供有一系列语言的API,其中包括有C，C++.JAVA,Perl, 和Ruby。QDBM在所有符合POSIX标准的平台上这些API都是可用的。QDBM 是一个在LGPL License 授权下试用的免费使用的软件。
基础API：
Depot 是QDBM的一个基础API,实现了几乎所有用于管理QDBM数据库功能的API调用。其它的API调用基本上只是把Depot API调用做了一次包装。Depot是所有API调用中最快的。为了你能正常的使用Depot , 你需要在你的源文件中包含”depot.h”头文件和”stdlib.h”头文件。通常情况下这两个文件我们应该把它放在源文件的最开始的位置。
#include <depot.h>
#include <stdlib.h>
一个用于指向数据库操作的句柄指针 “DEPOT”，这也就是好比如我们需要操作文件时使用的”stdio.h”里面用的”FILE” 文件指针。数据库可以通过“dpopen”函数调用打开，通过“dpclose”函数调用关闭。你不应该直接手动去操作数据库句柄的成员，如果出现了致命错误，除了关闭操作”dpclose”方法，任何的访问方法都会不正常并且会返回一个错误状态代码。同一个进程可以同时使用两个数据库操作句柄，但是同时操作同一个数据库文件我们并不建议你这样去操作。
API
extern const char *dpversion;
“dpversion”全局外部变量是一个字符串变量，定义了版本相关的信息。
extern int dpcode
“dpcode”全局外部变量定义了最后的错误状态码，所有的错误状态码的详细信息我们都可以在“depot.h”头文件中查到。初始变量值是“DP_ENOERR”,其它定义有的值还有以下值：DP_EFATAL', DP_EMODE’, DP_EBROKEN', DP_EKEEP’, DP_ENOITEM', DP_EALLOC’, DP_EMAP', DP_EOPEN’, DP_ECLOSE', DP_ETRUNC’, DP_ESYNC', DP_ESTAT’, DP_ESEEK', DP_EREAD’, DP_EWRITE', DP_ELOCK’, DP_EUNLINK', DP_EMKDIR’, DP_ERMDIR', and DP_EMISC’.
const char *dperrmsg(int code)
“ecode”指一个特定的错误代码，函数的返回值是一个不可写的错误代码对应的错误信息字符串。
DEPOT *dpopen(const char *name, int omode, int bnum);
“name”是指定的数据库名称。“omode”是指定连接数据库所要进行的操作：“DP_OWRITER”指定写，“DP_OREADER”指定读，如果指定的操作模式是“DP_OWRITER”,那么你可能需要对操作模式操作做一个与的操作，进行“DP_OCREAT”,也就是说当数据库不存在的时候创建新的数据库文件。“DP_OTRUNC”操作意味着不管数据库存在或者不存在我们都创建一个新的数据库文件。对于“DP_OREADER”读操作和“DP_OWRITER”写操作，我们可以与上一个“DP_ONOLCK”操作，这意味着我们操作数据库的时候将不对数据文件上锁，或者我们可以与上一个“DP_OLCKNB“操作，这就意味着我们执行非阻塞式打开。对于“DP_OCREAT”
操作可以或上“DP_OSPARSE”操作，这代表创建一个松散的数据库文件。“bnum”代表元素阵列的数组元素个数，如果不大于0，则使用默认值，这一个阵列值是在创建数据库时就决定了的，并且通常情况下是不能改变的。建议的阵列数组大小设置为0.5到4的范围内。函数的返回值是一个数据库的操作句柄，如果返回NULL则代表数据库打开不成功，当以写方式打开数据库文件时，我们会对数据库执行独占写锁的调用，当以读方式打开时，我们会对数据库文件执行共享读锁调用，打开线程会阻塞，直到数据库被锁定，如果使用了“DP_ONOLCK”模式操作，则应用程序应该负责控制数据库文件的锁定。
Int dpclose(DEPOT *depot)
“depot”代表一个数据库操作句柄。如果函数调用成功，返回值为true否则返回false。关闭数据库操作句柄后，我们就不应该再继续使用此句柄。如果是更新数据，我们应该在数据库句柄关闭前写入数据。如果是以写方式打开数据库，但是又没有关闭数据库，则这个数据库将会被破坏。
Int dpput(DEPOT *depot)
“depot”是一个写操作的数据库句柄。“kbuf”是一个指向需要写的数据域的Key指针，”ksiz”是一个表示key数据域长度大小值，如果这个数是一个负数，这个大小通过“strlen(kbuf)”分配。“vbuf”是一个表示value数据域的指针，“vsiz”是一个表示value数据域长度的值，如果是负数，这个大小通过“strlen(vbuf)”分配，“dmode”表示如果出现重复key的时候所要进行的操作，可以有以下值：”DP_DOVER”表示覆盖现有的存在的值，“DP_DKEEP”表示保持现有数据库的值，“DP_DCAT”表示指定的值连接到现有值的末尾，如果函数执行成功返回true否则返回false。
Int dpout(DEPOT *depot, const char *kbuf, int ksiz)
“dpout”函数表示用于删除一条记录，“depot”表示一个写操作的数据库句柄，“kbuf”表示一个指向key数据域的一个指针，”ksiz”表示key数据域的大小。如果为负数，则大小通过“strlen(kbuf)”计算分配。如果函数执行成功，返回true否则返货false。 返回false表明函数执行失败，数据库中不存在这这要上出的key 的数据库记录。
char *dpget(DEPOT *depot, const char*kbuf, int ksiz, int start, int max, int *sp);
“dpget”用于检索获取一条数据库记录。“depot”表示数据库操作句柄，“kbuf”表示一个key数据域指针，“ksiz”表示key数据域指针的大小，如果为负数，则key数据域指针使用“strlen(kbuf)”计算分配大小，“start”表示检索的起始数据库记录偏移，”max”表示读取的最大的数据库记录数，如果为负数，则表示无限制。“sp”表示一个用户返回数据库记录的变量的指针，如果为NULL，表示不适用此指针。如果函数执行成功，返回指向相应数据记录的指针，否则返回NULL。如果返回NULL，表明没有相应的key 值的记录存在数据库中，或者是size的值小于start的起始的值。由于返回的记录值会在末尾追加一个结束符‘\0’，所以返回值可以当做一个字符串进行处理。由于返回值的指针区域是使用malloc 函数动态分配的，所以在使用完后应该做release释放处理。
int dpgetwb(DEPOT *depot, const char *kbuf, int ksiz, int start, int max, char *vbuf);
“dpgetwb” 是用于检索一条数据库记录，并存入指定的指针区域。“depot”指向需要操作的数据库句柄。“kbuf”是一个指向key数据域的指针。“ksiz”表示key数据域的大小。如果为负数，则大小使用“strlen(kbuf)”计算。”start”表示开始检索的数据库记录的起始偏移地址。
“max”表示检索的最大长度。最大应该小于或等于缓冲区的大小。“vbuf”表示检索出的数据库记录的value值存储的buffer 地址。如果函数调用成功，返回写入”vbuf”的数据大小，否则返回“-1”.返回“-1”还有可能是数据库没有指定的key值的记录，或者查询的size大小小于开始start偏移量。注意查询的结果写入进“vbuf”是不带结束符‘\0’的。