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_RegisterForAdapterPort-      HBA_RegisterForLinkEvents
       StatEvents
       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 version 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.10                                                          1 Sep 2003                                                     libhbaapi(3LIB)