HBA_GetFcpPeCommonnFibreiChannelAHBA InforHBA_GetFcpPersistentBinding(3HBAAPI)NAME
HBA_GetFcpPersistentBinding, HBA_GetPersistentBindingV2, HBA_SetPersis‐
tentBindingV2, HBA_RemovePersistentBinding, HBA_RemoveAllPersistent‐
Bindings - handle persistent bindings between FCP-2 discovered devices
and operating system SCSI information
SYNOPSIS
cc [ flag... ] file... -lHBAAPI [ library... ]
#include <hbaapi.h>
HBA_STATUS HBA_GetFcpPersistentBinding(HBA_HANDLE handle, HBA_FCPBIND‐
ING *binding);
HBA_STATUS HBA_GetPersistentBindingV2(HBA_HANDLE handle, HBA_WWN hba‐
PortWWN, HBA_FCPBINDING2 *binding);
HBA_STATUS HBA_SetPersistentBindingV2(HBA_HANDLE handle, HBA_WWN hba‐
PortWWN, HBA_FCPBINDING2 *binding);
HBA_STATUS HBA_RemovePersistentBinding(HBA_HANDLE handle, HBA_WWN hba‐
PortWWN, HBA_FCPBINDING2 *binding);
HBA_STATUS HBA_RemoveAllPersistentBindings(HBA_HANDLE handle, HBA_WWN
hbaPortWWN);
PARAMETERS
handle an open handle returned from HBA_OpenAdapter(3HBAAPI)
binding
HBA_GetFcpPersistentBinding()
a buffer to store the binding entries in. The
binding->NumberOfEntries member must indicate the
maximum number of entries that fit within the buf‐
fer. On completion, the binding->NumberOfEntries
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.
HBA_GetPersistentBindingV2()
a pointer to a HBA_FCPBINDING2 structure. The Num‐
berOfEntries member will be the maximum number of
entries returned.
HBA_SetPersistentBindingV2()
a pointer to a HBA_FCPBINDING2 structure. The Num‐
berOfEntries member will be the number of bindings
requested in the structure.
HBA_RemovePersistentBinding()
a pointer to a HBA_FCPBINDING2 structure. The
structure will contain all the bindings to be
removed. The NumberOfEntries member will be the
number of bindings being requested to be removed in
the structure.
hbaPortWWN
HBA_GetPersistentBindingV2()
The Port WWN of the local HBA through which persis‐
tent bindings will be retrieved.
HBA_SetPersistentBindingV2()
The Port WWN of the local HBA through which persis‐
tent bindings will be set.
HBA_RemovePersistentBinding()HBA_RemoveAllPersistentBindings()
The Port WWN of the local HBA through which persis‐
tent bindings will be removed.
DESCRIPTION
The HBA_GetFcpPersistentBinding() function retrieves the set of map‐
pings between FCP LUNs and SCSI LUNs that are reestablished upon ini‐
tialization or reboot. The means of establishing the persistent bind‐
ings is vendor-specific and accomplished outside the scope of the HBA
API.
The HBA_GetPersistentBindingV2() function retrieves the set of persis‐
tent 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 accom‐
plished outside the scope of the HBA API. The binding information can
contain bindings to Logical Unit Unique Device Identifiers.
The HBA_SetPersistentBindingV2() 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 Fab‐
ric has been reinitialized. Before then, the effects are not specified.
The HBA_RemovePersistentBinding() function removes one or more persis‐
tent 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.
The HBA_RemoveAllPersistentBindings() 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.
RETURN VALUES
The HBA_GetFcpPersistentBinding() function returns the following val‐
ues:
HBA_STATUS_OK
The HBA was able to retrieve information.
HBA_STATUS_ERROR_MORE_DATA
A a larger buffer is required. The value of binding->NumberOfEn‐
tries after the call indicates the total number of entries avail‐
able. The caller should reallocate a larger buffer to accomodate
the indicated number of entries and reissue the routine.
HBA_STATUS_ERROR_NOT_SUPPORTED
The HBA handle specified by handle does not support persistent
binding.
In the event that other error codes are returned, the value of bind‐
ing->NumberOfEntries 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.
The HBA_GetPersistentBindingV2() function returns the following values:
HBA_STATUS_OK
The HBA was able to retrieve information.
HBA_STATUS_ERROR_MORE_DATA
A a larger buffer is required. The value of binding->NumberOfEn‐
tries after the call indicates the total number of entries avail‐
able. The caller should reallocate a larger buffer to accomodate
the indicated number of entries and reissue the routine.
HBA_STATUS_ERROR_ILLEGAL_WWN
The Port WWN hbaPortWWN is not a WWN contained by the HBA refer‐
enced by handle.
HBA_STATUS_ERROR_NOT_SUPPORTED
The HBA handle specified by handle does not support persistent
binding.
The value of binding remains unchanged. The structure it points to con‐
tains binding information. The number of entries returned is the mini‐
mum between the number of entries specifed in the binding argument and
the total number of bindings.
The HBA_SetPersistentBindingV2() function returns the following values.
HBA_STATUS_OK
The HBA was able to set bindings.
HBA_STATUS_ERROR_ILLEGAL_WWN
The Port WWN hbaPortWWN is not a WWN contained by the HBA refer‐
enced by handle.
HBA_STATUS_ERROR_NOT_SUPPORTED
The HBA handle specified by handle does not support persistent
binding.
The value of binding remains unchanged. The success or failure of each
Persistent binding set is indicated in the Status member of the
HBA_FCPBINDINGENTRY2 structure.
The HBA_RemovePersistentBinding() function returns the following val‐
ues:
HBA_STATUS_OK
The HBA was able to retrieve information.
HBA_STATUS_ERROR_ILLEGAL_WWN
The Port WWN hbaPortWWN is not a WWN contained by the HBA refer‐
enced by handle.
HBA_STATUS_ERROR_NOT_SUPPORTED
The HBA handle specified by handle does not support persistent
binding.
The value of binding remains unchanged. The success or failure of each
Persistent binding set is indicated in the Status member of the
HBA_FCPBINDINGENTRY2 structure.
The HBA_RemoveAllPersistentBindings() function returns the following
values:
HBA_STATUS_OK
The HBA was able to retrieve information.
HBA_STATUS_ERROR_ILLEGAL_WWN
The Port WWN hbaPortWWN is not a WWN contained by the HBA refer‐
enced by handle.
HBA_STATUS_ERROR_NOT_SUPPORTED
The HBA handle specified by handle does not support persistent
binding.
ERRORS
See libhbaapi(3LIB) for general error status values.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Standard: FC-MI 1.92 (API │
│ │version 1) │
├─────────────────────────────┼─────────────────────────────┤
│ │Standard: FC-HBA Version 4 │
│ │(API version 2) │
├─────────────────────────────┼─────────────────────────────┤
│MT-Level │Safe │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOHBA_GetFcpTargetMapping(3HBAAPI), HBA_OpenAdapter(3HBAAPI), libh‐
baapi(3LIB), attributes(5)
T11 FC-MI Specification
BUGS
The HBA_GetFcpTargetMapping(3HBAAPI) and HBA_GetFcpPersistentBinding()
functions do not take a portindex 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 HBA_GetFcpTargetMappingV2() that takes a Port WWN as an argument.
This fixes the bug with multi-ported HBAs in HBA_GetFcpTargetMapping().
SunOS 5.10 1 Sep 20HBA_GetFcpPersistentBinding(3HBAAPI)