.ds TYPE C
.\"
.\" See the file LICENSE for redistribution information.
.\"
.\" Copyright (c) 1996, 1997
.\"	Sleepycat Software.  All rights reserved.
.\"
.\"	@(#)db_lock.so	10.25 (Sleepycat) 11/25/97
.\"
.\"
.\" See the file LICENSE for redistribution information.
.\"
.\" Copyright (c) 1997
.\"	Sleepycat Software.  All rights reserved.
.\"
.\"	@(#)macros.so	10.38 (Sleepycat) 1/18/98
.\"
.\" We don't want hyphenation for any HTML documents.
.ie '\*[HTML]'YES'\{\
.nh
\}
.el\{\
.ds Hy
.hy
..
.ds Nh
.nh
..
\}
.\" The alternative text macro
.\" This macro takes two arguments:
.\"	+ the text produced if this is a "C" manpage
.\"	+ the text produced if this is a "CXX" or "JAVA" manpage
.\"
.de Al
.ie '\*[TYPE]'C'\{\\$1
\}
.el\{\\$2
\}
..
.\" Scoped name macro.
.\" Produces a_b, a::b, a.b depending on language
.\" This macro takes two arguments:
.\"	+ the class or prefix (without underscore)
.\"	+ the name within the class or following the prefix
.de Sc
.ie '\*[TYPE]'C'\{\\$1_\\$2
\}
.el\{\
.ie '\*[TYPE]'CXX'\{\\$1::\\$2
\}
.el\{\\$1.\\$2
\}
\}
..
.\" Scoped name for Java.
.\" Produces Db.b, for Java, otherwise just b.  This macro is used for
.\" constants that must be scoped in Java, but are global otherwise.
.\" This macro takes two arguments:
.\"	+ the class
.\"	+ the name within the class or following the prefix
.de Sj
.ie '\*[TYPE]'JAVA'\{\
.TP 5
Db.\\$1\}
.el\{\
.TP 5
\\$2\}
..
.\" The general information text macro.
.de Gn
.ie '\*[TYPE]'C'\{The DB library is a family of groups of functions that provides a modular
programming interface to transactions and record-oriented file access.
The library includes support for transactions, locking, logging and file
page caching, as well as various indexed access methods.
Many of the functional groups (e.g., the file page caching functions)
are useful independent of the other DB functions,
although some functional groups are explicitly based on other functional
groups (e.g., transactions and logging).
\}
.el\{The DB library is a family of classes that provides a modular
programming interface to transactions and record-oriented file access.
The library includes support for transactions, locking, logging and file
page caching, as well as various indexed access methods.
Many of the classes (e.g., the file page caching class)
are useful independent of the other DB classes,
although some classes are explicitly based on other classes
(e.g., transactions and logging).
\}
For a general description of the DB package, see
.IR db_intro (3).
..
.\" The library error macro, the local error macro.
.\" These macros take one argument:
.\"	+ the function name.
.de Ee
The
.I \\$1
.ie '\*[TYPE]'C'\{function may fail and return
.I errno
\}
.el\{method may fail and throw a
.IR DbException (3)
.if '\*[TYPE]'CXX'\{
or return
.I errno
\}
\}
for any of the errors specified for the following DB and library functions:
..
.de Ec
In addition, the
.I \\$1
.ie '\*[TYPE]'C'\{function may fail and return
.I errno
\}
.el\{method may fail and throw a
.IR DbException (3)
.ie '\*[TYPE]'CXX'\{or return
.I errno
\}
.el\{encapsulating an
.I errno
\}
\}
for the following conditions:
..
.de Ea
[EAGAIN]
A lock was unavailable.
..
.de Eb
[EBUSY]
The shared memory region was in use and the force flag was not set.
..
.de Em
[EAGAIN]
The shared memory region was locked and (repeatedly) unavailable.
..
.de Ei
[EINVAL]
An invalid flag value or parameter was specified.
..
.de Es
[EACCES]
An attempt was made to modify a read-only database.
..
.de Et
The DB_THREAD flag was specified and spinlocks are not implemented for
this architecture.
..
.de Ep
[EPERM]
Database corruption was detected.
All subsequent database calls (other than
.ie '\*[TYPE]'C'\{\
.IR DB->close )
\}
.el\{\
.IR Db::close )
\}
will return EPERM.
..
.de Ek
.if '\*[TYPE]'CXX'\{\
Methods marked as returning
.I errno
will, by default, throw an exception that encapsulates the error information.
The default error behavior can be changed, see
.IR DbException (3).
\}
..
.\" The SEE ALSO text macro
.de Sa
.\" make the line long for nroff.
.if n .ll 72
.nh
.na
.IR db_archive (1),
.IR db_checkpoint (1),
.IR db_deadlock (1),
.IR db_dump (1),
.IR db_load (1),
.IR db_recover (1),
.IR db_stat (1),
.IR db_intro (3),
.ie '\*[TYPE]'C'\{\
.IR db_appinit (3),
.IR db_cursor (3),
.IR db_dbm (3),
.IR db_internal (3),
.IR db_lock (3),
.IR db_log (3),
.IR db_mpool (3),
.IR db_open (3),
.IR db_thread (3),
.IR db_txn (3)
\}
.el\{\
.IR db_internal (3),
.IR db_thread (3),
.IR Db (3),
.IR Dbc (3),
.IR DbEnv (3),
.IR DbException (3),
.IR DbInfo (3),
.IR DbLock (3),
.IR DbLockTab (3),
.IR DbLog (3),
.IR DbLsn (3),
.IR DbMpool (3),
.IR DbMpoolFile (3),
.IR Dbt (3),
.IR DbTxn (3),
.IR DbTxnMgr (3)
\}
.ad
.Hy
..
.\" The function header macro.
.\" This macro takes one argument:
.\"	+ the function name.
.de Fn
.in 2
.I \\$1
.in
..
.\" The XXX_open function text macro, for merged create/open calls.
.\" This macro takes two arguments:
.\"	+ the interface, e.g., "transaction region"
.\"	+ the prefix, e.g., "txn" (or the class name for C++, e.g., "DbTxn")
.de Co
.ie '\*[TYPE]'C'\{\
.Fn \\$2_open
The
.I \\$2_open
function copies a pointer, to the \\$1 identified by the
.B directory
.IR dir ,
into the memory location referenced by
.IR regionp .
.PP
If the
.I dbenv
argument to
.I \\$2_open
was initialized using
.IR db_appinit ,
.I dir
is interpreted as described by
.IR db_appinit (3).
\}
.el\{\
.Fn \\$2::open
The
.I \\$2::open
.ie '\*[TYPE]'CXX'\{\
method copies a pointer, to the \\$1 identified by the
.B directory
.IR dir ,
into the memory location referenced by
.IR regionp .
\}
.el\{\
method returns a \\$1 identified by the
.B directory
.IR dir .
\}
.PP
If the
.I dbenv
argument to
.I \\$2::open
was initialized using
.IR DbEnv::appinit ,
.I dir
is interpreted as described by
.IR DbEnv (3).
\}
.PP
Otherwise,
if
.I dir
is not NULL,
it is interpreted relative to the current working directory of the process.
If
.I dir
is NULL,
the following environment variables are checked in order:
``TMPDIR'', ``TEMP'', and ``TMP''.
If one of them is set,
\\$1 files are created relative to the directory it specifies.
If none of them are set, the first possible one of the following
directories is used:
.IR /var/tmp ,
.IR /usr/tmp ,
.IR /temp ,
.IR /tmp ,
.I C:/temp
and
.IR C:/tmp .
.PP
All files associated with the \\$1 are created in this directory.
This directory must already exist when
.ie '\*[TYPE]'C'\{
\\$1_open
\}
.el\{\
\\$2::open
\}
is called.
If the \\$1 already exists,
the process must have permission to read and write the existing files.
If the \\$1 does not already exist,
it is optionally created and initialized.
..
.\" The common close language macro, for discarding created regions
.\" This macro takes one argument:
.\"	+ the function prefix, e.g., txn (the class name for C++, e.g., DbTxn)
.de Cc
In addition, if the
.I dir
argument to
.ie '\*[TYPE]'C'\{\
.ds Va db_appinit
.ds Vo \\$1_open
.ds Vu \\$1_unlink
\}
.el\{\
.ds Va DbEnv::appinit
.ds Vo \\$1::open
.ds Vu \\$1::unlink
\}
.I \\*(Vo
was NULL
and
.I dbenv
was not initialized using
.IR \\*(Va ,
.if '\\$1'memp'\{\
or the DB_MPOOL_PRIVATE flag was set,
\}
all files created for this shared region will be removed,
as if
.I \\*(Vu
were called.
.rm Va
.rm Vo
.rm Vu
..
.\" The DB_ENV information macro.
.\" This macro takes two arguments:
.\"	+ the function called to open, e.g., "txn_open"
.\"	+ the function called to close, e.g., "txn_close"
.de En
.ie '\*[TYPE]'C'\{\
based on the
.I dbenv
argument to
.IR \\$1 ,
which is a pointer to a structure of type DB_ENV (typedef'd in <db2/db.h>).
It is expected that applications will use a single DB_ENV structure as the
argument to all of the subsystems in the DB package.
In order to ensure compatibility with future releases of 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 the C
library routine
.IR bzero (3)
or
.IR memset (3).
.PP
The fields of the DB_ENV structure used by
.I \\$1
are described below.
.if '\*[TYPE]'CXX'\{\
As references to the DB_ENV structure may be maintained by
.IR \\$1 ,
it is necessary that the DB_ENV structure and memory it references be valid
until the
.I \\$2
function is called.
\}
.ie '\\$1'db_appinit'\{The
.I dbenv
argument may not be NULL.
If any of the fields of the
.I dbenv
are set to 0,
defaults appropriate for the system are used where possible.
\}
.el\{If
.I dbenv
is NULL
or any of its fields are set to 0,
defaults appropriate for the system are used where possible.
\}
.PP
The following fields in the DB_ENV structure may be initialized before calling
.IR \\$1 :
\}
.el\{\
based on which set methods have been used.
It is expected that applications will use a single DbEnv object as the
argument to all of the subsystems in the DB package.
The fields of the DbEnv object used by
.I \\$1
are described below.
As references to the DbEnv object may be maintained by
.IR \\$1 ,
it is necessary that the DbEnv object and memory it references be valid
until the object is destroyed.
.ie '\\$1'appinit'\{\
The
.I dbenv
argument may not be NULL.
If any of the fields of the
.I dbenv
are set to 0,
defaults appropriate for the system are used where possible.
\}
.el\{\
Any of the DbEnv fields that are not explicitly set will default to
appropriate values.
\}
.PP
The following fields in the DbEnv object may be initialized, using the
appropriate set method, before calling
.IR \\$1 :
\}
..
.\" The DB_ENV common fields macros.
.de Se
.ie '\*[TYPE]'JAVA'\{\
.TP 5
DbErrcall db_errcall;
.ns
.TP 5
String db_errpfx;
.ns
.TP 5
int db_verbose;
The error fields of the DbEnv behave as described for
.IR DbEnv (3).
\}
.el\{\
.ie '\*[TYPE]'CXX'\{\
.TP 5
void *(*db_errcall)(char *db_errpfx, char *buffer);
.ns
.TP 5
FILE *db_errfile;
.ns
.TP 5
const char *db_errpfx;
.ns
.TP 5
class ostream *db_error_stream;
.ns
.TP 5
int db_verbose;
The error fields of the DbEnv behave as described for
.IR DbEnv (3).
\}
.el\{\
void *(*db_errcall)(char *db_errpfx, char *buffer);
.ns
.TP 5
FILE *db_errfile;
.ns
.TP 5
const char *db_errpfx;
.ns
.TP 5
int db_verbose;
The error fields of the DB_ENV behave as described for
.IR db_appinit (3).
\}
\}
..
.\" The open flags.
.de Fm
The
.I flags
and
.I mode
arguments specify how files will be opened and/or created when they
don't already exist.
The flags value is specified by
.BR or 'ing
together one or more of the following values:
.Sj 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 open flag macro.
.\" This macro takes two arguments:
.\"	+ the open function name
.\"	+ the object it returns.
.de Ft
.TP 5
.Sj DB_THREAD
Cause the \\$2 handle returned by the
.I \\$1
.Al function method
to be useable by multiple threads within a single address space,
i.e., to be ``free-threaded''.
.if '\*[TYPE]'JAVA'\{\
Threading is assumed in the Java API,
so no special flags are required,
and DB functions will always behave as if the DB_THREAD flag was specified.
\}
..
.\" The mode macro.
.\" This macro takes one argument:
.\"	+ the subsystem name.
.de Mo
All files created by the \\$1 are created with mode
.I mode
(as described in
.IR chmod (2))
and modified by the process' umask value at the time of creation (see
.IR umask (2)).
The group ownership of created files is based on the system and directory
defaults, and is not further specified by DB.
..
.\" The application exits macro.
.\" This macro takes one argument:
.\"	+ the application name.
.de Ex
The
.I \\$1
utility exits 0 on success, and >0 if an error occurs.
..
.\" The application -h section.
.\" This macro takes one argument:
.\"	+ the application name
.de Dh
DB_HOME
If the
.B \-h
option is not specified and the environment variable
.I DB_HOME
is set, it is used as the path of the database home, as described in
.IR db_appinit (3).
..
.\" The function DB_HOME ENVIRONMENT VARIABLES section.
.\" This macro takes one argument:
.\"	+ the open function name
.de Eh
DB_HOME
If the
.I dbenv
argument to
.I \\$1
was initialized using
.IR db_appinit ,
the environment variable DB_HOME may be used as the path of the database
home for the interpretation of the
.I dir
argument to
.IR \\$1 ,
as described in
.IR db_appinit (3).
.if \\n(.$>1 \{Specifically,
.I \\$1
is affected by the configuration string value of \\$2.\}
..
.\" The function TMPDIR ENVIRONMENT VARIABLES section.
.\" This macro takes two arguments:
.\"	+ the interface, e.g., "transaction region"
.\"	+ the prefix, e.g., "txn" (or the class name for C++, e.g., "DbTxn")
.de Ev
TMPDIR
If the
.I dbenv
argument to
.ie '\*[TYPE]'C'\{\
.ds Vo \\$2_open
\}
.el\{\
.ds Vo \\$2::open
\}
.I \\*(Vo
was NULL or not initialized using
.IR db_appinit ,
the environment variable TMPDIR may be used as the directory in which to
create the \\$1,
as described in the
.I \\*(Vo
section above.
.rm Vo
..
.\" The unused flags macro.
.de Fl
The
.I flags
parameter is currently unused, and must be set to 0.
..
.\" The no-space TP macro.
.de Nt
.br
.ns
.TP 5
..
.\" The return values of the functions macros.
.\" Rc is the standard two-value return with a suffix for more values.
.\" Ro is the standard two-value return but there were previous values.
.\" Rt is the standard two-value return, returning errno, 0, or < 0.
.\" These macros take one argument:
.\"	+ the routine name
.de Rc
The
.I \\$1
.ie '\*[TYPE]'C'\{function returns the value of
.I errno
on failure,
0 on success,
\}
.el\{method throws a
.IR DbException (3)
.ie '\*[TYPE]'CXX'\{or returns the value of
.I errno
on failure,
0 on success,
\}
.el\{that encapsulates an
.I errno
on failure,
\}
\}
..
.de Ro
Otherwise, the
.I \\$1
.ie '\*[TYPE]'C'\{function returns the value of
.I errno
on failure and 0 on success.
\}
.el\{method throws a
.IR DbException (3)
.ie '\*[TYPE]'CXX'\{or returns the value of
.I errno
on failure and 0 on success.
\}
.el\{that encapsulates an
.I errno
on failure,
\}
\}
..
.de Rt
The
.I \\$1
.ie '\*[TYPE]'C'\{function returns the value of
.I errno
on failure and 0 on success.
\}
.el\{method throws a
.IR DbException (3)
.ie '\*[TYPE]'CXX'\{or returns the value of
.I errno
on failure and 0 on success.
\}
.el\{that encapsulates an
.I errno
on failure.
\}
\}
..
.\" The TXN id macro.
.de Tx
.IP
If the file is being accessed under transaction protection,
the
.I txnid
parameter is a transaction ID returned from
.IR txn_begin ,
otherwise, NULL.
..
.\" The XXX_unlink function text macro.
.\" This macro takes two arguments:
.\"	+ the interface, e.g., "transaction region"
.\"	+ the prefix (for C++, this is the class name)
.de Un
.ie '\*[TYPE]'C'\{\
.ds Va db_appinit
.ds Vc \\$2_close
.ds Vo \\$2_open
.ds Vu \\$2_unlink
\}
.el\{\
.ds Va DbEnv::appinit
.ds Vc \\$2::close
.ds Vo \\$2::open
.ds Vu \\$2::unlink
\}
.Fn \\*(Vu
The
.I \\*(Vu
.Al function method
destroys the \\$1 identified by the directory
.IR dir ,
removing all files used to implement the \\$1.
.ie '\\$2'log' \{(The log files themselves and the directory
.I dir
are not removed.)\}
.el \{(The directory
.I dir
is not removed.)\}
If there are processes that have called
.I \\*(Vo
without calling
.I \\*(Vc
(i.e., there are processes currently using the \\$1),
.I \\*(Vu
will fail without further action,
unless the force flag is set,
in which case
.I \\*(Vu
will attempt to remove the \\$1 files regardless of any processes
still using the \\$1.
.PP
The result of attempting to forcibly destroy the region when a process
has the region open is unspecified.
Processes using a shared memory region maintain an open file descriptor
for it.
On UNIX systems, the region removal should succeed
and processes that have already joined the region should continue to
run in the region without change,
however processes attempting to join the \\$1 will either fail or
attempt to create a new region.
On other systems, e.g., WNT, where the
.IR unlink (2)
system call will fail if any process has an open file descriptor
for the file,
the region removal will fail.
.PP
In the case of catastrophic or system failure,
database recovery must be performed (see
.IR db_recover (1)
or the DB_RECOVER flags to
.IR \\*(Va (3)).
Alternatively, if recovery is not required because no database state is
maintained across failures,
it is possible to clean up a \\$1 by removing all of the
files in the directory specified to the
.I \\*(Vo
.Al function, method,
as \\$1 files are never created in any directory other than the one
specified to
.IR \\*(Vo .
Note, however,
that this has the potential to remove files created by the other DB
subsystems in this database environment.
.PP
.Rt \\*(Vu
.rm Va
.rm Vo
.rm Vu
.rm Vc
..
.\" Signal paragraph for standard utilities.
.\" This macro takes one argument:
.\"	+ the utility name.
.de Si
The
.I \\$1
utility attaches to DB shared memory regions.
In order to avoid region corruption,
it should always be given the chance to detach and exit gracefully.
To cause
.I \\$1
to clean up after itself and exit,
send it an interrupt signal (SIGINT).
..
.\" Logging paragraph for standard utilities.
.\" This macro takes one argument:
.\"	+ the utility name.
.de Pi
.B \-L
Log the execution of the \\$1 utility to the specified file in the
following format, where ``###'' is the process ID, and the date is
the time the utility starting running.
.sp
\\$1: ### Wed Jun 15 01:23:45 EDT 1995
.sp
This file will be removed if the \\$1 utility exits gracefully.
..
.\" Malloc paragraph.
.\" This macro takes one argument:
.\"	+ the allocated object
.de Ma
.if !'\*[TYPE]'JAVA'\{\
\\$1 are created in allocated memory.
If
.I db_malloc
is non-NULL,
it is called to allocate the memory,
otherwise,
the library function
.IR malloc (3)
is used.
The function
.I db_malloc
must match the calling conventions of the
.IR malloc (3)
library routine.
Regardless,
the caller is responsible for deallocating the returned memory.
To deallocate the returned memory,
free each returned memory pointer;
pointers inside the memory do not need to be individually freed.
\}
..
.\" Underlying function paragraph.
.\" This macro takes two arguments:
.\"	+ the function name
.\"	+ the utility name
.de Uf
The
.I \\$1
.Al function method
is the underlying function used by the
.IR \\$2 (1)
utility.
See the source code for the
.I \\$2
utility for an example of using
.I \\$1
in a UNIX environment.
..
.\" Underlying function paragraph, for C++.
.\" This macro takes three arguments:
.\"	+ the C++ method name
.\"	+ the function name for C
.\"	+ the utility name
.de Ux
The
.I \\$1
method is based on the C
.I \\$2
function, which
is the underlying function used by the
.IR \\$3 (1)
utility.
See the source code for the
.I \\$3
utility for an example of using
.I \\$2
in a UNIX environment.
..
.TH DB_LOCK 3 "November 25, 1997"
.UC 7
.SH NAME
db_lock \- lock manager
.SH SYNOPSIS
.nf
.ft B
#include <db2/db.h>

int
lock_open(const char *dir,
.ti +5
int flags, int mode, DB_ENV *dbenv, DB_LOCKTAB **regionp);

int
lock_id(DB_LOCKTAB *lt, u_int32_t *idp);

int
lock_vec(DB_LOCKTAB *lt, u_int32_t locker, int flags,
.ti +5
DB_LOCKREQ list[], int nlist, DB_LOCKREQ **elistp);

int
lock_get(DB_LOCKTAB *lt, u_int32_t locker, int flags,
.ti +5
const DBT *obj, const db_lockmode_t lock_mode, DB_LOCK *lock);

int
lock_put(DB_LOCKTAB *lt, DB_LOCK lock);

int
lock_close(DB_LOCKTAB *lt);

int
lock_unlink(const char *dir, int force, DB_ENV *dbenv);

int
lock_detect(DB_LOCKTAB *lt, int flags, int atype);
.ft R
.fi
.SH DESCRIPTION
.Gn
.PP
This manual page describes the specific details of the locking interface.
.PP
The
.I db_lock
functions are the library interface intended to provide general-purpose
locking.
While designed to work with the other DB functions, these functions are
also useful for more general locking purposes.
Locks can be shared between processes.
In most cases, when multiple threads or processes are using locking, the
deadlock detector,
.IR db_deadlock (1),
should be run.
.PP
.Co "lock table" lock
.PP
.Fm
.Ft lock_open DB_LOCKTAB
.PP
.Mo "lock subsystem"
.PP
The locking subsystem is configured
.En "lock_open" "lock_closed"
.TP 5
.Se
.TP 5
const u_int8_t lk_conflicts[][];
A
.I lk_modes
by
.I lk_modes
array.
A non-0 value for the array element:
.sp
.ti +5
lk_conflicts[requested_mode][held_mode]
.sp
indicates that requested_mode and held_mode conflict.
The ``not-granted'' mode must be represented by 0.
If
.I lk_conflicts
is NULL, the conflicts array
.I db_rw_conflicts
is used;
see the section below entitled ``STANDARD LOCK MODES'' for a description
of that array.
.TP 5
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
.I lk_detect
field must be set to one of the following values.
.RS
.TP 5
DB_LOCK_DEFAULT
Use the default policy as specified in the
.IR db_deadlock (1)
man page.
.TP 5
DB_LOCK_OLDEST
Abort the oldest transaction.
.TP 5
DB_LOCK_RANDOM
Abort a random transaction involved in the deadlock.
.TP 5
DB_LOCK_YOUNGEST
Abort the youngest transaction.
.RE
.TP 5
unsigned int lk_max;
The maximum number of locks to be held or requested in the table.
This value is used by
.I lock_open
to estimate how much space to allocate for various lock-table data
structures.
If
.I lk_max
is 0, a default value is used.
.TP 5
int lk_modes;
The number of lock modes to be recognized by the lock table (including
the ``not-granted'' mode).
If
.I lk_modes
is 0, the value DB_LOCK_RW_N is used;
see below for a description of that value.
.PP
.Rt lock_open
.PP
.Fn lock_id
The
.I lock_id
function copies a locker ID,
which is guaranteed to be unique in the specified lock table,
into the memory location referenced by
.IR idp .
.PP
The access methods
(see
.IR db_open (3)),
generate a unique locker ID for each file that is opened with locking.
During DB access method operation,
this locker ID will be used for all lock calls unless a transaction
identifier was specified for the call,
in which case the transaction ID specified is used for locking.
.PP
.Rt lock_id
.PP
.Fn lock_vec
The
.I lock_vec
function atomically obtains and releases one or more locks from the
specified table,
.IR lt .
The
.I lock_vec
function is intended to support acquisition or trading of multiple locks
under one lock table semaphore,
as is needed for lock coupling or in multigranularity locking for lock
escalation.
.PP
The
.I locker
argument specified to
.I lock_vec
is an unsigned 32-bit integer quantity.
It represents the entity requesting or releasing the lock.
.PP
The
.I flags
value must be set to 0 or the following value:
.TP 5
DB_LOCK_NOWAIT
If a lock cannot be granted because the requested lock conflicts with an
existing lock, return immediately instead of waiting for the lock to
become available.
.PP
The
.I list
array provided to
.I lock_vec
is typedef'd in <db2/db.h> as DB_LOCKREQ.
A DB_LOCKREQ structure has at least the following fields,
which must be initialized before calling
.IR lock_vec :
.TP 5
lockop_t op;
The operation to be performed, which must be set to one of the
following values:
.RS
.TP 5
DB_LOCK_GET
Get a lock, as defined by the values of
.IR locker ,
.I obj
and
.IR mode .
Upon return from
.IR lock_vec ,
if the
.I lock
field is non-NULL, a reference to the acquired lock is stored there.
(This reference is invalidated by any call to
.I lock_vec
or
.I lock_put
that releases the lock.)
.TP 5
DB_LOCK_PUT
The lock referenced by the contents of the
.I lock
field is released.
.TP 5
DB_LOCK_PUT_ALL
All locks held by the
.I locker
are released.
(Any locks acquired as a part of the current call to
.I lock_vec
that appear after the DB_LOCK_PUT_ALL entry are not considered for this
operation).
.TP 5
DB_LOCK_PUT_OBJ
All locks held by the
.IR locker ,
on the object
.IR obj ,
with the mode specified by
.IR lock_mode ,
are released.
A
.I lock_mode
of DB_LOCK_NG indicates that all locks on the object should be released.
Note that any locks acquired as a part of the current call to
.I lock_vec
that occur before the DB_LOCK_PUT_OBJ will also be released; those acquired
afterwards will not be released.
.RE
.TP 5
const DBT obj;
An untyped byte string that specifies the object to be locked or
released.
.TP 5
const lockmode_t mode;
The lock mode, used as an index into
.IR lt 's
conflict array.
.TP 5
DB_LOCK lock;
A lock reference.
.PP
The
.I nlist
argument specifies the number of elements in the
.I list
array.
.PP
If any of the requested locks cannot be acquired,
or any of the locks to be released cannot be released,
the operations before the failing operation are guaranteed to have completed
successfully, and
.I lock_vec
returns a non-zero value.
In addition, if
.I elistp
is not NULL, it is set to point to the DB_LOCKREQ entry that
was being processed when the error occurred.
.PP
In the case of an error,
.I lock_vec
may return one of the following values:
.TP 5
DB_LOCK_DEADLOCK
The specified
.I locker
was selected as a victim in order to resolve a deadlock.
.TP 5
DB_LOCK_NOTHELD
The lock cannot be released, as it was not held by the
.IR locker .
.TP 5
DB_LOCK_NOTGRANTED
A lock was requested that could not be granted and the
.I flag
parameter was set to DB_LOCK_NOWAIT.
In this case, if non-NULL,
.I elistp
identifies the request that was granted.
.PP
.Ro lock_vec
.PP
.Fn lock_get
The
.I lock_get
function is a simple interface to the
.I lock_vec
functionality, and is equivalent to calling the
.I lock_vec
function with the
.I lt
and
.I locker
arguments,
.I elistp
and
.I conflict
arguments, and a single element
.I list
array, for which the
.I op
field is DB_LOCK_GET, and the
.IR obj ,
.I lock_mode
and
.I lock
fields are represented by the arguments of the same name.
Note that the type of the
.I obj
argument to
.I lock_get
is different from the
.I obj
element found in the DB_LOCKREQ structure.
The
.I lock_get
function returns success and failure as described for the
.I lock_vec
function.
.PP
.Fn lock_put
The
.I lock_put
function is a simple interface to the
.I lock_vec
functionality, and is equivalent to calling the
.I lock_vec
function with a single element
.I list
array, for which the
.I op
field is DB_LOCK_PUT and the
.I lock
field is represented by the argument of the same name.
The
.I lock_put
function returns success and failure as described for the
.I lock_vec
function.
.PP
.Fn lock_close
The
.I lock_close
function disassociates the calling process from the lock table
.IR lt .
Note that
.I lock_close
does not release any locks still held by the closing process.
(This provides functionality for long-lived locks.)
Processes that wish to have all their locks released can do so by
issuing the appropriate
.I lock_vec
call.
.PP
.Cc lock
.PP
When multiple threads are using the DB_LOCKTAB handle concurrently,
only a single thread may call the
.I lock_close
function.
.PP
.Rt lock_close
.PP
.Un "lock table" lock
.PP
.Fn lock_detect
The
.I lock_detect
function runs one iteration of the deadlock detector on the specified table,
.IR lt .
The deadlock detector traverses the lock table, detects deadlocks,
and if it finds one,
marks one of the participating transactions for abort and then
returns.
.PP
The flags value is specified by
.BR or 'ing
together one or more of the following values:
.PP
.TP 5
DB_LOCK_CONFLICT
Only run the deadlock detector if a lock conflict has occurred since
the last time that the deadlock detector was run.
.PP
The
.I atype
parameter specifies which transaction to abort in the case of deadlock.
It must be set to one of values described above for the
.I lk_detect
field of the
.I DB_ENV
structure.
.PP
.Rt lock_detect
.PP
.Uf lock_detect db_deadlock
.SH "ENVIRONMENT VARIABLES"
The following environment variables affect the execution of
.IR db_lock :
.TP 5
.Eh lock_open
.TP 5
.Ev "lock table" lock
.SH "STANDARD LOCK MODES"
The include file <db2/db.h> declares two commonly used conflict arrays:
.TP 5
const u_int8_t db_lock_rw_conflicts[];
This is a conflict array for a simple scheme using shared and exclusive
lock modes.
.TP 5
const u_int8_t db_lock_riw_conflicts[];
This is a conflict array that involves various intent lock modes (e.g.,
intent shared) that are used for multigranularity locking.
.PP
Their associated sizes are DB_LOCK_RW_N and DB_LOCK_RIW_N.
.PP
In addition, the include file <db2/db.h> defines the type
.IR db_lockmode_t ,
which is the type of the lock modes used with the standard tables above:
.RS
.TP 5
DB_LOCK_NG
not granted (always 0)
.TP 5
DB_LOCK_READ
read (shared)
.TP 5
DB_LOCK_WRITE
write (exclusive)
.RE
.SH "ERRORS"
.Ee lock_open
.na
.Nh
close(2), 
db_version(3), 
fcntl(2), 
fflush(3), 
lock_unlink(3), 
lseek(2), 
malloc(3), 
memcpy(3), 
memset(3), 
mmap(2), 
munmap(2), 
open(2), 
sigfillset(3), 
sigprocmask(2), 
stat(2), 
strcpy(3), 
strdup(3), 
strerror(3), 
strlen(3), 
unlink(2), 
and
write(2). 
.Hy
.ad
.PP
.Ec lock_open
.TP 5
.Em
.TP 5
.Ei
.sp
.Et
.PP
.Ee lock_vec
.na
.Nh
fcntl(2), 
fflush(3), 
lock_detect(3), 
lseek(2), 
memcpy(3), 
memset(3), 
mmap(2), 
munmap(2), 
strerror(3), 
and
write(2). 
.Hy
.ad
.PP
.Ec lock_vec
.TP 5
[EACCES]
An attempt was made to release lock held by another locker.
.TP 5
.Ei
.PP
.Ee lock_get
.na
.Nh
fcntl(2), 
fflush(3), 
lock_detect(3), 
lseek(2), 
memcpy(3), 
memset(3), 
mmap(2), 
munmap(2), 
strerror(3), 
and
write(2). 
.Hy
.ad
.PP
.Ec lock_get
.TP 5
.Ei
.PP
.Ee lock_put
.na
.Nh
fcntl(2), 
fflush(3), 
lock_detect(3), 
lseek(2), 
memcpy(3), 
memset(3), 
mmap(2), 
munmap(2), 
strerror(3), 
and
write(2). 
.Hy
.ad
.PP
.Ec lock_put
.TP 5
[EACCES]
An attempt was made to release lock held by another locker.
.TP 5
.Ei
.PP
.Ee lock_close
.na
.Nh
close(2), 
fcntl(2), 
fflush(3), 
munmap(2), 
and
strerror(3). 
.Hy
.ad
.PP
.Ee lock_unlink
.na
.Nh
close(2), 
fcntl(2), 
fflush(3), 
malloc(3), 
memcpy(3), 
memset(3), 
mmap(2), 
munmap(2), 
open(2), 
sigfillset(3), 
sigprocmask(2), 
stat(2), 
strcpy(3), 
strdup(3), 
strerror(3), 
strlen(3), 
and
unlink(2). 
.Hy
.ad
.PP
.Ec lock_unlink
.TP 5
.Eb
.PP
.Ee lock_detect
.na
.Nh
calloc(3), 
fcntl(2), 
fflush(3), 
lseek(2), 
malloc(3), 
memcpy(3), 
memset(3), 
mmap(2), 
munmap(2), 
strerror(3), 
and
write(2). 
.Hy
.ad
.SH "BUGS"
If a process dies while holding locks, those locks remain held and are
.B never
released.
In this case, all processes should exit as quickly as possible, so
that
.I db_recover
can be run.
.SH "SEE ALSO"
.Sa