Index for Section 3

Alphabetical listing for D

Bottom of page

dlm_rd_attach(3)
NAME
  dlm_rd_attach - Attaches a process or process lock group to a recovery
  domain

LIBRARY
  Distributed Lock Manager Library (libdlm.a)

SYNOPSIS
  #include <sys/dlm.h>

  dlm_status_t dlm_rd_attach (
	   char * name,
	   dlm_rd_id_t * rd_id_p,
	   dlm_rd_flags_t attach_flag );

PARAMETERS
  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
	    domain.

  attach_flag
	    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:

	    DLM_RD_PROCESS
		      Attaches the process to the recovery domain.

	    DLM_RD_GROUP
		      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.

DESCRIPTION
  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
       flag

  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.

RETURN VALUES
  Upon completion, the dlm_rd_attach() function call returns one of the
  following values:

  DLM_SUCCESS
	    The operation was completed successfully.

  DLM_ATTACHED
	    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.

  DLM_BADPARAM
	    No flags were specified, illegal flags were specified, or both
	    DLM_RD_PROCESS and DLM_RD_GROUP flags were specified.

  DLM_EFAULT
	    The rd_id_p parameter or name parameter points to an invalid
	    memory location.

  DLM_ENAMETOOLONG
	    The recovery domain name exceeds DLM_RDNAMELEN characters in
	    length.

  DLM_ENOSYS
	    The DLM is not enabled.

  DLM_INSFMEM
	    There is insufficient kernel memory to create the necessary data
	    structures.

  DLM_INTR  The process has aborted the dlm_rd_attach() request before
	    completion.

  DLM_NO_GROUP
	    The DLM_RD_GROUP flag was specified, but the process does not
	    belong to a process lock group.

  DLM_NOTATTACHED
	    The process has not yet called the dlm_nsjoin() function to
	    attach to a DLM namespace.

  DLM_TOOMANYRD
	    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.

FILES
  /usr/include/sys/dlm.h
	    DLM library header file.

RELATED INFORMATION
  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),
  dlm_unlock(3)

  File: dlm(4)

  TruCluster Server Cluster Highly Available Applications

Index for Section 3

Alphabetical listing for D

Top of page