'\" te .\" Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved. .TH libhbaapi 3LIB "22 Aug 2011" "SunOS 5.11" "Interface Libraries" .SH NAME libhbaapi \- Common Fibre Channel HBA information library .SH SYNOPSIS .LP .nf cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lHBAAPI\fR [ \fIlibrary\fR\&.\|.\|. ] #include .fi .SH DESCRIPTION .sp .LP The functions in this library access Fibre Channel HBA data. .sp .LP Fibre Channel HBA information is provided through a standard interface in a vendor independent manner. This common interface provides access to the following information: .RS +4 .TP .ie t \(bu .el o Local HBA attributes .RE .RS +4 .TP .ie t \(bu .el o Local HBA port attributes and statistics .RE .RS +4 .TP .ie t \(bu .el o Mapping between FCP-2 discovered devices and operating system SCSI information .RE .RS +4 .TP .ie t \(bu .el o Discovered devices port attributes .RE .RS +4 .TP .ie t \(bu .el o SCSI commands for discovered FCP-2 devices (Report LUNS, Read Capacity, and Inquiry) .RE .RS +4 .TP .ie t \(bu .el o Common Transport commands to discover Fabric details .RE .SH INTERFACES .sp .LP The shared object \fBlibhbaapi.so.1\fR provides the public interfaces defined below. See \fBIntro\fR(3) for additional information on shared object interfaces. .sp .sp .TS tab(); lw(3i) lw(2.5i) lw(3i) lw(2.5i) . \fBHBA_CloseAdapter\fR\fBHBA_FreeLibrary\fR \fBHBA_GetAdapterAttributes\fR\fBHBA_GetAdapterName\fR \fBHBA_GetAdapterPortAttributes\fR\fBHBA_GetBindingCapability\fR \fBHBA_GetBindingSupport\fR\fBHBA_GetDiscoveredPortAttributes\fR \fBHBA_GetEventBuffer\fR\fBHBA_GetFC4Statistics\fR \fBHBA_GetFCPStatistics\fR\fBHBA_GetFcpPersistentBinding\fR \fBHBA_GetFcpTargetMapping\fR\fBHBA_GetFcpTargetMappingV2\fR \fBHBA_GetNumberOfAdapters\fR\fBHBA_GetPersistentBindingV2\fR \fBHBA_GetPortAttributesByWWN\fR\fBHBA_GetPortStatistics\fR \fBHBA_GetRNIDMgmtInfo\fR\fBHBA_GetVendorLibraryAttributes\fR \fBHBA_GetVersion\fR\fBHBA_GetWrapperLibraryAttributes\fR \fBHBA_LoadLibrary\fR\fBHBA_OpenAdapter\fR \fBHBA_OpenAdapterByWWN\fR\fBHBA_RefreshAdapterConfiguration\fR \fBHBA_RefreshInformation\fR\fBHBA_RegisterForAdapterAddEvents\fR \fBHBA_RegisterForAdapterEvents\fR\fBHBA_RegisterForAdapterPortEvents\fR \fBHBA_RegisterForAdapterPortStatEvents\fR\fBHBA_RegisterForLinkEvents\fR \fBHBA_RegisterForTargetEvents\fR\fBHBA_RemoveAllPersistentBindings\fR \fBHBA_RemoveCallback\fR\fBHBA_RemovePersistentBinding\fR \fBHBA_ResetStatistics\fR\fBHBA_ScsiInquiryV2\fR \fBHBA_ScsiReadCapacityV2\fR\fBHBA_ScsiReportLUNsV2\fR \fBHBA_SendCTPassThru\fR\fBHBA_SendCTPassThruV2\fR \fBHBA_SendLIRR\fR\fBHBA_SendRLS\fR \fBHBA_SendRNID\fR\fBHBA_SendRNIDV2\fR \fBHBA_SendRPL\fR\fBHBA_SendRPS\fR \fBHBA_SendReadCapacity\fR\fBHBA_SendReportLUNs\fR \fBHBA_SendSRL\fR\fBHBA_SendScsiInquiry\fR \fBHBA_SetBindingSupport\fR\fBHBA_SetPersistentBindingV2\fR \fBHBA_SetRNIDMgmtInfo\fR .TE .SH USAGE .sp .LP Client applications link with the Common Library (using \fB-l\fRHBAAPI) to access the interfaces. The Common Library dynamically loads individual Vendor-Specific Libraries (VSL) listed in \fB/etc/hba.conf\fR described on the \fBhba.conf\fR(4). .sp .LP Using the \fBlibhbaapi\fR involves the following steps: .RS +4 .TP 1. Optionally determining the version of the library by calling \fBHBA_GetVersion\fR(3HBAAPI). .RE .RS +4 .TP 2. Initializing the Common Library by calling \fBHBA_LoadLibrary\fR(3HBAAPI). .RE .RS +4 .TP 3. Determine the number of HBAs known to the common library by calling \fBHBA_GetNumberOfAdapters\fR(3HBAAPI). .RE .RS +4 .TP 4. Determine each HBA name in turn by calling \fBHBA_GetAdapterName\fR(3HBAAPI). .RE .RS +4 .TP 5. Open each HBA in turn by calling \fBHBA_OpenAdapter\fR(3HBAAPI). .RE .RS +4 .TP 6. Operate on a given HBA by calling the following: .RS +4 .TP .ie t \(bu .el o \fBHBA_GetAdapterAttributes\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_GetAdapterPortAttributes\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_GetDiscoveredPortAttributes\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_GetPortAttributesByWWN\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_SendCTPassThru\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_SendCTPassThruV2\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_GetEventBuffer\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_SetRNIDMgmtInfo\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_GetRNIDMgmtInfo\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_SendRNID\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_SendRNIDV2\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_RefreshInformation\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_RefreshAdapterConfiguration\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_GetVendorLibraryAttributes\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_GetWrapperLibraryAttributes\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_ResetStatistics\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_GetFcpTargetMapping\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_GetFcpTargetMappingV2\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_GetFcpPersistentBinding\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_SendScsiInquiry\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_SendReportLUNs\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_ScsiReportLUNsV2\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_SendReadCapacity\fR(3HBAAPI) .RE .RS +4 .TP .ie t \(bu .el o \fBHBA_SendRLS\fR(3HBAAPI) .RE .RE .RS +4 .TP 7. Close open HBAs by calling \fBHBA_CloseAdapter\fR(3HBAAPI). .RE .RS +4 .TP 8. Unload the library by calling \fBHBA_FreeLibrary\fR(3HBAAPI). .RE .SH ERRORS .sp .LP Errors are generally returned from the underlying VSL and can include any of the following values: .sp .ne 2 .mk .na \fB\fBHBA_STATUS_OK\fR\fR .ad .sp .6 .RS 4n Request completed successfully. (No Error) .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR\fR\fR .ad .sp .6 .RS 4n Non-specific error encountered. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_NOT_SUPPORTED\fR\fR .ad .sp .6 .RS 4n The VSL does not support this interface. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_INVALID_HANDLE\fR\fR .ad .sp .6 .RS 4n The \fIhandle\fR argument does not refer to an open HBA handle. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_ARG\fR\fR .ad .sp .6 .RS 4n An argument in the request was invalid. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_ILLEGAL_WWN\fR\fR .ad .sp .6 .RS 4n A WWN in the request was not recognized. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_ILLEGAL_INDEX\fR\fR .ad .sp .6 .RS 4n An index in the request was not recognized. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_MORE_DATA\fR\fR .ad .sp .6 .RS 4n A larger buffer is required to complete the requested operation. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_STALE_DATA\fR\fR .ad .sp .6 .RS 4n The state of the HBA has changed, possibly due to Dynamic Reconfiguration or devices being added or removed. The caller should call \fBHBA_RefreshInformation\fR(3HBAAPI) and reissue any discovery logic to reset all indexes related to this HBA. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_SCSI_CHECK_CONDITION\fR\fR .ad .sp .6 .RS 4n A SCSI check-condition was encountered during the I/O operation. Not all VSLs report this error value. Some might return \fBHBA_STATUS_ERROR\fR when a check-condition is encountered, or \fBHBA_STATUS_OK\fR. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_BUSY\fR\fR .ad .sp .6 .RS 4n The requested device is busy. A retry might be effective. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_TRY_AGAIN\fR\fR .ad .sp .6 .RS 4n The requested I/O timed out. A retry might be effective. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_UNAVAILABLE\fR\fR .ad .sp .6 .RS 4n The requested HBA has been removed or deactivated. .RE .sp .LP All other error values are reserved. .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Availabilitysystem/library/storage/snia-hbaapi _ Interface StabilityCommitted _ T{ Standard: FC-HBA Version 4 (API version 2) T} _ MT-LevelSafe _ StandardFC-MI 1.92 (API version 1) .TE .SH SEE ALSO .sp .LP \fBHBA_GetAdapterAttributes\fR(3HBAAPI), \fBHBA_GetAdapterName\fR(3HBAAPI), \fBHBA_GetAdapterPortAttributes\fR(3HBAAPI), \fBHBA_GetBindingCapability\fR(3HBAAPI), \fBHBA_GetDiscoveredPortAttributes\fR(3HBAAPI), \fBHBA_GetEventBuffer\fR(3HBAAPI), \fBHBA_GetFcpPersistentBinding\fR(3HBAAPI), \fBHBA_GetFcpTargetMapping\fR(3HBAAPI), \fBHBA_GetNumberOfAdapters\fR(3HBAAPI), \fBHBA_GetPortAttributesByWWN\fR(3HBAAPI), \fBHBA_GetPortStatistics\fR(3HBAAPI), \fBHBA_GetVersion\fR(3HBAAPI), \fBHBA_GetWrapperLibraryAttributes\fR(3HBAAPI), \fBHBA_LoadLibrary\fR(3HBAAPI), \fBHBA_OpenAdapter\fR(3HBAAPI), \fBHBA_RefreshInformation\fR(3HBAAPI), \fBHBA_RegisterForAdapterEvents\fR(3HBAAPI), \fBHBA_SendCTPassThru\fR(3HBAAPI), \fBHBA_SendRLS\fR(3HBAAPI), \fBHBA_SendScsiInquiry\fR(3HBAAPI), \fBHBA_SetRNIDMgmtInfo\fR(3HBAAPI), \fBhba.conf\fR(4), \fBattributes\fR(5) .sp .LP T11 FC-MI Specification