+I+Berkeley DB: DbLockTab::open[P

DbLockTab::open





#include <db_cxx.h>

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





Description

The DbLockTab::openPmethod copies a pointer, to the "lock region" identified by the directoryBdir, into the memory location referenced by regionp.

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

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

[

DB_CREATE
Create any underlying files, as necessary. If the files do not alreadyBexist 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 befree-threaded.


WAll files created by the lock subsystem are created with mode mode (as describedHin chmod(2)) and modified by the process' umask value at the time$of creation (see umask(2)))).IThe group ownership of created files is based on the system and directory6defaults, and is not further specified by Berkeley DB.

#The locking subsystem is configuredEbased on the dbenv argument. It is expected that applicationsiwill use a single DbEnv object as the argument to all of thessubsystems in the Berkeley DB package. The fields of the DbEnv object,used by DbLockTab::open are described below.pReferences to the DbEnv object are maintained by Berkeley DB, so itDis necessary that the object and memory it references be valid untilthe object is destroyed.mAny of the DbEnv fields that are not explicitly set will defaultto appropriate values.

oThe 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;
y
int db_verbose;
The error fields of the DbEnv behave as described for>DbEnv::appinit.V

const u_int8_t lk_conflicts[][];
A lk_modes by lk_modes array.$A non-0 value for the array element:A

    lk_conflicts[requested_mode][held_mode]

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

db_detect_t lk_detect;
If non-0, specifies that the deadlock detector be run whenever a lockEconflict occurs, and specifies which transaction should be aborted inthe case of a deadlock.FThe lk_detect field must be set to one of the following values.
z

DB_LOCK_DEFAULT
Use the default policy as specified by db_deadlock.6

DB_LOCK_OLDEST
Abort the oldest transaction.M

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.CThis value is used by DbLockTab::open to estimate how much space to0allocate for various lock-table data structures./If lk_max is 0, a default value is used.d

u_int32_t lk_modes;
The number of lock modes to be recognized by the lock table (includingAthe 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

W

DB_HOME
If the dbenv argument to DbLockTab::open was initialized usingiDbEnv::appinit the environment variable DB_HOME mayBbe used as the path of the database home for the interpretation ofthe dir argument.


\

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




Errors

VIf a fatal error occurs in Berkeley DB, the DbLockTab::open method may fail and eitherIreturn DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY,Gat which point all subsequent database calls will also fail in the sameFway. Methods marked as returning errno will, by default, throwHan exception that encapsulates the error information. The default error\behavior can be changed, see DbException.

The DbLockTab::open&method may fail and throw an exceptionKfor 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),DDbLockTab::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 exceptionor return errnofor the following conditions:

R

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

EINVAL
An invalid flag value or parameter was specified.

FThe DB_THREAD flag was specified and spinlocks are not implemented forthis architecture.





Class

:DbLockTab



See Also

BDbLockTab::close,DDbLockTab::detect,>DbLockTab::get,<DbLockTab::id,DbLockTab::open,?DbLockTab::statCDbLockTab::unlinkand>DbLockTab::vec.
8yaÿÿ, Inc. All rights reserved.>+Berkeley DB: DbLockTab::open[P

DbLockTab::o