| blob | a6e97257a46d90837babde179fb692fefbdc4c3c |
1 '\" te
2 .\" Copyright (c) 2004-2006 Storage Networking Industry Association. All Rights Reserved.
3 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
4 .\" 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.
5 .\" 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.
6 .\" 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]
7 .TH LIBMPAPI 3LIB "Dec 12, 2006"
8 .SH NAME
9 libMPAPI, libmpapi \- Common Mulitipath Management library
10 .SH SYNOPSIS
11 .LP
12 .nf
13 cc [ \fIflag\fR... ] \fIfile\fR... \fB-lMPAPI\fR [ \fIlibrary\fR... ]
14 #include <\fBmpapi.h\fR>
15 #include <\fBmpapi_sun.h\fR>
16 .fi
18 .SH DESCRIPTION
19 .sp
20 .LP
21 The functions in this library allow a management application to administer the
22 multipath devices and associated resources through standard interfaces,
23 independent of a vendor-unique multipathing solution.
24 .SH INTERFACES
25 .sp
26 .LP
27 The shared object \fBlibMPAPI.so.1\fR provides the public interfaces defined
28 below. See \fBIntro\fR(3) for additional information on shared object
29 interfaces.
30 .br
31 .in +2
32 \fBMP_AssignLogicalUnitToTPG\fR
33 .in -2
34 .br
35 .in +2
36 \fBMP_CancelOverridePath\fR
37 .in -2
38 .br
39 .in +2
40 \fBMP_CompareOIDs\fR
41 .in -2
42 .br
43 .in +2
44 \fBMP_DeregisterForObjectPropertyChanges\fR
45 .in -2
46 .br
47 .in +2
48 \fBMP_DeregisterForObjectVisibilityChanges\fR
49 .in -2
50 .br
51 .in +2
52 \fBMP_DeregisterPlugin\fR
53 .in -2
54 .br
55 .in +2
56 \fBMP_DisableAutoFailback\fR
57 .in -2
58 .br
59 .in +2
60 \fBMP_DisableAutoProbing\fR
61 .in -2
62 .br
63 .in +2
64 \fBMP_DisablePath\fR
65 .in -2
66 .br
67 .in +2
68 \fBMP_EnableAutoFailback\fR
69 .in -2
70 .br
71 .in +2
72 \fBMP_EnableAutoProbing\fR
73 .in -2
74 .br
75 .in +2
76 \fBMP_EnablePath\fR
77 .in -2
78 .br
79 .in +2
80 \fBMP_FreeOidList\fR
81 .in -2
82 .br
83 .in +2
84 \fBMP_GetAssociatedPathOidList\fR
85 .in -2
86 .br
87 .in +2
88 \fBMP_GetAssociatedPluginOid\fR
89 .in -2
90 .br
91 .in +2
92 \fBMP_GetAssociatedTPGOidList\fR
93 .in -2
94 .br
95 .in +2
96 \fBMP_GetDeviceProductOidList\fR
97 .in -2
98 .br
99 .in +2
100 \fBMP_GetDeviceProductProperties\fR
101 .in -2
102 .br
103 .in +2
104 \fBMP_GetInitiatorPortOidList\fR
105 .in -2
106 .br
107 .in +2
108 \fBMP_GetInitiatorPortProperties\fR
109 .in -2
110 .br
111 .in +2
112 \fBMP_GetLibraryProperties\fR
113 .in -2
114 .br
115 .in +2
116 \fBMP_GetMPLogicalUnitProperties\fR
117 .in -2
118 .br
119 .in +2
120 \fBMP_GetMPLuOidListFromTPG\fR
121 .in -2
122 .br
123 .in +2
124 \fBMP_GetMultipathLus\fR
125 .in -2
126 .br
127 .in +2
128 \fBMP_GetObjectType\fR
129 .in -2
130 .br
131 .in +2
132 \fBMP_GetPathLogicalUnitProperties\fR
133 .in -2
134 .br
135 .in +2
136 \fBMP_GetPluginOidList\fR
137 .in -2
138 .br
139 .in +2
140 \fBMP_GetPluginProperties\fR
141 .in -2
142 .br
143 .in +2
144 \fBMP_GetProprietaryLoadBalanceOidList\fR
145 .in -2
146 .br
147 .in +2
148 \fBMP_GetProprietaryLoadBalanceProperties\fR
149 .in -2
150 .br
151 .in +2
152 \fBMP_GetTargetPortGroupProperties\fR
153 .in -2
154 .br
155 .in +2
156 \fBMP_GetTargetPortOidList\fR
157 .in -2
158 .br
159 .in +2
160 \fBMP_GetTargetPortProperties\fR
161 .in -2
162 .br
163 .in +2
164 \fBMP_RegisterForObjectPropertyChanges\fR
165 .in -2
166 .br
167 .in +2
168 \fBMP_RegisterForObjectVisibilityChanges\fR
169 .in -2
170 .br
171 .in +2
172 \fBMP_RegisterPlugin\fR
173 .in -2
174 .br
175 .in +2
176 \fBMP_SetFailbackPollingRate\fR
177 .in -2
178 .br
179 .in +2
180 \fBMP_SetLogicalUnitLoadBalanceType\fR
181 .in -2
182 .br
183 .in +2
184 \fBMP_SetOverridePath\fR
185 .in -2
186 .br
187 .in +2
188 \fBMP_SetPathWeight\fR
189 .in -2
190 .br
191 .in +2
192 \fBMP_SetPluginLoadBalanceType\fR
193 .in -2
194 .br
195 .in +2
196 \fBMP_SetProbingPollingRate\fR
197 .in -2
198 .br
199 .in +2
200 \fBMP_SetProprietaryProperties\fR
201 .in -2
202 .br
203 .in +2
204 \fBMP_SetTPGAccess\fR
205 .in -2
206 .br
207 .in +2
208 \fBSun_MP_SendScsiCmd\fR
209 .in -2
210 .SH USAGE
211 .sp
212 .LP
213 Client applications link with the Common Library (using \fB-lMPAPI\fR) to
214 access the interfaces. The Common Library dynamically loads an individual
215 vendor-provided plugin library that is available through
216 \fBMP_RegisterPlugin\fR(3MPAPI) on the host system.
217 .sp
218 .LP
219 Using \fBlibMPAPI\fR involves the following steps:
220 .RS +4
221 .TP
222 1.
223 Optionally calling \fBMP_GetLibraryProperties()\fR to retrieve the
224 properties of the Common Library.
225 .RE
226 .RS +4
227 .TP
228 2.
229 Calling \fBMP_GetPluginOidList()\fR to retrieve the registered plugin
230 libraries.
231 .RE
232 .RS +4
233 .TP
234 3.
235 Optionally calling \fBMP_GetPluginProperties()\fR to retrieve the properties
236 of the plugin library.
237 .RE
238 .RS +4
239 .TP
240 4.
241 Retrieve discovery information and property information on multipath devices
242 and associated resources by calling the following:
243 .RS +4
244 .TP
245 .ie t \(bu
246 .el o
247 \fBMP_GetAssociatedPathOidList()\fR
248 .RE
249 .RS +4
250 .TP
251 .ie t \(bu
252 .el o
253 \fBMP_GetAssociatedTPGOidList()\fR
254 .RE
255 .RS +4
256 .TP
257 .ie t \(bu
258 .el o
259 \fBMP_GetDeviceProductOidList()\fR
260 .RE
261 .RS +4
262 .TP
263 .ie t \(bu
264 .el o
265 \fBMP_GetDeviceProductProperties()\fR
266 .RE
267 .RS +4
268 .TP
269 .ie t \(bu
270 .el o
271 \fBMP_GetInitiatorPortOidList()\fR
272 .RE
273 .RS +4
274 .TP
275 .ie t \(bu
276 .el o
277 \fBMP_GetInitiatorPortProperties()\fR
278 .RE
279 .RS +4
280 .TP
281 .ie t \(bu
282 .el o
283 \fBMP_GetMPLuOidListFromTPG()\fR
284 .RE
285 .RS +4
286 .TP
287 .ie t \(bu
288 .el o
289 \fBMP_GetMPLogicalUnitProperties()\fR
290 .RE
291 .RS +4
292 .TP
293 .ie t \(bu
294 .el o
295 \fBMP_GetMultipathLus()\fR
296 .RE
297 .RS +4
298 .TP
299 .ie t \(bu
300 .el o
301 \fBMP_GetPathLogicalUnitProperties()\fR
302 .RE
303 .RS +4
304 .TP
305 .ie t \(bu
306 .el o
307 \fBMP_GetProprietaryLoadBalanceOidList()\fR
308 .RE
309 .RS +4
310 .TP
311 .ie t \(bu
312 .el o
313 \fBMP_GetProprietaryLoadBalanceProperties()\fR
314 .RE
315 .RS +4
316 .TP
317 .ie t \(bu
318 .el o
319 \fBMP_GetTargetPortGroupProperties()\fR
320 .RE
321 .RS +4
322 .TP
323 .ie t \(bu
324 .el o
325 \fBMP_GetTargetPortOidList()\fR
326 .RE
327 .RS +4
328 .TP
329 .ie t \(bu
330 .el o
331 \fBMP_GetTargetPortProperties()\fR
332 .RE
333 .RE
334 .RS +4
335 .TP
336 5.
337 Register and deregister for property and visibility changes on multipath
338 devices and associated resources by calling:
339 .RS +4
340 .TP
341 .ie t \(bu
342 .el o
343 \fBMP_RegisterForObjectPropertyChanges()\fR
344 .RE
345 .RS +4
346 .TP
347 .ie t \(bu
348 .el o
349 \fBMP_RegisterForObjectVisibilityChanges()\fR
350 .RE
351 .RS +4
352 .TP
353 .ie t \(bu
354 .el o
355 \fBMP_DeregisterForObjectPropertyChanges()\fR
356 .RE
357 .RS +4
358 .TP
359 .ie t \(bu
360 .el o
361 \fBMP_DeregisterForObjectVisibilityChanges()\fR
362 .RE
363 .RE
364 .RS +4
365 .TP
366 6.
367 Perform administrative operations on multipath devices and associated
368 resources by calling:
369 .RS +4
370 .TP
371 .ie t \(bu
372 .el o
373 \fBMP_AssignLogicalUnitToTPG()\fR
374 .RE
375 .RS +4
376 .TP
377 .ie t \(bu
378 .el o
379 \fBMP_CancelOverridePath()\fR
380 .RE
381 .RS +4
382 .TP
383 .ie t \(bu
384 .el o
385 \fBMP_DisableAutoFailback()\fR
386 .RE
387 .RS +4
388 .TP
389 .ie t \(bu
390 .el o
391 \fBMP_DisableAutoProbing()\fR
392 .RE
393 .RS +4
394 .TP
395 .ie t \(bu
396 .el o
397 \fBMP_DisablePath()\fR
398 .RE
399 .RS +4
400 .TP
401 .ie t \(bu
402 .el o
403 \fBMP_EnableAutoFailback()\fR
404 .RE
405 .RS +4
406 .TP
407 .ie t \(bu
408 .el o
409 \fBMP_EnableAutoProbing()\fR
410 .RE
411 .RS +4
412 .TP
413 .ie t \(bu
414 .el o
415 \fBMP_EnablePath()\fR
416 .RE
417 .RS +4
418 .TP
419 .ie t \(bu
420 .el o
421 \fBMP_SetLogicalUnitLoadBalanceType()\fR
422 .RE
423 .RS +4
424 .TP
425 .ie t \(bu
426 .el o
427 \fBMP_SetOverridePath()\fR
428 .RE
429 .RS +4
430 .TP
431 .ie t \(bu
432 .el o
433 \fBMP_SetPathWeight()\fR
434 .RE
435 .RS +4
436 .TP
437 .ie t \(bu
438 .el o
439 \fBMP_SetPluginLoadBalanceType()\fR
440 .RE
441 .RS +4
442 .TP
443 .ie t \(bu
444 .el o
445 \fBMP_SetFailbackPollingRate()\fR
446 .RE
447 .RS +4
448 .TP
449 .ie t \(bu
450 .el o
451 \fBMP_SetProbingPollingRate()\fR
452 .RE
453 .RS +4
454 .TP
455 .ie t \(bu
456 .el o
457 \fBMP_SetProprietaryProperties()\fR
458 .RE
459 .RS +4
460 .TP
461 .ie t \(bu
462 .el o
463 \fBMP_SetTPGAccess()\fR
464 .RE
465 .RS +4
466 .TP
467 .ie t \(bu
468 .el o
469 \fBSun_MP_SendScsiCmd()\fR
470 .RE
471 .RE
472 .SH ERRORS
473 .sp
474 .LP
475 Errors are generally returned from the underlying VSL and can include any of
476 the following values:
477 .sp
478 .ne 2
479 .na
480 \fB\fBMP_STATUS_SUCCESS\fR\fR
481 .ad
482 .sp .6
483 .RS 4n
484 This status value is returned when the requested operation is successfully
485 carried out.
486 .RE
488 .sp
489 .ne 2
490 .na
491 \fB\fBMP_STATUS_INVALID_PARAMETER\fR\fR
492 .ad
493 .sp .6
494 .RS 4n
495 This status value is returned when parameters passed to an API are detected to
496 be invalid or inappropriate for a particular API parameter. If the parameter is
497 an object ID, this status indicates that the object type subfield is defined in
498 this specification, but is not appropriate for this API
499 .RE
501 .sp
502 .ne 2
503 .na
504 \fB\fBMP_STATUS_UNKNOWN_FN\fR\fR
505 .ad
506 .sp .6
507 .RS 4n
508 This status value is returned when a client function passed into the API is not
509 a previously registered or known function.
510 .RE
512 .sp
513 .ne 2
514 .na
515 \fB\fBMP_STATUS_FAILED\fR\fR
516 .ad
517 .sp .6
518 .RS 4n
519 This status value is returned when the requested operation could not be carried
520 out.
521 .RE
523 .sp
524 .ne 2
525 .na
526 \fB\fBMP_STATUS_INSUFFICIENT_MEMORY\fR\fR
527 .ad
528 .sp .6
529 .RS 4n
530 This status value is returned when the API could [not] allocate the memory
531 required to complete the requested operation.
532 .RE
534 .sp
535 .ne 2
536 .na
537 \fB\fBMP_STATUS_INVALID_OBJECT_TYPE\fR\fR
538 .ad
539 .sp .6
540 .RS 4n
541 This status value is returned when an object ID includes a type subfield that
542 is not defined in this specification.
543 .RE
545 .sp
546 .ne 2
547 .na
548 \fB\fBMP_STATUS_OBJECT_NOT_FOUND\fR\fR
549 .ad
550 .sp .6
551 .RS 4n
552 This status value is returned when the object associated with the ID specified
553 in the API could not be located, or has been deleted. Note that an invalid
554 object type is covered by \fBMP_STATUS_INVALID_OBJECT_TYPE\fR so this status is
555 limited to an invalid object owner identifier or sequence number.
556 .RE
558 .sp
559 .ne 2
560 .na
561 \fB\fBMP_STATUS_UNSUPPORTED\fR\fR
562 .ad
563 .sp .6
564 .RS 4n
565 This status value is returned when the implementation does not support the
566 requested function.
567 .RE
569 .sp
570 .ne 2
571 .na
572 \fB\fBMP_STATUS_FN_REPLACED\fR\fR
573 .ad
574 .sp .6
575 .RS 4n
576 This status value is returned when a client function passed into the API
577 replaces a previously registered function.
578 .RE
580 .sp
581 .ne 2
582 .na
583 \fB\fBMP_STATUS_ACCESS_STATE_INVALID\fR\fR
584 .ad
585 .sp .6
586 .RS 4n
587 This status value is returned when a device processing \fBMP_SetTPGAccess\fR
588 returns a status indicating that the caller is attempting to establish an
589 illegal combination of access states.
590 .RE
592 .sp
593 .ne 2
594 .na
595 \fB\fBMP_STATUS_PATH_NONOPERATIONAL\fR\fR
596 .ad
597 .sp .6
598 .RS 4n
599 This status is returned when communication cannot be established with the path
600 selected by the caller.
601 .RE
603 .sp
604 .ne 2
605 .na
606 \fB\fBMP_STATUS_TRY_AGAIN\fR\fR
607 .ad
608 .sp .6
609 .RS 4n
610 This status is returned when the plugin or driver is unable to complete the
611 request, but might be able to complete it later.
612 .RE
614 .sp
615 .ne 2
616 .na
617 \fB\fBMP_STATUS_NOT_PERMITTED\fR\fR
618 .ad
619 .sp .6
620 .RS 4n
621 The operation is not permitted in the current configuration, but might be
622 permitted in other configurations.
623 .RE
625 .SH FILES
626 .sp
627 .ne 2
628 .na
629 \fB\fB/usr/lib/libMPAPI.so\fR\fR
630 .ad
631 .RS 27n
632 shared object
633 .RE
635 .sp
636 .ne 2
637 .na
638 \fB\fB/usr/lib/64/libMPAPI.so\fR\fR
639 .ad
640 .RS 27n
641 64-bit shared object
642 .RE
644 .SH ATTRIBUTES
645 .sp
646 .LP
647 See \fBattributes\fR(5) for descriptions of the following attributes:
648 .sp
650 .sp
651 .TS
652 box;
653 c | c
654 l | l .
655 ATTRIBUTE TYPE ATTRIBUTE VALUE
656 _
657 Interface Stability Committed
658 MT-Level Safe
659 _
660 Standard T{
661 ANSI INCITS 412 Multipath Management API (except for \fBSun_MP_SendScsiCmd\fR)
662 T}
663 .TE
665 .SH SEE ALSO
666 .sp
667 .LP
668 \fBIntro\fR(3), \fBMP_RegisterPlugin\fR(3MPAPI), \fBattributes\fR(5)
669 .sp
670 .LP
671 \fIMultipath Management API Version 1.0\fR