'\" te .\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. .TH HBA_GetFcpPersistentBinding 3HBAAPI "1 Sep 2003" "SunOS 5.11" "Common Fibre Channel HBA Information Library Functions" .SH NAME HBA_GetFcpPersistentBinding, HBA_GetPersistentBindingV2, HBA_SetPersistentBindingV2, HBA_RemovePersistentBinding, HBA_RemoveAllPersistentBindings \- handle persistent bindings between FCP-2 discovered devices and operating system SCSI information .SH SYNOPSIS .LP .nf cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lHBAAPI\fR [ \fIlibrary\fR\&.\|.\|. ] #include \fBHBA_STATUS\fR \fBHBA_GetFcpPersistentBinding\fR(\fBHBA_HANDLE\fR \fIhandle\fR, \fBHBA_FCPBINDING *\fR\fIbinding\fR); .fi .LP .nf \fBHBA_STATUS\fR \fBHBA_GetPersistentBindingV2\fR(\fBHBA_HANDLE\fR \fIhandle\fR, \fBHBA_WWN\fR \fIhbaPortWWN\fR, \fBHBA_FCPBINDING2 *\fR\fIbinding\fR); .fi .LP .nf \fBHBA_STATUS\fR \fBHBA_SetPersistentBindingV2\fR(\fBHBA_HANDLE\fR \fIhandle\fR, \fBHBA_WWN\fR \fIhbaPortWWN\fR, \fBHBA_FCPBINDING2 *\fR\fIbinding\fR); .fi .LP .nf \fBHBA_STATUS\fR \fBHBA_RemovePersistentBinding\fR(\fBHBA_HANDLE\fR \fIhandle\fR, \fBHBA_WWN\fR \fIhbaPortWWN\fR, \fBHBA_FCPBINDING2 *\fR\fIbinding\fR); .fi .LP .nf \fBHBA_STATUS\fR \fBHBA_RemoveAllPersistentBindings\fR(\fBHBA_HANDLE\fR \fIhandle\fR, \fBHBA_WWN\fR \fIhbaPortWWN\fR); .fi .SH PARAMETERS .sp .ne 2 .mk .na \fB\fIhandle\fR\fR .ad .RS 14n .rt an open handle returned from \fBHBA_OpenAdapter\fR(3HBAAPI) .RE .sp .ne 2 .mk .na \fB\fIbinding\fR\fR .ad .RS 14n .rt .sp .ne 2 .mk .na \fB\fBHBA_GetFcpPersistentBinding()\fR\fR .ad .sp .6 .RS 4n a buffer to store the binding entries in. The \fIbinding\fR->\fBNumberOfEntries\fR member must indicate the maximum number of entries that fit within the buffer. On completion, the \fIbinding\fR->\fBNumberOfEntries\fR member will indicate the actual number of binding entries for the HBA. This value can be greater than the number of entries the buffer can store. .RE .sp .ne 2 .mk .na \fB\fBHBA_GetPersistentBindingV2()\fR\fR .ad .sp .6 .RS 4n a pointer to a \fBHBA_FCPBINDING2\fR structure. The \fBNumberOfEntries\fR member will be the maximum number of entries returned. .RE .sp .ne 2 .mk .na \fB\fBHBA_SetPersistentBindingV2()\fR\fR .ad .sp .6 .RS 4n a pointer to a \fBHBA_FCPBINDING2\fR structure. The \fBNumberOfEntries\fR member will be the number of bindings requested in the structure. .RE .sp .ne 2 .mk .na \fB\fBHBA_RemovePersistentBinding()\fR\fR .ad .sp .6 .RS 4n a pointer to a \fBHBA_FCPBINDING2\fR structure. The structure will contain all the bindings to be removed. The \fBNumberOfEntries\fR member will be the number of bindings being requested to be removed in the structure. .RE .RE .sp .ne 2 .mk .na \fB\fIhbaPortWWN\fR\fR .ad .RS 14n .rt .sp .ne 2 .mk .na \fB\fBHBA_GetPersistentBindingV2()\fR\fR .ad .sp .6 .RS 4n The Port WWN of the local HBA through which persistent bindings will be retrieved. .RE .sp .ne 2 .mk .na \fB\fBHBA_SetPersistentBindingV2()\fR\fR .ad .sp .6 .RS 4n The Port WWN of the local HBA through which persistent bindings will be set. .RE .sp .ne 2 .mk .na \fB\fBHBA_RemovePersistentBinding()\fR\fR .ad .br .na \fB\fBHBA_RemoveAllPersistentBindings()\fR\fR .ad .sp .6 .RS 4n The Port WWN of the local HBA through which persistent bindings will be removed. .RE .RE .SH DESCRIPTION .sp .LP The \fBHBA_GetFcpPersistentBinding()\fR function retrieves the set of mappings between FCP LUNs and SCSI LUNs that are reestablished upon initialization or reboot. The means of establishing the persistent bindings is vendor-specific and accomplished outside the scope of the HBA API. .sp .LP The \fBHBA_GetPersistentBindingV2()\fR function retrieves the set of persistent bindings between FCP LUNs and SCSI LUNs for the specified HBA Port that are reestablished upon initialization or reboot. The means of establishing the persistent bindings is vendor-specific and accomplished outside the scope of the HBA API. The binding information can contain bindings to Logical Unit Unique Device Identifiers. .sp .LP The \fBHBA_SetPersistentBindingV2()\fR function sets additional persistent bindings between FCP LUNs and SCSI LUNs for the specified HBA Port. It can also accept bindings to Logical Unit Unique Device Identifiers. Bindings already set will remain set. An error occurs if a request is made to bind to an OS SCSI ID which has already been bound. Persistent bindings will not affect Target Mappings until the OS, HBA, and/or Fabric has been reinitialized. Before then, the effects are not specified. .sp .LP The \fBHBA_RemovePersistentBinding()\fR function removes one or more persistent bindings. The persistent binding will only be removed if both the OS SCSI LUN and the SCSI Lun match a binding specifed in the arguments. Persistent bindings removed will not affect Target Mappings until the OS, HBA, and/or Fabric has been reinitialized. Before then, the effects are not specified. .sp .LP The \fBHBA_RemoveAllPersistentBindings()\fR function removes all persistent bindings. Persistent bindings removed will not affect Target Mappings until the OS, HBA, and/or Fabric has been reinitialized. Before then, the effects are not specified. .SH RETURN VALUES .sp .LP The \fBHBA_GetFcpPersistentBinding()\fR function returns the following values: .sp .ne 2 .mk .na \fB\fBHBA_STATUS_OK\fR\fR .ad .sp .6 .RS 4n The HBA was able to retrieve information. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_MORE_DATA\fR\fR .ad .sp .6 .RS 4n A a larger buffer is required. The value of \fIbinding\fR->\fBNumberOfEntries\fR after the call indicates the total number of entries available. The caller should reallocate a larger buffer to accomodate the indicated number of entries and reissue the routine. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_NOT_SUPPORTED\fR\fR .ad .sp .6 .RS 4n The HBA handle specified by \fIhandle\fR does not support persistent binding. .RE .sp .LP In the event that other error codes are returned, the value of \fIbinding\fR->\fBNumberOfEntries\fR after the call should be checked, and if greater than the value before the call, a larger buffer should be allocated for a retry of the routine. .sp .LP The \fBHBA_GetPersistentBindingV2()\fR function returns the following values: .sp .ne 2 .mk .na \fB\fBHBA_STATUS_OK\fR\fR .ad .sp .6 .RS 4n The HBA was able to retrieve information. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_MORE_DATA\fR\fR .ad .sp .6 .RS 4n A a larger buffer is required. The value of \fIbinding\fR->\fBNumberOfEntries\fR after the call indicates the total number of entries available. The caller should reallocate a larger buffer to accomodate the indicated number of entries and reissue the routine. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_ILLEGAL_WWN\fR\fR .ad .sp .6 .RS 4n The Port WWN \fIhbaPortWWN\fR is not a WWN contained by the HBA referenced by \fIhandle\fR. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_NOT_SUPPORTED\fR\fR .ad .sp .6 .RS 4n The HBA handle specified by \fIhandle\fR does not support persistent binding. .RE .sp .LP The value of \fIbinding\fR remains unchanged. The structure it points to contains binding information. The number of entries returned is the minimum between the number of entries specifed in the binding argument and the total number of bindings. .sp .LP The \fBHBA_SetPersistentBindingV2()\fR function returns the following values. .sp .ne 2 .mk .na \fB\fBHBA_STATUS_OK\fR\fR .ad .sp .6 .RS 4n The HBA was able to set bindings. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_ILLEGAL_WWN\fR\fR .ad .sp .6 .RS 4n The Port WWN \fIhbaPortWWN\fR is not a WWN contained by the HBA referenced by \fIhandle\fR. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_NOT_SUPPORTED\fR\fR .ad .sp .6 .RS 4n The HBA handle specified by \fIhandle\fR does not support persistent binding. .RE .sp .LP The value of \fIbinding\fR remains unchanged. The success or failure of each Persistent binding set is indicated in the \fBStatus\fR member of the \fBHBA_FCPBINDINGENTRY2\fR structure. .sp .LP The \fBHBA_RemovePersistentBinding()\fR function returns the following values: .sp .ne 2 .mk .na \fB\fBHBA_STATUS_OK\fR\fR .ad .sp .6 .RS 4n The HBA was able to retrieve information. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_ILLEGAL_WWN\fR\fR .ad .sp .6 .RS 4n The Port WWN \fIhbaPortWWN\fR is not a WWN contained by the HBA referenced by \fIhandle\fR. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_NOT_SUPPORTED\fR\fR .ad .sp .6 .RS 4n The HBA handle specified by \fIhandle\fR does not support persistent binding. .RE .sp .LP The value of \fIbinding\fR remains unchanged. The success or failure of each Persistent binding set is indicated in the \fBStatus\fR member of the \fBHBA_FCPBINDINGENTRY2\fR structure. .sp .LP The \fBHBA_RemoveAllPersistentBindings()\fR function returns the following values: .sp .ne 2 .mk .na \fB\fBHBA_STATUS_OK\fR\fR .ad .sp .6 .RS 4n The HBA was able to retrieve information. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_ILLEGAL_WWN\fR\fR .ad .sp .6 .RS 4n The Port WWN \fIhbaPortWWN\fR is not a WWN contained by the HBA referenced by \fIhandle\fR. .RE .sp .ne 2 .mk .na \fB\fBHBA_STATUS_ERROR_NOT_SUPPORTED\fR\fR .ad .sp .6 .RS 4n The HBA handle specified by \fIhandle\fR does not support persistent binding. .RE .SH ERRORS .sp .LP See \fBlibhbaapi\fR(3LIB) for general error status values. .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 _ 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_GetFcpTargetMapping\fR(3HBAAPI), \fBHBA_OpenAdapter\fR(3HBAAPI), \fBlibhbaapi\fR(3LIB), \fBattributes\fR(5) .sp .LP T11 FC-MI Specification .SH BUGS .sp .LP The \fBHBA_GetFcpTargetMapping\fR(3HBAAPI) and \fBHBA_GetFcpPersistentBinding()\fR functions do not take a \fIportindex\fR to define to which port of a multi-ported HBA the command should apply. The behavior on multi-ported HBAs is vendor-specific and could result in mappings or bindings for all ports being intermixed in the response buffer. SNIA version 2 defines a \fBHBA_GetFcpTargetMappingV2()\fR that takes a Port WWN as an argument. This fixes the bug with multi-ported HBAs in \fBHBA_GetFcpTargetMapping()\fR.