Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

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(5).

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:

  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(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/library/storage/snia-hbaapi
Interface Stability
Committed
Standard: FC-HBA Version 4 (API version 2)
MT-Level
Safe
Standard
FC-MI 1.92 (API version 1)

See Also

HBA_GetAdapterAttributes(3HBAAPI), HBA_GetAdapterName(3HBAAPI), HBA_GetAdapterPortAttributes(3HBAAPI), HBA_GetBindingCapability(3HBAAPI), HBA_GetDiscoveredPortAttributes(3HBAAPI), HBA_GetEventBuffer(3HBAAPI), HBA_GetFcpPersistentBinding(3HBAAPI), HBA_GetFcpTargetMapping(3HBAAPI), HBA_GetNumberOfAdapters(3HBAAPI), HBA_GetPortAttributesByWWN(3HBAAPI), HBA_GetPortStatistics(3HBAAPI), HBA_GetVersion(3HBAAPI), HBA_GetWrapperLibraryAttributes(3HBAAPI), HBA_LoadLibrary(3HBAAPI), HBA_OpenAdapter(3HBAAPI), HBA_RefreshInformation(3HBAAPI), HBA_RegisterForAdapterEvents(3HBAAPI), HBA_SendCTPassThru(3HBAAPI), HBA_SendRLS(3HBAAPI), HBA_SendScsiInquiry(3HBAAPI), HBA_SetRNIDMgmtInfo(3HBAAPI), hba.conf(5), attributes(7)

T11 FC-MI Specification