man pages section 3: Library Interfaces and Headers

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:

Local HBA attributes
Local HBA port attributes and statistics
Mapping between FCP-2 discovered devices and operating system SCSI information
Discovered devices port attributes
SCSI commands for discovered FCP-2 devices (Report LUNS, Read Capacity, and Inquiry)
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:

Optionally determining the version of the library by calling HBA_GetVersion(3HBAAPI).
Initializing the Common Library by calling HBA_LoadLibrary(3HBAAPI).
Determine the number of HBAs known to the common library by calling HBA_GetNumberOfAdapters(3HBAAPI).
Determine each HBA name in turn by calling HBA_GetAdapterName(3HBAAPI).
Open each HBA in turn by calling HBA_OpenAdapter(3HBAAPI).
Operate on a given HBA by calling the following:
Close open HBAs by calling HBA_CloseAdapter(3HBAAPI).
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:

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 version 2)
MT-Level	Safe