Linux程序员手册 第3部分
更新日期： 2017-09-15

名称

dbopen-数据库访问方法

语法

#include <sys/types.h>
#include <limits.h>
#include <db.h>
#include <fcntl.h>

DB *dbopen(const char *file, int flags, int mode, DBTYPE type,
           const void *openinfo);

说明

请注意：此页面记录了glibc所提供的接口，直至2.1版。从2.2版开始，glibc不再提供这些接口。可能您正在寻找libdb库提供的API。

dbopen()是数据库文件的库接口。支持的文件格式为btree，hash和UNIX文件格式。 btree格式表示已排序的平衡树结构。散列格式是一种可扩展的动态散列方案。平面文件格式是具有固定或可变长度记录的字节流文件。格式和特定​​于文件格式的信息在其各自的手册页btree(3)，hash(3)和recno(3)中进行了详细描述。

dbopen()打开文件进行读取和/或写入。可以通过将file参数设置为NULL来创建从不打算保留在磁盘上的文件。

这些标志和模式参数是open(2)例程所指定的，但是，只有O_CREAT，O_EXCL，O_EXLOCK，O_NONBLOCK，O_RDONLY，O_RDWR，O_SHLOCK和O_TRUNC标志才有意义。 (注意，无法打开数据库文件O_WRONLY。)

type参数的类型为DBTYPE(在包含文件中定义)，并且可以设置为DB_BTREE，DB_HASH或DB_RECNO。

openinfo参数是一个指向特定于访问方法的结构的指针，该结构在访问方法的手册页中进行了介绍。如果openinfo为NULL，则每种访问方法都将使用适合于系统和访问方法的默认值。

dbopen()成功时返回指向数据库结构的指针，错误时返回指向NULL的指针。 DB结构在包含文件中定义，并且至少包含以下字段：

typedef struct {
    DBTYPE type;
    int (*close)(const DB *db);
    int (*del)(const DB *db, const DBT *key, unsigned int flags);
    int (*fd)(const DB *db);
    int (*get)(const DB *db, DBT *key, DBT *data,
               unsigned int flags);
    int (*put)(const DB *db, DBT *key, const DBT *data,
               unsigned int flags);
    int (*sync)(const DB *db, unsigned int flags);
    int (*seq)(const DB *db, DBT *key, DBT *data,
               unsigned int flags);
} DB;

这些元素描述数据库类型和执行各种操作的一组功能。这些函数采用dbopen()返回的结构指针，有时还使用一个或多个指向键/数据结构和标志值的指针。

type

基础访问方法的类型(和文件格式)。

close

指向例程的指针，该例程将所有缓存的信息刷新到磁盘，释放所有分配的资源并关闭基础文件。由于密钥/数据对可能会缓存在内存中，因此无法通过关闭或同步功能同步文件可能会导致信息不一致或丢失。关闭例程在错误(设置errno)时返回-1，并在成功时返回0。

del

指向从数据库中删除密钥/数据对的例程的指针。

The argument flag

may be set to the following value:

R_CURSOR

删除光标引用的记录。游标必须事先已初始化。

删除例程在错误(设置errno)时返回-1，在成功时返回0，如果文件中没有指定的键，则返回1。

fd

指向例程的指针，该例程返回表示基础数据库的文件描述符。引用同一文件的文件描述符将返回给所有使用相同文件名调用dbopen()的进程。该文件描述符可以安全地用作fcntl(2)和flock(2)锁定函数的参数。文件描述符不一定与访问方法使用的任何基础文件相关联。内存数据库中没有文件描述符可用。 fd例程在错误(设置errno)时返回-1，在成功时返回文件描述符。

get

指向例程的指针，该例程是从数据库进行键检索的接口。与指定键关联的数据的地址和长度在数据引用的结构中返回。 get例程在错误(设置errno)时返回-1，在成功时返回0，如果密钥不在文件中，则返回1。

put

指向将密钥/数据对存储在数据库中的例程的指针。

The argument flag

may be set to one of the following values:

R_CURSOR

替换光标引用的键/数据对。游标必须事先已初始化。

R_IAFTER

在键引用的数据之后立即追加数据，从而创建新的键/数据对。在密钥结构中返回附加密钥/数据对的记录号。 (仅适用于DB_RECNO访问方法。)

R_IBEFORE

在密钥引用的数据之前立即插入数据，从而创建新的密钥/数据对。在密钥结构中返回插入的密钥/数据对的记录号。 (仅适用于DB_RECNO访问方法。)

R_NOOVERWRITE

仅当密钥先前不存在时才输入新的密钥/数据对。

R_SETCURSOR

存储键/数据对，设置或初始化光标位置以引用它。 (仅适用于DB_BTREE和DB_RECNO访问方法。)

R_SETCURSOR仅可用于DB_BTREE和DB_RECNO访问方法，因为它暗示键具有不变的固有顺序。

R_IAFTER和R_IBEFORE仅可用于DB_RECNO访问方法，因为它们每个都暗示该访问方法能够创建新的键。仅当键是有序的且独立的(例如记录号)时，才如此。

放置例程的默认行为是输入新的密钥/数据对，替换以前存在的任何密钥。

put例程在错误(设置errno)时返回-1，在成功时返回0，如果设置了R_NOOVERWRITE标志并且该文件中已经存在密钥，则返回1。

seq

指向例程的指针，该例程是从数据库顺序检索的接口。密钥的地址和长度在密钥引用的结构中返回，数据的地址和长度在数据引用的结构中返回。

顺序密钥/数据对检索可以随时开始，并且"光标"的位置不受del，get，put或sync例程的调用的影响。顺序扫描期间对数据库的修改将反映在扫描中，即，将不会返回插入在游标后面的记录，而将返回在游标前面插入的记录。

The flag value must

be set to one of the following values:

R_CURSOR

返回与指定键关联的数据。这与get例程的不同之处在于，它也将光标设置或初始化为键的位置。 (注意，对于DB_BTREE访问方法，返回的键不一定与指定键完全匹配。返回的键是大于或等于指定键的最小键，允许部分键匹配和范围搜索。)

R_FIRST

返回数据库的第一个键/数据对，并设置或初始化了光标以引用它。

R_LAST

返回数据库的最后一个键/数据对，并设置或初始化光标以引用它。 (仅适用于DB_BTREE和DB_RECNO访问方法。)

R_NEXT

在光标之后立即检索键/数据对。如果尚未设置光标，则它与R_FIRST标志相同。

R_PREV

在光标之前检索键/数据对。如果尚未设置光标，则与R_LAST标志相同。 (仅适用于DB_BTREE和DB_RECNO访问方法。)

R_LAST和R_PREV仅可用于DB_BTREE和DB_RECNO访问方法，因为它们每个都暗示键具有不变的固有顺序。

seq例程在错误(设置errno)时返回-1，在成功时返回0，如果不存在小于或大于指定或当前密钥的键/数据对，则返回1。如果正在使用DB_RECNO访问方法，并且数据库文件是字符特殊文件，并且当前没有完整的键/数据对，则seq例程返回2。

sync

指向例程的指针，该例程将所有缓存的信息刷新到磁盘。如果数据库仅在内存中，则同步例程无效，并且将始终成功。

The flag value may be set to the following value:

R_RECNOSYNC

如果正在使用DB_RECNO访问方法，则此标志将导致同步例程应用到作为recno文件基础的btree文件，而不是recno文件本身。 (有关更多信息，请参见recno(3)手册页的bfname字段。)

同步例程在错误(设置errno)时返回-1，并在成功时返回0。

Key/data pairs

对所有文件类型的访问基于密钥/数据对。密钥和数据均由以下数据结构表示：

typedef struct {
    void  *data;
    size_t size;
} DBT;

DBT结构的元素定义如下：

data

指向字节字符串的指针。

size

字节字符串的长度。

密钥和数据字节字符串可以引用实质上无限制长度的字符串，尽管它们中的任何两个必须同时放入可用的内存中。应当注意，访问方法不提供有关字节字符串对齐的保证。

错误说明

dbopen()例程可能会失败，并为库例程open(2)和malloc(3)或以下各项指定的任何错误设置errno：

EFTYPE

文件格式错误。

EINVAL

指定的参数(哈希函数，填充字节等)与当前文件规范不兼容，或者对该函数没有意义(例如，在没有事先初始化的情况下使用游标)，或者参数之间不匹配文件和软件的版本号。

关闭例程可能会失败，并为库例程close(2)，read(2)，write(2)，free(3)或fsync(2)指定的任何错误设置errno。

del，get，put和seq例程可能会失败，并为库例程read(2)，write(2)，free(3)或malloc(3)指定的任何错误设置errno。

fd例程将失败，并将内存数据库中的errno设置为ENOENT。

同步例程可能会失败，并为库例程fsync(2)指定的任何错误设置errno。

BUGS

typedef DBT是"数据库thang"的助记符，之所以被使用是因为没人能想到一个尚未使用的合理名称。

文件描述符接口是一个麻烦，将在该接口的将来版本中删除。

没有一种访问方法提供任何形式的并发访问，锁定或事务。

另外参见

btree(3)，hash(3)，mpool(3)，recno(3)

LIBTP：UNIX的可移植，模块化事务，Margo Seltzer，Michael Olson，USENIX程序，1992年冬季。

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本，请访问https://www.kernel.org/doc/man-pages/。