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