Berkeley DB: lock_open
Description: Berkeley DB: An embedded database programmatic toolkit.
Keywords: embedded,database,programmatic,toolkit,b+tree,btr ee,hash,hashing,transaction,transactions,locking,logging,access method,access me thods,java,C,C++

# lock_open

`

###

    #include <db.h>

    int
    lock_open(const char *dir, u_int32_t flags,
        int mode, DB_ENV *dbenv, DB_LOCKTAB **regionp);

# Description

The lock_open function copies a pointer, to the "lock region" identified by the directory dir, into the memory location referenced by regionp.

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(DB_LOCKTAB) handle returned by lock_open to be useable by multiple threads within a single address space, i.e., to be free-threaded.

All files created by the lock subsystem are created with mode mode (as described in chmod(2)) and modified by the process' umask value at the time of creation (see umask(2)))). The group ownership of created files is based on the system and directory defaults, and is not further specified by Berkeley DB.

The locking subsystem is configured based on the dbenv argument to lock_open which is a pointer to a structure of type DB_ENV. Applications normally use the same DB_ENV structure (initialized by db_appinit) as an argument to all of the subsystems in the Berkeley DB package.

References to the DB_ENV structure are maintained by Berkeley DB, so it may not be discarded until the last close function, corresponding to an open function for which it was an argument, has returned. To ensure compatibility with future releases of Berkeley DB, all fields of the DB_ENV structure that are not explicitly set should be initialized to 0 before the first time the structure is used. Do this by declaring the structure external or static, or by calling one of the C library routines bzero(3) or memset(3).

The fields of the DB_ENV structure used by lock_open are described below. If dbenv is NULL or any of its fields are set to 0, defaults appropriate for the system are used where possible.

The following fields in the DB_ENV structure may be initialized before calling lock_open:

void *(*db_errcall)(char *db_errpfx, char *buffer);
FILE *db_errfile;
const char *db_errpfx;
int db_verbose;
  The error fields of the DB_ENV behave as described for db_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 lock_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 lock_open function returns the value of errno on failure, and 0 on success.

# Environment Variables

DB_HOME
  If the dbenv argument to lock_open was initialized using db_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 lock_open was NULL or not initialized using db_appinit the environment variable TMPDIR may be used as the directory in which to create the lock table, as described in lock_open.

# Errors

If a fatal error occurs in Berkeley DB, the lock_open function may fail and return DB_RUNRECOVERY, at which point all subsequent database calls will also return DB_RUNRECOVERY.

The lock_open function may fail and return errno for any of the errors specified for the following Berkeley DB and C library functions: abort(3), close(3), db_version, fcntl(3), fflush(3), fprintf(3), free(3), fstat(3), fsync(3), getenv(3), getpid(3), getuid(3), isdigit(3), lock_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 lock_open function may fail and 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.

# See Also

lock_close, lock_detect, lock_get, lock_id, lock_open, lock_put, lock_stat, lock_unlink and lock_vec.`