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.

Usage

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:

   • HBA_GetAdapterAttributes(3HBAAPI)

   • HBA_GetAdapterPortAttributes(3HBAAPI)

   • HBA_GetDiscoveredPortAttributes(3HBAAPI)

   • HBA_GetPortAttributesByWWN(3HBAAPI)

   • HBA_SendCTPassThru(3HBAAPI)

   • HBA_SendCTPassThruV2(3HBAAPI)

   • HBA_GetEventBuffer(3HBAAPI)

   • HBA_SetRNIDMgmtInfo(3HBAAPI)

   • HBA_GetRNIDMgmtInfo(3HBAAPI)

   • HBA_SendRNID(3HBAAPI)

   • HBA_SendRNIDV2(3HBAAPI)

   • HBA_RefreshInformation(3HBAAPI)

   • HBA_RefreshAdapterConfiguration(3HBAAPI)

   • HBA_GetVendorLibraryAttributes(3HBAAPI)

   • HBA_GetWrapperLibraryAttributes(3HBAAPI)

   • HBA_ResetStatistics(3HBAAPI)

   • HBA_GetFcpTargetMapping(3HBAAPI)

   • HBA_GetFcpTargetMappingV2(3HBAAPI)

   • HBA_GetFcpPersistentBinding(3HBAAPI)

   • HBA_SendScsiInquiry(3HBAAPI)

   • HBA_SendReportLUNs(3HBAAPI)

   • HBA_ScsiReportLUNsV2(3HBAAPI)

   • HBA_SendReadCapacity(3HBAAPI)

   • 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:

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(4), attributes(5)

T11 FC-MI Specification