libhbaapi(3LIB) 						Interface Libraries						   libhbaapi(3LIB)

NAME

       libhbaapi - Common Fibre Channel HBA information library

SYNOPSIS

       cc [ flag... ] file... -lHBAAPI [ library... ]
       #include <hbaapi.h>

DESCRIPTION

       The functions in this library access Fibre Channel HBA data.

       Fibre  Channel  HBA  information  is  provided through a standard interface in a vendor independent manner.  This common interface provides
       access to the following information:

	   o	  Local HBA attributes

	   o	  Local HBA port attributes and statistics

	   o	  Mapping between FCP-2 discovered devices and operating system SCSI information

	   o	  Discovered devices port attributes

	   o	  SCSI commands for discovered FCP-2 devices (Report LUNS, Read Capacity, and Inquiry)

	   o	  Common Transport commands to discover Fabric details

INTERFACES

       The shared object libhbaapi.so.1 provides the public interfaces defined below. See Intro(3) for additional  information	on  shared  object
       interfaces.

       HBA_CloseAdapter 		      HBA_FreeLibrary
       HBA_GetAdapterAttributes 	      HBA_GetAdapterName
       HBA_GetAdapterPortAttributes	      HBA_GetBindingCapability
       HBA_GetBindingSupport		      HBA_GetDiscoveredPortAttributes
       HBA_GetEventBuffer		      HBA_GetFC4Statistics
       HBA_GetFCPStatistics		      HBA_GetFcpPersistentBinding
       HBA_GetFcpTargetMapping		      HBA_GetFcpTargetMappingV2
       HBA_GetNumberOfAdapters		      HBA_GetPersistentBindingV2
       HBA_GetPortAttributesByWWN	      HBA_GetPortStatistics
       HBA_GetRNIDMgmtInfo		      HBA_GetVendorLibraryAttributes
       HBA_GetVersion			      HBA_GetWrapperLibraryAttributes
       HBA_LoadLibrary			      HBA_OpenAdapter
       HBA_OpenAdapterByWWN		      HBA_RefreshAdapterConfiguration
       HBA_RefreshInformation		      HBA_RegisterForAdapterAddEvents
       HBA_RegisterForAdapterEvents	      HBA_RegisterForAdapterPortEvents
       HBA_RegisterForAdapterPortStatEvents   HBA_RegisterForLinkEvents
       HBA_RegisterForTargetEvents	      HBA_RemoveAllPersistentBindings
       HBA_RemoveCallback		      HBA_RemovePersistentBinding
       HBA_ResetStatistics		      HBA_ScsiInquiryV2
       HBA_ScsiReadCapacityV2		      HBA_ScsiReportLUNsV2
       HBA_SendCTPassThru		      HBA_SendCTPassThruV2
       HBA_SendLIRR			      HBA_SendRLS
       HBA_SendRNID			      HBA_SendRNIDV2
       HBA_SendRPL			      HBA_SendRPS
       HBA_SendReadCapacity		      HBA_SendReportLUNs
       HBA_SendSRL			      HBA_SendScsiInquiry
       HBA_SetBindingSupport		      HBA_SetPersistentBindingV2

       HBA_SetRNIDMgmtInfo

USAGE

       Client applications link with the Common Library (using -lHBAAPI) to access the interfaces. The Common Library dynamically loads individual
       Vendor-Specific Libraries (VSL) listed in /etc/hba.conf described on the hba.conf(4).

       Using the libhbaapi involves the following steps:

	   1.	  Optionally determining the version of the library by calling HBA_GetVersion(3HBAAPI).

	   2.	  Initializing the Common Library by calling HBA_LoadLibrary(3HBAAPI).

	   3.	  Determine the number of HBAs known to the common library by calling HBA_GetNumberOfAdapters(3HBAAPI).

	   4.	  Determine each HBA name in turn by calling HBA_GetAdapterName(3HBAAPI).

	   5.	  Open each HBA in turn by calling HBA_OpenAdapter(3HBAAPI).

	   6.	  Operate on a given HBA by calling the following:

	       o      HBA_GetAdapterAttributes(3HBAAPI)

	       o      HBA_GetAdapterPortAttributes(3HBAAPI)

	       o      HBA_GetDiscoveredPortAttributes(3HBAAPI)

	       o      HBA_GetPortAttributesByWWN(3HBAAPI)

	       o      HBA_SendCTPassThru(3HBAAPI)

	       o      HBA_SendCTPassThruV2(3HBAAPI)

	       o      HBA_GetEventBuffer(3HBAAPI)

	       o      HBA_SetRNIDMgmtInfo(3HBAAPI)

	       o      HBA_GetRNIDMgmtInfo(3HBAAPI)

	       o      HBA_SendRNID(3HBAAPI)

	       o      HBA_SendRNIDV2(3HBAAPI)

	       o      HBA_RefreshInformation(3HBAAPI)

	       o      HBA_RefreshAdapterConfiguration(3HBAAPI)

	       o      HBA_GetVendorLibraryAttributes(3HBAAPI)

	       o      HBA_GetWrapperLibraryAttributes(3HBAAPI)

	       o      HBA_ResetStatistics(3HBAAPI)

	       o      HBA_GetFcpTargetMapping(3HBAAPI)

	       o      HBA_GetFcpTargetMappingV2(3HBAAPI)

	       o      HBA_GetFcpPersistentBinding(3HBAAPI)

	       o      HBA_SendScsiInquiry(3HBAAPI)

	       o      HBA_SendReportLUNs(3HBAAPI)

	       o      HBA_ScsiReportLUNsV2(3HBAAPI)

	       o      HBA_SendReadCapacity(3HBAAPI)

	       o      HBA_SendRLS(3HBAAPI)

	   7.	  Close open HBAs by calling HBA_CloseAdapter(3HBAAPI).

	   8.	  Unload the library by calling HBA_FreeLibrary(3HBAAPI).

ERRORS

       Errors are generally returned from the underlying VSL and can include any of the following values:

       HBA_STATUS_OK

	   Request completed successfully. (No Error)

       HBA_STATUS_ERROR

	   Non-specific error encountered.

       HBA_STATUS_ERROR_NOT_SUPPORTED

	   The VSL does not support this interface.

       HBA_STATUS_ERROR_INVALID_HANDLE

	   The handle argument does not refer to an open HBA handle.

       HBA_STATUS_ERROR_ARG

	   An argument in the request was invalid.

       HBA_STATUS_ERROR_ILLEGAL_WWN

	   A WWN in the request was not recognized.

       HBA_STATUS_ERROR_ILLEGAL_INDEX

	   An index in the request was not recognized.

       HBA_STATUS_ERROR_MORE_DATA

	   A larger buffer is required to complete the requested operation.

       HBA_STATUS_ERROR_STALE_DATA

	   The state of the HBA has changed, possibly due to Dynamic Reconfiguration or devices being added or removed.  The  caller  should  call
	   HBA_RefreshInformation(3HBAAPI) and reissue any discovery logic to reset all indexes related to this HBA.

       HBA_STATUS_SCSI_CHECK_CONDITION

	   A  SCSI  check-condition  was  encountered  during the I/O operation. Not all VSLs report this error value.	Some might return HBA_STA-
	   TUS_ERROR when a check-condition is encountered, or HBA_STATUS_OK.

       HBA_STATUS_ERROR_BUSY

	   The requested device is busy.  A retry might be effective.

       HBA_STATUS_ERROR_TRY_AGAIN

	   The requested I/O timed out.  A retry might be effective.

       HBA_STATUS_ERROR_UNAVAILABLE

	   The requested HBA has been removed or deactivated.

       All other error values are reserved.

ATTRIBUTES

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

       +-----------------------------+-------------------------------------+
       |      ATTRIBUTE TYPE	     |		ATTRIBUTE VALUE 	   |
       +-----------------------------+-------------------------------------+
       |Availability		     |SUNWcfcl (32-bit) 		   |
       +-----------------------------+-------------------------------------+
       |			     |SUNWcfclx (64-bit)		   |
       +-----------------------------+-------------------------------------+
       |Interface Stability	     |Standard: FC-MI 1.92 (API version 1) |
       +-----------------------------+-------------------------------------+
       |			     |Standard: FC-HBA Version 4 (API ver- |
       |			     |sion 2)				   |
       +-----------------------------+-------------------------------------+
       |MT-Level		     |Safe				   |
       +-----------------------------+-------------------------------------+

SEE ALSO

       HBA_GetAdapterAttributes(3HBAAPI),  HBA_GetAdapterName(3HBAAPI),  HBA_GetAdapterPortAttributes(3HBAAPI), HBA_GetBindingCapability(3HBAAPI),
       HBA_GetDiscoveredPortAttributes(3HBAAPI),    HBA_GetEventBuffer(3HBAAPI),    HBA_GetFcpPersistentBinding(3HBAAPI),     HBA_GetFcpTargetMap-
       ping(3HBAAPI),	 HBA_GetNumberOfAdapters(3HBAAPI),    HBA_GetPortAttributesByWWN(3HBAAPI),   HBA_GetPortStatistics(3HBAAPI),   HBA_GetVer-
       sion(3HBAAPI),	HBA_GetWrapperLibraryAttributes(3HBAAPI),    HBA_LoadLibrary(3HBAAPI),	  HBA_OpenAdapter(3HBAAPI),    HBA_RefreshInforma-
       tion(3HBAAPI),	HBA_RegisterForAdapterEvents(3HBAAPI),	HBA_SendCTPassThru(3HBAAPI),  HBA_SendRLS(3HBAAPI),  HBA_SendScsiInquiry(3HBAAPI),
       HBA_SetRNIDMgmtInfo(3HBAAPI), hba.conf(4), attributes(5)

       T11 FC-MI Specification

SunOS 5.11							    1 Sep 2003							   libhbaapi(3LIB)