listing for D
dlm_rd_attach - Attaches a process or process lock group to a recovery
Distributed Lock Manager Library (libdlm.a)
dlm_status_t dlm_rd_attach (
char * name,
dlm_rd_id_t * rd_id_p,
dlm_rd_flags_t attach_flag );
name Specifies the name of the recovery domain to which the process or
process lock group is to be attached. The name cannot exceed
DLM_RDNAMELEN characters in length.
rd_id_p Specifies a pointer to a location to which dlm_rd_attach()
returns a per-process handle for the recovery domain. Its value
is not unique within the cluster and cannot be used by other
processes, even those running on the same member system. The
process supplies this handle to subsequent calls to dlm_locktp(),
dlm_quelocktp(), dlm_rd_validate(), dlm_rd_collect(), and
dlm_rd_detach() to create persistent locks in the recovery domain
or otherwise operate on persistent locks existing in the domain.
If the process is attaching to the domain on behalf of a process
lock group (that is, it specifies the DLM_RD_GROUP flag in the
dlm_rd_attach() call), other processes in the process lock group
must also call the dlm_rd_attach() function to obtain a per-
process handle to the domain before requesting locks in the
Specifies flags that modify the operation. The attach_flag
parameter is a bit mask that is the logical OR of each bit set,
where each bit corresponds to an option.
The dlm_rd_flags_t structure defines a symbolic name for each
flag bit. The following list describes each flag:
Attaches the process to the recovery domain.
Attaches the process lock group to which the process
belongs to the recovery domain.
The DLM_RD_PROCESS and DLM_RD_GROUP flags are mutually exclusive.
The dlm_rd_attach() function attaches a process or process lock group to a
clusterwide recovery domain, returning a per-process handle for the
specified domain. If the recovery domain does not exist, the
dlm_rd_attach() function first creates it.
By specifying this handle in a subsequent dlm_locktp() or dlm_quelocktp()
function call using the DLM_PERSIST flag, a process or process lock group
creates a persistent resource. Multiple persistent resources can be created
in a single recovery domain; however, a single resource cannot exist
simultaneously in multiple recovery domains. Prior to calling the
dlm_rd_attach() function, a process must have attached to a DLM namespace
with a dlm_nsjoin() call.
A process or process lock group may be attached to up to DLM_MAX_RD_ATTACH
recovery domains at the same time.
Persistent resources are useful when an application must determine when an
object represented by a DLM resource name has been left in an inconsistent
state at the time the last lock on the resource has been dequeued.
Normally, when a process exits while holding a lock at a Protected Write
(PW) or Exclusive (EX) lock mode, the DLM marks the resource's value block
as invalid. If other locks were on the resource's conversion or wait queues
at that time, one or more of them would be granted, receiving a return
status indicating an invalid value block (DLM_SUCCVALNOTVALID or
DLM_SYNCVALNOTVALID). However, if there were no pending lock requests (that
is, this was the last lock on the resource), the resource itself would be
freed. The application would have no easy way of determining its state, or
the state of the object it represents.
A resource will survive the exit of the process (or the destruction of the
group lock container) that holds the last lock on it, regardless of the
mode of that lock, as long as the following is true:
· The resource was created as a persistent resource.
· The resource's value block is invalid.
· There are other processes or process lock groups attached to the
resource's recovery domain.
The DLM invalidates an entire recovery domain (that is, marks all resources
in the domain as invalid) in either of the following cases:
· When a cluster member system fails and that member system has a
process attached to the recovery domain
· When a process successfully calls the dlm_rd_detach() function,
specifying the rd_id of the recovery domain and the DLM_RD_INVALIDATE
While a persistent resource is invalid, the DLM will return
DLM_SUCCVALNOTVALID or DLM_SYNCVALNOTVALID status to all new lock requests
it grants on the resource.
The DLM deletes a persistent resource from the cluster if either of the
following is true:
· The last process or process lock group has detached from the
resource's recovery domain.
· The resource's value block has been marked valid by calls to the
dlm_rd_collect() and dlm_rd_validate() functions, and the last lock on
the resource has been released.
The DLM deletes a recovery domain from the cluster when all process and
process lock groups have detached from it.
Upon completion, the dlm_rd_attach() function call returns one of the
The operation was completed successfully.
The process is already attached to this recovery domain or the
process has already attached to this recovery domain on behalf of
its process lock group.
No flags were specified, illegal flags were specified, or both
DLM_RD_PROCESS and DLM_RD_GROUP flags were specified.
The rd_id_p parameter or name parameter points to an invalid
The recovery domain name exceeds DLM_RDNAMELEN characters in
The DLM is not enabled.
There is insufficient kernel memory to create the necessary data
DLM_INTR The process has aborted the dlm_rd_attach() request before
The DLM_RD_GROUP flag was specified, but the process does not
belong to a process lock group.
The process has not yet called the dlm_nsjoin() function to
attach to a DLM namespace.
Attaching to this resource domain would cause the process (or
process lock group to which it belongs) to be simultaneously
attached to more than DLM_MAX_RD_ATTACH recovery domains.
DLM library header file.
Functions: dlm_cancel(3), dlm_cvt(3), dlm_detach(3), dlm_get_lkinfo(3),
dlm_get_rsbinfo(3), dlm_glc_create(3), dlm_glc_detach(3),
dlm_glc_destroy(3), dlm_lock(3) dlm_notify(3), dlm_nsjoin(3),
dlm_nsleave(3), dlm_perrno(3), dlm_quecvt(3), dlm_quelock(3),
dlm_rd_collect(3), dlm_rd_detach(3), dlm_rd_validate(3), dlm_set_signal(3),
TruCluster Server Cluster Highly Available Applications
listing for D