Index Index for
Section 3
Index Alphabetical
listing for D
Bottom of page Bottom of
page		 

dlm_nsjoin(3)


NAME

  dlm_nsjoin - Connects the process to the specified resource namespace


LIBRARY

  Distributed Lock Manager Library (libdlm.a)


SYNOPSIS

  #include <sys/dlm.h>

  dlm_status_t dlm_nsjoin (
	  dlm_nsid_t nsid,
	  dlm_nsp_t *nsp,
	  dlm_flags_t flags );


PARAMETERS

  nsid	    Identifies the resource namespace. Specify either a zero (0) for
	    a systemwide namespace, a user ID (UID), or a group ID (GID).
	    The process must hold this ID for access to the namespace to be
	    granted.

  nsp	    Receives a handle that identifies the namespace.  An application
	    supplies this handle on subsequent calls to the dlm_lock(),
	    dlm_locktp(), dlm_quelock(), and dlm_quelocktp() functions when
	    creating a root lock in the namespace.

  flags	    Specifies flags that modify the operation. The flags parameter is
	    a bit mask that is the logical OR of each bit set, where each bit
	    corresponds to an option.

	    The dlm_flags_t structure defines a symbolic name for each flag
	    bit. The following list describes each flag:

	    DLM_GROUP Indicates that nsid specifies an effective group ID
		      (EGID) qualified namespace.  The process must be a
		      member of this group. The DLM_GROUP and DLM_USER flags
		      are mutually exclusive.

	    DLM_JOIN_SAME_OK
		      Allows a process to successfully call dlm_nsjoin() more
		      than once for the same namespace. When this flag is
		      specified and a process attempts to join a namespace it
		      has already joined, the dlm_nsjoin() function returns
		      the namespace handle in the nsp parameter and
		      DLM_SUCCESS status. Otherwise, the function returns
		      DLM_ATTACHED status and does not return a namespace
		      handle. Note that, if a process has joined the same
		      namespace multiple times (by using the DLM_JOIN_SAME_OK
		      flag in calls to the dlm_nsjoin() function), it needs
		      to make only one call to the dlm_nsleave() function to
		      disconnect from this namespace.

	    DLM_USER  Indicates that  nsid specifies an effective user ID
		      (EUID) qualified namespace.  The process must hold this
		      user ID.	A user ID of zero (0) indicates a systemwide
		      namespace.  In that case, the process must have root
		      privilege. The DLM_GROUP, DLM_PUBLIC, and DLM_USER
		      flags are mutually exclusive.

	    DLM_PUBLIC
		      Indicates that nsid specifies a public namespace. Note
		      that, because any process can connect to a public
		      namespace and manipulate locks in that namespace, you
		      must exercise caution when using it. Group-owned locks
		      are not allowed in a public namespace because any
		      process could take the lock away from its owner.	The
		      DLM_PUBLIC, DLM_GROUP, and DLM_USER flags are mutually
		      exclusive.


DESCRIPTION

  The dlm_nsjoin() function connects the process to the specified namespace
  for locking.

  A namespace can be viewed as a container for resource names. Multiple
  namespaces exist to provide separation of unrelated applications for
  reasons of security and modularity.  The namespaces are qualified by either
  EUID or EGID, or they are public namespaces.

  The application must request access to a namespace before attempting to
  acquire a lock on a resource in that namespace.  For non-public namespaces,
  the distributed lock manager (DLM) verifies that the application is
  permitted to access the indicated  namespace by verifying that the process
  holds the appropriate group ID, user ID, or root privilege as needed for
  that namespace.  The lock manager returns a handle to the namespace.	The
  application presents this handle on subsequent calls to acquire root locks.
  Sublocks can be added to a root lock without further access checks.

  The DLM_NSPROCMAX symbol specifies the maximum number of namespaces of
  which a process can be a member.  A process can join, leave, and then
  rejoin the same namespace.  After a process has joined a namespace,
  subsequent calls to the dlm_nsjoin() function for the same namespace will
  fail until the process successfully completes a dlm_nsleave() request for
  that namespace.

  It is the cluster administrator's responsibility to keep namespaces (for
  instance group and user IDs) consistent across the cluster.


RETURN VALUES

  Upon completion, the dlm_nsjoin() function returns one of the following
  values:

  DLM_SUCCESS
	    Connection was made to the namespace and a handle was returned.

  DLM_ATTACHED
	    This process has already joined the namespace, and did not
	    specify the DLM_JOIN_SAME_OK flag in the dlm_nsjoin function
	    call.

  DLM_BADPARAM
	    The nsp parameter was not specified or an illegal flag was
	    specified.

  DLM_EFAULT
	    An error occurred in the copy operation to or from the DLM
	    database.

  DLM_ENOSYS
	    The DLM is not enabled.

  DLM_NOACCESS
	    This process is not permitted access to the namespace.

  DLM_TOOMANYNS
	    This process is not able to join any more namespaces because it
	    has already attached to the maximum number of namespaces, as
	    specified by the DLM_NSPROCMAX symbol.

  DLM_PUBNS_DISALLOW
	    Group-owned locks are not allowed in a public namespace.


FILES

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

  /usr/examples/cluster/api_ex_master.c|api_ex_client.c
	    Source file 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_lock(3), dlm_notify(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 Index for
Section 3
Index Alphabetical
listing for D
Top of page Top of
page