Db — C Library Procedures

NAME

Db − manipulate simple database files

SYNOPSIS

#include<db.h>
int
Db_WriteEntry(file, buffer, index, size, lockHow)
int
Db_ReadEntry(file, buffer, index, size, lockHow)
int
Db_Open(file, size, handlePtr, writing, lockWhen, lockHow, numBuf)
int
Db_Put(handlePtr, buffer, index)
int
Db_Get(handlePtr, buffer, index)
int
Db_Close(handlePtr)

ARGUMENTS

char ∗file (in) The name of a database file on which to perform operations.

char ∗buffer (in/out) A pointer to the area from which or to which to transfer the record.

int index (out) Which record to access in a database operation.

int size (in) The size of a record.

Db_LockHow lockHow (in) Method to use when locking the database.

Db_Handle ∗handlePtr (in/out) A pointer to a “database handle”.

int writing (in) If non-zero, the database file is opened in write-only mode, otherwise in read-only mode.

Db_LockWhen lockWhen (in) Determines when to lock the database for long-term accesses.

int numBuf (in) Number of records to buffer when reading from database.

DESCRIPTION

These functions provide shared access to files containing arbitrary numbers of fixed-length records. There are two ways to access the files. The simplest way to access a database file is to use Db_WriteEntry() and Db_ReadEntry() to open the file, access a record, and close the file again. An alternative method is to use Db_Open() to obtain a handle for the file, use Db_Put() or Db_Get() to write or read entries, respectively, and use Db_Close() to close the file when it is no longer needed. In this case, the numBuf argument is used to specify how many records to buffer internally when doing reads (it must be specified as 0 for writes).

The Db library provides a simple locking facility to allow shared access to files, built on top of the flock() system call. Database files can be accessed without using locks, or using the standard flock() call in blocking or non-blocking mode. Unfortunately, hosts can hold locks when they crash, so a program that performs a blocking lock could wait indefinitely for a lock if no additional mechanism is used. The Db library allows locks to time out, and it can optionally break a lock if the lock times out. The time-out period is currently fixed. The different options are specified by the Db_LockHow type: typedef enum { DB_LOCK_NO_BLOCK, /∗ return immediately with error ∗/ DB_LOCK_POLL, /∗ poll the lock; time out if necessary ∗/ DB_LOCK_WAIT, /∗ wait indefinitely ∗/ DB_LOCK_BREAK, /∗ poll, plus break the lock if needed ∗/ DB_LOCK_NONE, /∗ do not lock the file at all ∗/ } Db_LockHow;

The Db_WriteEntry() and Db_ReadEntry() procedures take a Db_LockHow parameter to determine how to lock the database file the one time it is accessed. In addition to a Db_Lock parameter, Db_Open() takes a Db_LockWhen argument to specify when to perform the lock. Generally, when a file is going to be read or written sequentially, one would like to lock it before starting to do I/O and unlock it after finishing. If a file is going to be accessed repeatedly over a long period of time, however, it should be opened once but locked only during each access. These options are DB_LOCK_OPEN and DB_LOCK_ACCESS, respectively. If the file is never to be locked, then the Db_LockWhen argument may be specified as DB_LOCK_NEVER or the Db_LockHow argument may be specified as DB_LOCK_NONE.

Db_WriteEntry() and Db_ReadEntry() provide access to a single record. They take the filename to access; an index into the file, the size of a record; a pointer to a data buffer; and the method of locking the database, lockHow. All records must have the same size. The index is zero-based, so index 0 refers to the first record in the file.

Db_Open() takes the same file, size, and lockHow arguments as Db_WriteEntry() and Db_ReadEntry(). It also takes an argument, writing, which indicates whether access will be writing (1) or reading (0); and another argument, numBuf, which specifies how many records to read from the file at once when doing reads. The lockWhen argument is described above; it indicates whether locking should be done for each access or at the time the file is opened. Db_Open() returns a database handle in ∗handlePtr. The storage for the handle must be allocated by the caller of Db_Open(). A pointer to the handle must be used in later calls to Db_Put(), Db_Get(), or Db_Close().

Db_Put() and Db_Get() are analogous to Db_WriteEntry() and Db_ReadEntry(). They are used in cases when the database file is opened by Db_Open(), for use over an extended period of time. The handlePtr argument must be a handle returned by Db_Open(). The buffer must be a pointer to an area of the size specified in the call to Db_Open(). The index is an integer: if non-negative, it specifies a record number, like in calls to Db_WriteEntry() and Db_ReadEntry(). If index is -1, it specifies that the access should be sequential: the record to be operated upon should be the one immediately following the last record read or written. If Db_Put() or Db_Get() is called for the first time with an index of -1, the first record is written or read.

Db_Close() closes a file that was opened with Db_Open(). HandlePtr must point to a handle that was initialized by Db_Open().

DIAGNOSTICS

All routines return 0 if they complete successfully. Upon error, they return -1 and the errno variable contains additional information about what error occurred.

KEYWORDS

database, data base, lock, record, handle

Museum