dat_registry_list_providers(3dat) [sunos man page]
dat_registry_list_providers(3DAT) Direct Access Transport Library Functions dat_registry_list_providers(3DAT) NAME
dat_registry_list_providers - obtain a list of available pProviders from the Static Registry SYNOPSIS
typedef struct dat_provider_info { char ia_name[DAT_NAME_MAX_LENGTH]; DAT_UINT32 dapl_version_major; DAT_UINT32 dapl_version_minor; DAT_BOOLEAN is_thread_safe; } DAT_PROVIDER_INFO; cc [ flag... ] file... -ldat [ library... ] #include <dat/udat.h> DAT_RETURN dat_registry_list_providers ( IN DAT_COUNT max_to_return, OUT DAT_COUNT *number_entries, OUT DAT_PROVIDER_INFO *(dat_provider_list[]) ) PARAMETERS
max_to_return Maximum number of entries that can be returned to the Consumer in the dat_provider_list. number_entries The actual number of entries returned to the Consumer in the dat_provider_list if successful or the number of Providers available. dat_provider_lisPoints to an array of DAT_PROVIDER_INFO pointers supplied by the Consumer. Each Provider's information will be copied to the destination specified. DESCRIPTION
The dat_registry_list_providers() function allows the Consumer to obtain a list of available Providers from the Static Registry. The infor- mation provided is the Interface Adapter name, the uDAPL/kDAPL API version supported, and whether the provided version is thread-safe. The Consumer can examine the attributes to determine which (if any) Interface Adapters it wants to open. This operation has no effect on the Registry itself. The Registry can open an IA using a Provider whose dapl_version_minor is larger than the one the Consumer requests if no Provider entry matches exactly. Therefore, Consumers should expect that an IA can be opened successfully as long as at least one Provider entry returned by dat_registry_list_providers() matches the ia_name, dapl_version_major, and is_thread_safe fields exactly, and has a dapl_version_minor that is equal to or greater than the version requested. If the operation is successful, the returned value is DAT_SUCCESS and number_entries indicates the number of entries filled by the registry in dat_provider_list. If the operation is not successful, then number_entries returns the number of entries in the registry. Consumers can use this return to allocate dat_provider_list large enough for the registry entries. This number is just a snapshot at the time of the call and may be changed by the time of the next call. If the operation is not successful, then the content of dat_provider_list is not defined. If dat_provider_list is too small, including pointing to NULL for the registry entries, then the operation fails with the return DAT_INVALID_PARAMETER. RETURN VALUES
DAT_SUCCESS The operation was successful. DAT_INVALID_PARAMETER Invalid parameter. For example, dat_provider_list is too small or NULL. DAT_INTERNAL_ERROR Internal error. The DAT static registry is missing. USAGE
DAT_NAME_MAX_LENGTH includes the null character for string termination. ATTRIBUTES
See attributes(5) for descriptions of the following attributes: +-----------------------------+-----------------------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +-----------------------------+-----------------------------+ |Interface Stability |Standard: uDAPL, 1.1, 1.2 | +-----------------------------+-----------------------------+ |MT-Level |Safe | +-----------------------------+-----------------------------+ SEE ALSO
libdat(3LIB), attributes(5) SunOS 5.10 16 Jul 2004 dat_registry_list_providers(3DAT)
Check Out this Related Man Page
dat_ia_open(3DAT) Direct Access Transport Library Functions 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. async_evd_min_qlen Minimum length of the Asynchronous Event Dispatcher 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 dynam- ically 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 create 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 Consumers is out of scope of the DAT specification. If the Provider determines that the Consumer-provided async_evd_handle is invalid, the operation 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 unambiguous. A special handle may be returned for the Asynchronous Event Dispatcher 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 Asynchronous 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 synchronizing 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 limitations. 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 |Standard: uDAPL, 1.1, 1.2 | +-----------------------------+-----------------------------+ |MT-Level |Safe | +-----------------------------+-----------------------------+ SEE ALSO
dat_evd_modify_cno(3DAT), dat_evd_resize(3DAT), dat_ia_close(3DAT), dat_registry_list_providers(3DAT), libdat(3LIB), attributes(5) SunOS 5.10 16 Jul 2004 dat_ia_open(3DAT)