lock_vec(DB_ENV *env, u_int32_t locker, u_int32_t flags,
DB_LOCKREQ list, int nlist, DB_LOCKREQ **elistp);
The lock_vec function atomically obtains and releases one or more locks
from the lock table. The 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
The locker argument specified to lock_vec is an unsigned
32-bit integer quantity. It represents the entity requesting or releasing
The flags value must be set to 0 or
the following value:
- If a lock cannot be immediately granted because the requested lock
conflicts with an existing lock, return instead of waiting for the lock
to become available.
The list array provided to lock_vec is typedef'd as
DB_LOCKREQ. A DB_LOCKREQ structure has at least the following fields.
In order to ensure compatibility with future releases of Berkeley DB, all
fields of the DB_LOCKREQ 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
- lockop_t op;
- The operation to be performed, which must be set to one of the
- Get the lock defined by the values of the lock, mode,
and obj structure fields, for the specified locker.
Upon return from lock_vec, if the lock field is
non-NULL, a reference to the acquired lock is stored there. (This
reference is invalidated by any call to lock_vec or
lock_put that releases the lock.)
- The lock to which the lock structure field refers is released.
The locker argument, and mode and obj fields
- All locks held by the specified locker are released. The
lock, mode, and obj structure fields are
ignored. Locks acquired in operations performed by the current call to
lock_vec which appear before the DB_LOCK_PUT_ALL
operation are released; those acquired in operations appearing after
the DB_LOCK_PUT_ALL operation are not released.
- All locks held on the object obj are released. The
locker argument and the lock and mode structure
fields are ignored. Locks acquired in operations performed by the
current call to lock_vec that appear before the
DB_LOCK_PUT_OBJ operation are released; those acquired in
operations appearing after the DB_LOCK_PUT_OBJ operation are
- DB_LOCK lock;
- A lock reference.
- const lockmode_t mode;
- The lock mode, used as an index into the environment's lock conflict matrix.
When using the default lock conflict matrix, mode must be set to one
of the following values:
- read (shared)
- write (exclusive)
- intention to write (shared)
- intention to read (shared)
- intention to read and write (shared)
See DB_ENV->set_lk_conflicts and Standard Lock Modes for more information on the lock conflict matrix.
- const DBT obj;
- An untyped byte string that specifies the object to be locked or
released. Applications using the locking subsystem directly while also
doing locking via the Berkeley DB access methods must take care not to
inadvertently lock objects that happen to be equal to the unique file
IDs used to lock files. See Access
method locking conventions for more information.
The nlist argument specifies the number of elements in the
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
lock_vec returns a non-zero value. In addition, if elistp
is not NULL, it is set to point to the DB_LOCKREQ entry that was being
processed when the error occurred.
If a lock is requested that cannot be immediately granted, and the
flags parameter was set to DB_LOCK_NOWAIT, the
lock_vec function may
DB_LOCK_NOTGRANTED. In this case, if non-NULL,
elistp identifies the request that was not granted.
Otherwise, the lock_vec function returns a non-zero error value on failure and 0 on success.
The lock_vec function may fail and return a non-zero error for the following conditions:
- The operation was selected to resolve a deadlock.
- An invalid flag value or parameter was specified.
- The maximum number of locks has been reached.
The lock_vec function may fail and return a non-zero error for errors specified for other Berkeley DB and C library or system functions.
If a catastrophic error has occurred, the lock_vec function may fail and return
DB_RUNRECOVERY, in which case all subsequent Berkeley DB calls will fail
in the same way.
Copyright Sleepycat Software