opensolaris man page for hba_getfcptargetmapping

HBA_GetFcpTargetMapping(3HBAAPI)	      Common Fibre Channel HBA Information Library Functions		  HBA_GetFcpTargetMapping(3HBAAPI)

NAME
       HBA_GetFcpTargetMapping,  HBA_GetFcpTargetMappingV2  - retrieve mapping between FCP-2 discovered devices and operating system SCSI informa-
       tion

SYNOPSIS
       cc [ flag... ] file... -lHBAAPI [ library... ]
       #include <hbaapi.h>

       HBA_STATUS HBA_GetFcpTargetMapping(HBA_HANDLE handle,
	    HBA_FCPTARGETMAPPING *mapping);

       HBA_STATUS HBA_GetFcpTargetMappingV2(HBA_HANDLE handle,
	    HBA_WWN hbaPortWWN, HBA_FCPTARGETMAPPINGV2 *mapping);

PARAMETERS
       handle	     an open handle returned from HBA_OpenAdapter(3HBAAPI)

       mapping	     a buffer in which to store the mapping entries. The mapping->NumberOfEntries member  must	indicate  the  maximum	number	of
		     entries  that  will fit within the buffer.  On completion, the mapping->NumberOfEntries member indicates the actual number of
		     mapping entries for the HBA.  This value can be greater than the number of entries the buffer can store.

       hbaPortWWN    the Port Name of the local HBA Port for which the caller is requesting target mappings.

DESCRIPTION
       The HBA_GetFcpTargetMapping() function retrieves the current set of mappings between FCP LUNs and SCSI LUNs for a given HBA port.

       The HBA_GetFcpTargetMappingV2() function retrieves the current set of mappings between FCP LUNs and SCSI LUNs for a given HBA. The  mapping
       also includes a Logical Unit Unique Identifier for each logical unit.

RETURN VALUES
       The HBA_GetFcpTargetMappingV2() function returns the following values:

       HBA_STATUS_ERROR_ILLEGAL_WWN

	   The port WWN specified by hbaPortWWN is not a valid port WWN on the specified HBA

       HBA_STATUS_ERROR_NOT_SUPPORTED

	   Target mappings are not supported on the HBA.

       HBA_STATUS_ERROR

	   An error occurred.

       The HBA_GetFcpTargetMapping() and HBA_GetFcpTargetMappingV2() functions return the following values:

       HBA_STATUS_OK

	   The HBA was able to retrieve information.

       HBA_STATUS_ERROR_MORE_DATA

	   A  larger  buffer  is  required.  The value of mapping->NumberOfEntries after the call indicates the total number of entries available.
	   The caller should reallocate the buffer large enough to accomodate the indicated number of entries and reissue the routine.

       In the event that other error values are returned, the value of mapping->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.

ERRORS
       See libhbaapi(3LIB) for general error status values.

EXAMPLES
       Example 1 Return target mapping data.

       The  following  example returns target mapping data. It initially allocates space for one target mapping. If the number of entries returned
       is greater than the allocated space, a new buffer with sufficient space is allocated and HBA_GetFcpTargetMapping() is called again.

	 map = (HBA_FCPTARGETMAPPING *)calloc(1,
	     sizeof (HBA_FCPTARGETMAPPING));
	 status = HBA_GetFcpTargetMapping(handle, map);
	 if (map->NumberOfEntries > 0) {
	     HBA_UINT32  noe = map->NumberOfEntries;
	     free(map);
	     map = (HBA_FCPTARGETMAPPING *)calloc (1,
		 sizeof (HBA_FCPTARGETMAPPING) +
		 (sizeof (HBA_FCPSCSIENTRY)*(noe - 1)));
	     map->NumberOfEntries = noe;
	     if ((status = HBA_GetFcpTargetMapping(handle, map)) !=
		     HBA_STATUS_OK) {
		 fprintf(stderr, " Failed to get target "
		     "mappings %d", status);
		 free(map);
	     } else {
		 printf(" FCP Mapping entries: 
");
		 for (cntr = 0;
		     cntr < map->NumberOfEntries;
		     cntr ++) {
		 printf("  Path(%d): "%s"
", cntr,
		 map->entry[cntr].ScsiId.OSDeviceName);
		 }
	     }
	 }

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 ver- |
       |			     |sion 2)				   |
       +-----------------------------+-------------------------------------+
       |MT-Level		     |Safe				   |
       +-----------------------------+-------------------------------------+

SEE ALSO
       HBA_OpenAdapter(3HBAAPI), libhbaapi(3LIB), attributes(5)

       T11 FC-MI Specification

BUGS
       The  HBA_GetFcpTargetMapping()  routine	does  not take a portindex to define which port of a multi-ported HBA the command should apply to.
       The behavior on multi-ported HBAs is vendor specific, and may result in mappings or bindings for all ports being intermixed in the response
       buffer.	 SNIA version 2 defines a HBA_GetFcpTargetMappingV2() which takes a Port WWN as an argument.  This fixes the bug with multi-ported
       HBAs in HBA_GetFcpTargetMapping().

SunOS 5.11							    1 Sep 2003					  HBA_GetFcpTargetMapping(3HBAAPI)