'\" te
.\" Copyright (c) 2004-2006 Storage Networking Industry Association. All Rights Reserved.
.\" Copyright (c) 2006, Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH LIBMPAPI 3LIB "Dec 12, 2006"
.SH NAME
libMPAPI, libmpapi \- Common Mulitipath Management library
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR... ] \fIfile\fR... \fB-lMPAPI\fR  [ \fIlibrary\fR... ]
#include <\fBmpapi.h\fR>
#include <\fBmpapi_sun.h\fR>
.fi

.SH DESCRIPTION
.sp
.LP
The functions in this library allow a management application to administer the
multipath devices and associated resources through standard interfaces,
independent of a vendor-unique multipathing solution.
.SH INTERFACES
.sp
.LP
The shared object \fBlibMPAPI.so.1\fR provides the public interfaces defined
below. See \fBIntro\fR(3) for additional information on shared object
interfaces.
.br
.in +2
\fBMP_AssignLogicalUnitToTPG\fR
.in -2
.br
.in +2
\fBMP_CancelOverridePath\fR
.in -2
.br
.in +2
\fBMP_CompareOIDs\fR
.in -2
.br
.in +2
\fBMP_DeregisterForObjectPropertyChanges\fR
.in -2
.br
.in +2
\fBMP_DeregisterForObjectVisibilityChanges\fR
.in -2
.br
.in +2
\fBMP_DeregisterPlugin\fR
.in -2
.br
.in +2
\fBMP_DisableAutoFailback\fR
.in -2
.br
.in +2
\fBMP_DisableAutoProbing\fR
.in -2
.br
.in +2
\fBMP_DisablePath\fR
.in -2
.br
.in +2
\fBMP_EnableAutoFailback\fR
.in -2
.br
.in +2
\fBMP_EnableAutoProbing\fR
.in -2
.br
.in +2
\fBMP_EnablePath\fR
.in -2
.br
.in +2
\fBMP_FreeOidList\fR
.in -2
.br
.in +2
\fBMP_GetAssociatedPathOidList\fR
.in -2
.br
.in +2
\fBMP_GetAssociatedPluginOid\fR
.in -2
.br
.in +2
\fBMP_GetAssociatedTPGOidList\fR
.in -2
.br
.in +2
\fBMP_GetDeviceProductOidList\fR
.in -2
.br
.in +2
\fBMP_GetDeviceProductProperties\fR
.in -2
.br
.in +2
\fBMP_GetInitiatorPortOidList\fR
.in -2
.br
.in +2
\fBMP_GetInitiatorPortProperties\fR
.in -2
.br
.in +2
\fBMP_GetLibraryProperties\fR
.in -2
.br
.in +2
\fBMP_GetMPLogicalUnitProperties\fR
.in -2
.br
.in +2
\fBMP_GetMPLuOidListFromTPG\fR
.in -2
.br
.in +2
\fBMP_GetMultipathLus\fR
.in -2
.br
.in +2
\fBMP_GetObjectType\fR
.in -2
.br
.in +2
\fBMP_GetPathLogicalUnitProperties\fR
.in -2
.br
.in +2
\fBMP_GetPluginOidList\fR
.in -2
.br
.in +2
\fBMP_GetPluginProperties\fR
.in -2
.br
.in +2
\fBMP_GetProprietaryLoadBalanceOidList\fR
.in -2
.br
.in +2
\fBMP_GetProprietaryLoadBalanceProperties\fR
.in -2
.br
.in +2
\fBMP_GetTargetPortGroupProperties\fR
.in -2
.br
.in +2
\fBMP_GetTargetPortOidList\fR
.in -2
.br
.in +2
\fBMP_GetTargetPortProperties\fR
.in -2
.br
.in +2
\fBMP_RegisterForObjectPropertyChanges\fR
.in -2
.br
.in +2
\fBMP_RegisterForObjectVisibilityChanges\fR
.in -2
.br
.in +2
\fBMP_RegisterPlugin\fR
.in -2
.br
.in +2
\fBMP_SetFailbackPollingRate\fR
.in -2
.br
.in +2
\fBMP_SetLogicalUnitLoadBalanceType\fR
.in -2
.br
.in +2
\fBMP_SetOverridePath\fR
.in -2
.br
.in +2
\fBMP_SetPathWeight\fR
.in -2
.br
.in +2
\fBMP_SetPluginLoadBalanceType\fR
.in -2
.br
.in +2
\fBMP_SetProbingPollingRate\fR
.in -2
.br
.in +2
\fBMP_SetProprietaryProperties\fR
.in -2
.br
.in +2
\fBMP_SetTPGAccess\fR
.in -2
.br
.in +2
\fBSun_MP_SendScsiCmd\fR
.in -2
.SH USAGE
.sp
.LP
Client applications link with the Common Library (using \fB-lMPAPI\fR) to
access  the  interfaces.  The Common Library dynamically loads an individual
vendor-provided plugin library that is available through
\fBMP_RegisterPlugin\fR(3MPAPI) on the host system.
.sp
.LP
Using \fBlibMPAPI\fR involves the following steps:
.RS +4
.TP
1.
Optionally calling \fBMP_GetLibraryProperties()\fR to retrieve the
properties of the Common Library.
.RE
.RS +4
.TP
2.
Calling \fBMP_GetPluginOidList()\fR to retrieve the registered plugin
libraries.
.RE
.RS +4
.TP
3.
Optionally calling \fBMP_GetPluginProperties()\fR to retrieve the properties
of the plugin library.
.RE
.RS +4
.TP
4.
Retrieve discovery information and property information on multipath devices
and associated  resources  by calling the following:
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_GetAssociatedPathOidList()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_GetAssociatedTPGOidList()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_GetDeviceProductOidList()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_GetDeviceProductProperties()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_GetInitiatorPortOidList()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_GetInitiatorPortProperties()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_GetMPLuOidListFromTPG()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_GetMPLogicalUnitProperties()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_GetMultipathLus()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_GetPathLogicalUnitProperties()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_GetProprietaryLoadBalanceOidList()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_GetProprietaryLoadBalanceProperties()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_GetTargetPortGroupProperties()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_GetTargetPortOidList()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_GetTargetPortProperties()\fR
.RE
.RE
.RS +4
.TP
5.
Register and deregister for property and visibility changes on multipath
devices and associated resources by calling:
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_RegisterForObjectPropertyChanges()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_RegisterForObjectVisibilityChanges()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_DeregisterForObjectPropertyChanges()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_DeregisterForObjectVisibilityChanges()\fR
.RE
.RE
.RS +4
.TP
6.
Perform administrative operations on multipath devices and associated
resources by calling:
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_AssignLogicalUnitToTPG()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_CancelOverridePath()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_DisableAutoFailback()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_DisableAutoProbing()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_DisablePath()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_EnableAutoFailback()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_EnableAutoProbing()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_EnablePath()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_SetLogicalUnitLoadBalanceType()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_SetOverridePath()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_SetPathWeight()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_SetPluginLoadBalanceType()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_SetFailbackPollingRate()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_SetProbingPollingRate()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_SetProprietaryProperties()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBMP_SetTPGAccess()\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBSun_MP_SendScsiCmd()\fR
.RE
.RE
.SH ERRORS
.sp
.LP
Errors are generally returned from the underlying VSL and can include any of
the following values:
.sp
.ne 2
.na
\fB\fBMP_STATUS_SUCCESS\fR\fR
.ad
.sp .6
.RS 4n
This status value is returned when the requested operation is successfully
carried out.
.RE

.sp
.ne 2
.na
\fB\fBMP_STATUS_INVALID_PARAMETER\fR\fR
.ad
.sp .6
.RS 4n
This status value is returned when parameters passed to an API are detected to
be invalid or inappropriate for a particular API parameter. If the parameter is
an object ID, this status indicates that the object type subfield is defined in
this specification, but is not         appropriate for this API
.RE

.sp
.ne 2
.na
\fB\fBMP_STATUS_UNKNOWN_FN\fR\fR
.ad
.sp .6
.RS 4n
This status value is returned when a client function passed into the API is not
a previously registered or known function.
.RE

.sp
.ne 2
.na
\fB\fBMP_STATUS_FAILED\fR\fR
.ad
.sp .6
.RS 4n
This status value is returned when the requested operation could not be carried
out.
.RE

.sp
.ne 2
.na
\fB\fBMP_STATUS_INSUFFICIENT_MEMORY\fR\fR
.ad
.sp .6
.RS 4n
This status value is returned when the API could [not] allocate the memory
required to complete the requested operation.
.RE

.sp
.ne 2
.na
\fB\fBMP_STATUS_INVALID_OBJECT_TYPE\fR\fR
.ad
.sp .6
.RS 4n
This status value is returned when an object ID includes a type subfield that
is not defined in this specification.
.RE

.sp
.ne 2
.na
\fB\fBMP_STATUS_OBJECT_NOT_FOUND\fR\fR
.ad
.sp .6
.RS 4n
This status value is returned when the object associated with the ID specified
in the API could not be located, or has been deleted. Note that an invalid
object type is covered by \fBMP_STATUS_INVALID_OBJECT_TYPE\fR so this status is
limited to an invalid object owner identifier or sequence number.
.RE

.sp
.ne 2
.na
\fB\fBMP_STATUS_UNSUPPORTED\fR\fR
.ad
.sp .6
.RS 4n
This status value is returned when the implementation does not support the
requested function.
.RE

.sp
.ne 2
.na
\fB\fBMP_STATUS_FN_REPLACED\fR\fR
.ad
.sp .6
.RS 4n
This status value is returned when a client function passed into the API
replaces a previously registered function.
.RE

.sp
.ne 2
.na
\fB\fBMP_STATUS_ACCESS_STATE_INVALID\fR\fR
.ad
.sp .6
.RS 4n
This status value is returned when a device processing \fBMP_SetTPGAccess\fR
returns a status indicating that the caller is attempting to establish an
illegal combination of access states.
.RE

.sp
.ne 2
.na
\fB\fBMP_STATUS_PATH_NONOPERATIONAL\fR\fR
.ad
.sp .6
.RS 4n
This status is returned when communication cannot be established with the path
selected by the caller.
.RE

.sp
.ne 2
.na
\fB\fBMP_STATUS_TRY_AGAIN\fR\fR
.ad
.sp .6
.RS 4n
This status is returned when the plugin or driver is unable to complete the
request, but might be able to complete it later.
.RE

.sp
.ne 2
.na
\fB\fBMP_STATUS_NOT_PERMITTED\fR\fR
.ad
.sp .6
.RS 4n
The operation is not permitted in the current configuration, but might be
permitted in other configurations.
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/usr/lib/libMPAPI.so\fR\fR
.ad
.RS 27n
shared object
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/64/libMPAPI.so\fR\fR
.ad
.RS 27n
64-bit shared object
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
MT-Level	Safe
_
Standard	T{
ANSI INCITS 412 Multipath Management API (except for \fBSun_MP_SendScsiCmd\fR)
T}
.TE

.SH SEE ALSO
.sp
.LP
\fBIntro\fR(3), \fBMP_RegisterPlugin\fR(3MPAPI), \fBattributes\fR(5)
.sp
.LP
\fIMultipath Management API Version 1.0\fR