#include <db_cxx.h>

static int
DbLockTab::open(const char *dir,
    u_int32_t flags, int mode, DbEnv *dbenv, DbLockTab **regionp);

Description

The dir pathname argument is interpreted as described in Berkeley DB File Naming.

The flags and mode arguments specify how files will be opened and/or created if they do not already exist. The flags value is specified by logically OR'ing together one or more of the following values:

DB_CREATE

Create any underlying files, as necessary. If the files do not already exist and the DB_CREATE flag is not specified, the call will fail.

DB_THREAD

Cause the m4_reg(DbLockTab) handle returned by DbLockTab::open to be useable by multiple threads within a single address space, i.e., to be free-threaded.

The locking subsystem is configured based on the dbenv argument. It is expected that applications will use a single DbEnv object as the argument to all of the subsystems in the Berkeley DB package. The fields of the DbEnv object used by DbLockTab::open are described below. References to the DbEnv object are maintained by Berkeley DB, so it is necessary that the object and memory it references be valid until the object is destroyed. Any of the DbEnv fields that are not explicitly set will default to appropriate values.

The following fields in the DbEnv object may be initialized, using the appropriate set method, before calling DbLockTab::open:

void *(*db_errcall)(char *db_errpfx, char *buffer);

FILE *db_errfile;

const char *db_errpfx;

class ostream *db_error_stream;

int db_verbose;

The error fields of the DbEnv behave as described for DbEnv::appinit.

const u_int8_t lk_conflicts[][];

A lk_modes by lk_modes array. A non-0 value for the array element:

lk_conflicts[requested_mode][held_mode]

indicates that requested_mode and held_mode conflict. The not-granted mode must be represented by 0. If lk_conflicts is NULL, the conflicts array db_rw_conflicts is used; see Standard Lock Modes for a description of that array.

db_detect_t lk_detect;

If non-0, specifies that the deadlock detector be run whenever a lock conflict occurs, and specifies which transaction should be aborted in the case of a deadlock. The lk_detect field must be set to one of the following values.

DB_LOCK_DEFAULT

Use the default policy as specified by db_deadlock.

DB_LOCK_OLDEST

Abort the oldest transaction.

DB_LOCK_RANDOM

Abort a random transaction involved in the deadlock.

DB_LOCK_YOUNGEST

Abort the youngest transaction.

u_int32_t lk_max;

The maximum number of locks to be held or requested in the table. This value is used by DbLockTab::open to estimate how much space to allocate for various lock-table data structures. If lk_max is 0, a default value is used.

u_int32_t lk_modes;

The number of lock modes to be recognized by the lock table (including the not-granted mode). If lk_modes is 0, the value DB_LOCK_RW_N is used.

The DbLockTab::open method either returns errno or throws an exception that encapsulates an errno on failure, and 0 on success.

Environment Variables

DB_HOME

If the dbenv argument to DbLockTab::open was initialized using DbEnv::appinit the environment variable DB_HOME may be used as the path of the database home for the interpretation of the dir argument.

TMPDIR

If the dbenv argument to DbLockTab::open was NULL or not initialized using DbEnv::appinit the environment variable TMPDIR may be used as the directory in which to create the lock table, as described in DbLockTab::open.

Errors

The DbLockTab::open method may fail and throw an exception for any of the errors specified for the following Berkeley DB and C library functions: abort(3), close(3), DbEnv::version, fcntl(3), fflush(3), fprintf(3), free(3), fstat(3), fsync(3), getenv(3), getpid(3), getuid(3), isdigit(3), DbLockTab::unlink, lseek(3), malloc(3), memcpy(3), memset(3), mmap(3), munmap(3), open(3), pstat_getdynamic(3), read(3), shmat(3), shmctl(3), shmdt(3), sigfillset(3), sigprocmask(3), stat(3), strerror(3), strlen(3), sysconf(3), unlink(3), vfprintf(3), vsnprintf(3), and write(3).

In addition, the DbLockTab::open method may fail and throw an exception or return errno for the following conditions:

EAGAIN

The shared memory region was locked and (repeatedly) unavailable.

EINVAL

An invalid flag value or parameter was specified.

The DB_THREAD flag was specified and spinlocks are not implemented for this architecture.

Class

See Also