Manual Pages for UNIX Operating System command usage for man HBA_GetFcpTargetMapping

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 information

SYNOPSIS
     cc [ flag... ] file... -lHBAAPI [ library... ]
     #include 

     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 comple-
                   tion,  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 follow-
     ing values:




SunOS 5.11           Last change: 1 Sep 2003                    1






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



     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  reallo-
         cate 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 rou-
     tine.

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

EXAMPLES
     Example 1 Return target mapping data.


     The following example returns target mapping data.  It  ini-
     tially allocates space for one target mapping. If the number



SunOS 5.11           Last change: 1 Sep 2003                    2






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



     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: \n");
               for (cntr = 0;
                   cntr < map->NumberOfEntries;
                   cntr ++) {
               printf("  Path(%d): \"%s\"\n", cntr,
               map->entry[cntr].ScsiId.OSDeviceName);
               }
           }
       }


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



















SunOS 5.11           Last change: 1 Sep 2003                    3






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



______________________________________________________________________
   |        ATTRIBUTE TYPE       |        ATTRIBUTE VALUE      |
   | ____________________________|_____________________________|_
   |  Interface Stability        |  Committed                  |
   | ____________________________|_____________________________|_
   |                             |  Standard: FC-HBA Version  4|
   |                             |  (API version 2)            |
   |_____________________________|_____________________________|
   | MT-Level                    | Safe                        |
   |_____________________________|_____________________________|
   | Standard                    | FC-MI 1.92 (API version 1)  |
   |_____________________________|_____________________________|


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


     T11 FC-MI Specification

BUGS
     The HBA_GetFcpTargetMapping() routine does not take  a  por-
     tindex  to  define which port of a multi-ported HBA the com-
     mand 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           Last change: 1 Sep 2003                    4






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






















































SunOS 5.11           Last change: 1 Sep 2003                    5