dat_ia_open man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

DAT_IA_OPEN(3DAT)					     DAT_IA_OPEN(3DAT)

NAME
       dat_ia_open - open an Interface Adapter (IA)

SYNOPSIS
       cc [ flag... ] file... -ldat [ library... ]
       #include <dat/udat.h>

       DAT_RETURN
	   dat_ia_open (
	   IN const DAT_NAME_PTR       ia_name_ptr,
	   IN	    DAT_COUNT	       async_evd_min_qlen,
	   INOUT    DAT_EVD_HANDLE     *async_evd_handle,
	   OUT	    DAT_IA_HANDLE      *ia_handle
	   )

PARAMETERS
       ia_name_ptr
			     Symbolic  name  for the IA to be opened. The name
			     should be defined by the Provider registration.

			     If the name is prefixed by the string  RO_AWARE_,
			     then  the prefix is removed prior to being passed
			     down and the existence of	the  prefix  indicates
			     that  the application has been coded to correctly
			     deal with relaxed ordering	 constraints.  If  the
			     prefix  is	 not present and the platform on which
			     the application is running is  utilizing  relaxed
			     ordering,	   the	  open	  will	  fail	  with
			     DAT_INVALID_PARAMETER (with DAT_SUBTYPE_STATUS of
			     DAT_INVALID_RO_COOKIE). This setting also affects
			     dat_lmr_create(3DAT).

       async_evd_min_qlen
			     Minimum length of	the  Asynchronous  Event  Dis‐
			     patcher queue.

       async_evd_handle
			     Pointer  to  a handle for an Event Dispatcher for
			     asynchronous events generated  by	the  IA.  This
			     parameter can be DAT_EVD_ASYNC_EXISTS to indicate
			     that there is already EVD for asynchronous events
			     for this Interface Adapter or DAT_HANDLE_NULL for
			     a Provider to generate EVD for it.

       ia_handle
			     Handle for an open instance of  a	DAT  IA.  This
			     handle  is used with other functions to specify a
			     particular instance of the IA.

DESCRIPTION
       The dat_ia_open() function opens an IA  by  creating  an	 IA  instance.
       Multiple instances (opens) of an IA can exist.

       The value of DAT_HANDLE_NULL for async_evd_handle (*async_evd_handle ==
       DAT_HANDLE_NULL) indicates that the default Event Dispatcher is created
       with the requested async_evd_min_qlen. The async_evd_handle returns the
       handle of the created Asynchronous Event Dispatcher. The first Consumer
       that  opens an IA must use DAT_HANDLE_NULL because no EVD can yet exist
       for the requested ia_name_ptr.

       The Asynchronous Event Dispatcher (async_evd_handle) is created with no
       CNO   (DAT_HANDLE_NULL).	  Consumers  can  change  these	 values	 using
       dat_evd_modify_cno(3DAT). The Consumer can  modify  parameters  of  the
       Event Dispatcher using dat_evd_resize(3DAT) and dat_evd_modify_cno().

       The  Provider  is  required  to	provide a queue size at least equal to
       async_evd_min_qlen, but is free to  provide  a  larger  queue  size  or
       dynamically  enlarge  the queue when needed. The Consumer can determine
       the  actual  queue  size	 by  querying  the  created  Event  Dispatcher
       instance.

       If  async_evd_handle is not DAT_HANDLE_NULL, the Provider does not cre‐
       ate an Event Dispatcher for an  asynchronous  event  and	 the  Provider
       ignores the async_evd_min_qlen value. The async_evd_handle value passed
       in by the Consumer must be an asynchronous Event Dispatcher created for
       the  same  Provider  (ia_name_ptr). The Provider does not have to check
       for the validity of the Consumer passed in async_evd_handle. It is  the
       Consumer responsibility to guarantee that async_evd_handle is valid and
       for this Provider. How the async_evd_handle is passed between DAT  Con‐
       sumers is out of scope of the DAT specification. If the Provider deter‐
       mines that the Consumer-provided async_evd_handle is invalid, the oper‐
       ation   fails  and  returns  DAT_INVALID_HANDLE.	 The  async_evd_handle
       remains unchanged, so the returned async_evd_handle  is	the  same  the
       Consumer	 passed	 in.  All  asynchronous	 notifications	for  the  open
       instance of the IA are directed by the Provider to the Consumer	passed
       in Asynchronous Event Dispatcher specified by async_evd_handle.

       Consumer can specify the value of DAT_EVD_ASYNC_EXISTS to indicate that
       there exists an event dispatcher somewhere else on the host, in user or
       kernel  space,  for  asynchronous  event notifications. It is up to the
       Consumer to ensure that this event dispatcher is unique	and  unambigu‐
       ous.  A	special handle may be returned for the Asynchronous Event Dis‐
       patcher for this scenario, DAT_EVD_OUT_OF_SCOPE, to indicate that there
       is  a default Event Dispatcher assigned for this Interface Adapter, but
       that it is not in a scope where this Consumer may directly invoke it.

       The Asynchronous Event Dispatcher is an Object of both the Provider and
       IA.   Each  Asynchronous	 Event	Dispatcher  bound to an IA instance is
       notified of all asynchronous events, such that binding  multiple	 Asyn‐
       chronous	 Event	Dispatchers  degrades performance by duplicating asyn‐
       chronous event notifications for all  Asynchronous  Event  Dispatchers.
       Also,  transport	 and  memory  resources can be consumed per Event Dis‐
       patcher bound to an IA

       As with all Event Dispatchers, the Consumer is responsible for synchro‐
       nizing access to the event queue.

       Valid IA names are obtained from dat_registry_list_providers(3DAT).

RETURN VALUES
       DAT_SUCCESS
				     The operation was successful.

       DAT_INSUFFICIENT_RESOURCES
				     The operation failed due to resource lim‐
				     itations.

       DAT_INVALID_PARAMETER
				     Invalid parameter.

       DAT_PROVIDER_NOT_FOUND
				     The specified provider was not registered
				     in the registry.

       DAT_INVALID_HANDLE
				     Invalid  DAT  handle; async_evd_handle is
				     invalid.

USAGE
       The dat_ia_open() function is the root method for  the  Provider,  and,
       thus,  all  Objects.  It	 is the root handle through which the Consumer
       obtains all other DAT handles. When the Consumer closes its handle, all
       its DAT Objects are released.

       The  dat_ia_open() function is the workhorse method that provides an IA
       instance. It can also initialize the Provider library or do  any	 other
       registry-specific functions.

       The  dat_ia_open()  function  creates a unique handle for the IA to the
       Consumer. All further DAT Objects created for this  Consumer  reference
       this handle as their owner.

       The  dat_ia_open()  function can use a reference count for the Provider
       Library to ensure that the Provider Library cannot be removed  when  it
       is in use by a DAT Consumer.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌────────────────────┬────────────────────────────────────┐
       │  ATTRIBUTE TYPE    │	       ATTRIBUTE VALUE		 │
       ├────────────────────┼────────────────────────────────────┤
       │Interface Stability │ Committed				 │
       ├────────────────────┼────────────────────────────────────┤
       │MT-Level	    │ Safe				 │
       ├────────────────────┼────────────────────────────────────┤
       │Standard	    │ uDAPL, 1.1, 1.2 (except RO_AWARE_) │
       └────────────────────┴────────────────────────────────────┘

SEE ALSO
       dat_evd_modify_cno(3DAT),   dat_evd_resize(3DAT),   dat_ia_close(3DAT),
       dat_registry_list_providers(3DAT), libdat(3LIB), attributes(5)

				 Jan 28, 2009		     DAT_IA_OPEN(3DAT)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net