 |
Index for
Section 3 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
dlm_lock(3)
NAME
dlm_lock, dlm_locktp - Synchronously requests a lock on a named resource
LIBRARY
Distributed Lock Manager Library (libdlm.a)
SYNOPSIS
#include <sys/dlm.h>
dlm_status_t dlm_lock (
dlm_nsp_t nsp,
uchar_t *resnam,
ushort_t resnlen,
dlm_lkid_t *parid,
dlm_lkid_t *lkid_p,
dlm_lkmode_t rqmode,
dlm_valb_t *valb_p,
dlm_flags_t flags,
callback_arg_t notprm,
callback_arg_t hint,
blk_callback_t blkrtn,
uint_t timeout );
dlm_status_t dlm_locktp (
dlm_nsp_t nsp,
uchar_t *resnam,
ushort_t resnlen,
dlm_lkid_t *parid,
dlm_lkid_t *lkid_p,
dlm_lkmode_t rqmode,
dlm_valb_t *valb_p,
dlm_flags_t flags,
callback_arg_t notprm,
callback_arg_t hint,
blk_callback_t blkrtn,
uint_t timeout,
dlm_trans_id_t trans_id,
dlm_rd_id_t rd_id );
PARAMETERS
nsp Identifies the namespace where the root resource exists. You
obtain this value by using the dlm_nsjoin() function to connect
to the namespace. This parameter is valid only for lock requests
with a parid of zero (0); that is, it must be zero (0) for child
locks.
resnam Specifies the address of a byte string that contains the name of
the resource to lock.
resnlen Specifies the length of the resource name. Resource names must
be from 1 to DLM_RESNAMELEN bytes long.
parid Specifies the lock ID of the parent lock. If you specify a value
of zero (0) for this parameter, the dlm_lock() and dlm_locktp()
functions assume that the lock does not have a parent lock (that
is, it is a root lock). If you specify a nonzero value, the
distributed lock manager (DLM) considers the requested lock to be
a sublock of the specified parent.
lkid_p Receives the lock ID of the requested lock.
rqmode Specifies the mode of the requested lock, as follows:
DLM_NLMODE
Null mode (NL)
DLM_CRMODE
Concurrent Read (CR)
DLM_CWMODE
Concurrent Write (CW)
DLM_PRMODE
Protected Read (PR)
DLM_PWMODE
Protected Write (PW)
DLM_EXMODE
Exclusive (EX)
See dlm(4) for a description of lock modes and a
discussion of legal lock conversions.
valb_p When specified, provides the address of a lock value block that
contains the number of longwords defined by the DLM_VALBLKSIZE
symbol in the dlm.h file. The lock value block contains
information about the resource that is interpreted only by the
user program. Note that, if you specify the DLM_VALB flag, you
must specify the valb_p parameter.
See dlm(4) for a discussion of lock value blocks.
flags When provided, specifies flags that modify the lock operation.
The flags parameter is a bit mask that is the logical OR of each
bit set, where each bit corresponds to an option. See the Flags
topic in the DESCRIPTION section of this reference page for a
description of those flags that can be specified in this
parameter.
notprm When specified, supplies a parameter to be passed to the blocking
notification routine specified by the blkrtn parameter. See
dlm(4) for a discussion of blocking notification routines.
hint When specified, provides a parameter to be passed to the blocking
notification routine of another lock that blocks this lock. See
dlm(4) for a discussion of blocking notification routines.
blkrtn When provided, specifies the address of a blocking notification
routine that is called whenever this lock is granted and is
blocking another lock request. You can specify a parameter to be
passed to this routine by using the notprm parameter. Specifing
NULL for blkrtn indicates that no blocking notification is
requested. See dlm(4) for a discussion of blocking notification
routines.
timeout When supplied, specifies, in multiples of 10 milliseconds, a
timeout value for the request. (The timeout granularity is one
second.) If the request is not completed within this interval,
the request is canceled with a DLM_TIMEOUT status. A timeout
value of zero (0) causes the lock request never to time out.
trans_id When provided in a dlm_locktp() call, identifies a transaction
that may manipulate the lock. The transaction may or may not span
cluster members, as indicated by the DLM_TXID_LOCAL or
DLM_TXID_GLOBAL flag. The values 0 and -1 are reserved to the
DLM. This parameter is valid only when the DLM_TXID_LOCAL or
DLM_TXID_GLOBAL flag is specified.
The scope of a transaction ID is limited to a namespace. The same
value in different namespaces indicates different transactions;
the same value in a single namespace indicates the same
transaction.
The DLM uses transaction IDs to fine tune its deadlock search
mechanism when process IDs and group IDs do not clearly reflect
lock ownership. If two locks have different transaction IDs, the
DLM considers them to have different owners, even if they have
been taken by the same process or processes with the same group
ID. If two locks have the same transaction ID, the DLM considers
them to have the same owner, even if they have been taken by
processes with different process or group IDs.
rd_id Specifies the recovery domain ID returned by a previous call to
dlm_rd_attach(). Use this parameter with the DLM_PERSIST flag to
lock a persistent resource on a dlm_locktp() call. If the
resource does not exist, it is created as a persistent resource.
(If the DLM_PERSIST flag is not specified, the rd_id parameter is
ignored and the resource is treated as nonpersistent.)
A single recovery domain can contain multiple persistent
resources; however, a single resource cannot belong to more than
one recovery domain. See dlm_rd_attach(3) for a discussion of
persistent resources and recovery domains.
DESCRIPTION
The dlm_lock() and dlm_locktp() functions request a new lock on a resource.
The dlm_locktp() function is identical to the dlm_lock() function except
that it supports the use of group locks, transaction IDs, and persistent
resources.
The function completes synchronously when the lock request has been granted
or has failed as indicated by the completion status. The lock manager
inserts the lock ID in the location specified by the lkid_p parameter. If
the lock request succeeds, you use this lock ID for subsequent manipulation
of this lock.
Flags
The dlm_flags_t structure defines a symbolic name for each flag bit. The
following list describes each flag:
DLM_GROUP_LOCK
Indicates that the lock is to be a group lock held by the group
lock container to which the process is attached. It can be
manipulated by other processes that are attached to the same
group lock container. This flag is valid only in a dlm_locktp()
function call.
DLM_NODLCKBLK
Indicates to the DLM that the process releases this lock on
demand if it is blocking another lock request. As a result, the
DLM does not consider this lock request when trying to detect
either conversion or multiple resource deadlock conditions.
A process typically specifies the DLM_NODLCKBLK flag only when it
also specifies a blocking notification routine in the blkrtn
parameter. The DLM calls a process's blocking notification
routine when the process holds a granted lock that is
incompatible with another lock on the conversion or waiting
queue.
Specifying the DLM_NODLCKBLK flag can help prevent certain false
deadlocks that can occur when blocking notifications are used.
In these deadlocks, the DLM will detect a blocking condition, but
the blocking condition will disappear as soon as the process
holding the lock executes, receives the blocking notification,
and dequeues the lock.
If the process specifies the DLM_NODLCKBLK flag, the blocking
notification routine should either dequeue the lock or convert it
to a lower lock mode without issuing any new lock requests. If
the blocking notification routine does otherwise, a genuine
deadlock could be ignored.
DLM_NODLCKWT
Indicates to the DLM that the caller is not blocked from
execution while waiting for the lock request to complete. As a
result, the DLM does not consider this lock request when trying
to detect either conversion or multiple resource deadlock
conditions.
For example, an application might specify this flag when it
intends to leave a lock request outstanding on the waiting queue
as a signaling device between processes. Be careful when you
specify this flag; improper use of the DLM_NODLCKWT flag can
cause the DLM to ignore genuine deadlocks.
DLM_NOQUEUE
Indicates that the caller does not desire to wait for the request
to be granted. When this flag is specified, the lock request is
not queued if it cannot be granted immediately.
DLM_PERSIST
Locks a persistent resource belonging to the recovery domain
identified by the rd_id parameter. It is an error to lock a
persistent resource without specifying the DLM_PERSIST flag.
Likewise, it is an error to lock a nonpersistent resource by
specifying the flag. See dlm_rd_attach(3) for a discussion of
persistent resources and recovery domains.
DLM_SYNCSTS
Indicates that the DLM should return the successful condition
value DLM_SYNCH if the lock request is granted immediately. If
the lock request cannot be granted immediately, the DLM returns
the condition value DLM_SUCCESS when the request is granted.
DLM_TXID_GLOBAL
Indicates that the lock is to be manipulated by a transaction
that may span cluster members, and that the DLM should use the
value in the trans_id argument to detect deadlocks among locks
with the same transaction ID. This flag is valid only in a
dlm_locktp() function call.
DLM_TXID_LOCAL
Indicates that the lock is to be manipulated by a transaction
that will not span cluster members, and that the DLM should use
the value in the trans_id argument to detect deadlocks among
locks with the same transaction ID. This flag is valid only in a
dlm_locktp() function call.
DLM_VALB Informs the DLM that the caller is interested in the resource's
lock value block. You must specify this flag to read or write
the resource's lock value block. When you specify the DLM_VALB
flag, you must specify the valb_p parameter. See dlm(4) for a
discussion of lock value blocks.
RETURN VALUES
Upon completion, the dlm_lock() or dlm_locktp() function returns one of the
following values:
DLM_SUCCESS
The lock request was successfully queued.
DLM_SUCCVALNOTVALID
The lock request completed successfully, but the resource's lock
value block was marked invalid. See dlm(4) for a discussion of
lock value blocks.
DLM_SYNCH The lock request completed successfully; the DLM_SYNCSTS flag in
the flags parameter was specified, and the DLM was able to grant
the lock request immediately.
DLM_SYNCVALNOTVALID
The lock request completed successfully; the DLM_SYNCSTS flag in
the flags parameter was specified, but the resource's lock value
block was marked invalid. See dlm(4) for a discussion of lock
value blocks.
DLM_ABORT The lock was dequeued by the dlm_unlock function before it was
granted.
DLM_BADPARAM
You specified an invalid lock mode in the rqmode parameter, a
nonzero parid with the nsp parameter, a trans_id of 0 or -1, or
an rd_id parameter that was out of the range of valid resource
domain IDs.
DLM_DEADLOCK
A conversion or multiple resource deadlock was detected. This
request has not been granted.
DLM_EFAULT
An error occurred in the copy operation to or from the DLM
database.
DLM_ENOSYS
The DLM is not enabled.
DLM_INSFMEM
There is insufficient kernel memory to create the necessary data
structures.
DLM_IS_PR An attempt was made to lock a persistent resource as
nonpersistent.
DLM_IVBUFLEN
The length of the resource name is less than 1 or greater than
DLM_RESNAMELEN.
DLM_IVLOCKID
You specified an invalid or nonexistent lock identification for
the parent lock ID.
DLM_IVRDID
No existing recovery domain corresponds to the value of the rd_id
parameter.
DLM_NO_GROUP
The DLM_GROUP_LOCK flag was specified and the process is not
attached to a group lock container.
DLM_NOTATTACHED
The process has not yet joined the namespace identified by the
nsp parameter, or the nsp parameter is less than zero (0) or
greater than or equal to DLM_NSPROCMAX.
DLM_NOTQUEUED
The lock request was not queued; the DLM_NOQUEUE flag in the
flags parameter was specified, and the DLM was unable to grant
the lock request immediately.
DLM_NOT_PR
An attempt was made to lock a nonpersistent resource as
persistent.
DLM_PARNOTGRANT
The parent lock specified in the parid parameter was not granted.
DLM_PR_RD_MISMATCH
An attempt was made to lock an existing persistent resource in
one recovery domain with an rd_id value that refers to another
recovery domain.
DLM_TIMEOUT
The lock request has timed out before being granted.
FILES
/usr/include/sys/dlm.h
DLM library header file.
/usr/examples/cluster/api_ex_master.c|api_ex_client.c
Source files for an example showing lock conversion and value
block usage.
RELATED INFORMATION
Functions: dlm_cancel(3), dlm_cvt(3), dlm_detach(3), dlm_get_lkinfo(3),
dlm_get_rsbinfo(3), dlm_glc_attach(3), dlm_glc_create(3),
dlm_glc_detach(3), dlm_glc_destroy(3), dlm_notify(3), dlm_nsjoin(3),
dlm_nsleave(3), dlm_perrno(3), dlm_quecvt(3), dlm_quelock(3),
dlm_rd_attach(3), dlm_rd_collect(3), dlm_rd_detach(3), dlm_rd_validate(3),
dlm_set_signal(3), dlm_unlock(3)
File: dlm(4)
TruCluster Server Cluster Highly Available Applications
|
Index for
Section 3 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|