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_GetBindingSupport
HBA_GetEventBuffer
HBA_GetFCPStatistics
HBA_GetFcpTargetMapping
HBA_GetNumberOfAdapters
HBA_GetPortAttributesByWWN
HBA_GetRNIDMgmtInfo
HBA_GetVersion
HBA_LoadLibrary
HBA_OpenAdapterByWWN
HBA_RefreshInformation
HBA_RegisterForAdapterEvents
HBA_RegisterForAdapterPortStatEvents
HBA_RegisterForTargetEvents
HBA_RemoveCallback
HBA_ResetStatistics
HBA_ScsiReadCapacityV2
HBA_SendCTPassThru
HBA_SendLIRR
HBA_SendRNID
HBA_SendRPL
HBA_SendReadCapacity
HBA_SendSRL
HBA_SetBindingSupport
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_STATUS_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:
