e157982eee6a55bf830c3b23d0494ed2ec531b6c
[multipath-tools/.git] / libdmmp / libdmmp / libdmmp.h
1 /*
2  * Copyright (C) 2015 - 2017 Red Hat, Inc.
3  *
4  * This program is free software: you can redistribute it and/or modify
5  * it under the terms of the GNU General Public License as published by
6  * the Free Software Foundation, either version 3 of the License, or
7  * (at your option) any later version.
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
16  *
17  * Author: Gris Ge <fge@redhat.com>
18  *         Todd Gill <tgill@redhat.com>
19  */
20
21
22 #ifndef _LIB_DMMP_H_
23 #define _LIB_DMMP_H_
24
25 #include <stdint.h>
26 #include <stdarg.h>
27
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31
32 #define DMMP_DLL_EXPORT         __attribute__ ((visibility ("default")))
33 #define DMMP_DLL_LOCAL          __attribute__ ((visibility ("hidden")))
34
35 #define DMMP_OK                         0
36 #define DMMP_ERR_BUG                    1
37 #define DMMP_ERR_NO_MEMORY              2
38 #define DMMP_ERR_IPC_TIMEOUT            3
39 #define DMMP_ERR_IPC_ERROR              4
40 #define DMMP_ERR_NO_DAEMON              5
41 #define DMMP_ERR_INCOMPATIBLE           6
42 #define DMMP_ERR_MPATH_BUSY             7
43 #define DMMP_ERR_MPATH_NOT_FOUND        8
44 #define DMMP_ERR_INVALID_ARGUMENT       9
45 #define DMMP_ERR_PERMISSION_DENY        10
46
47 /*
48  * Use the syslog severity level as log priority
49  */
50 #define DMMP_LOG_PRIORITY_ERROR         3
51 #define DMMP_LOG_PRIORITY_WARNING       4
52 #define DMMP_LOG_PRIORITY_INFO          6
53 #define DMMP_LOG_PRIORITY_DEBUG         7
54
55 #define DMMP_LOG_PRIORITY_DEFAULT       DMMP_LOG_PRIORITY_WARNING
56
57 /**
58  * dmmp_log_priority_str() - Convert log priority to string.
59  *
60  * Convert log priority to string (const char *).
61  *
62  * @priority:
63  *      int. Log priority.
64  *
65  * Return:
66  *      const char *. Valid string are:
67  *
68  *      * "ERROR" for DMMP_LOG_PRIORITY_ERROR
69  *
70  *      * "WARN " for DMMP_LOG_PRIORITY_WARNING
71  *
72  *      * "INFO " for DMMP_LOG_PRIORITY_INFO
73  *
74  *      * "DEBUG" for DMMP_LOG_PRIORITY_DEBUG
75  *
76  *      * "Invalid argument" for invalid log priority.
77  */
78 DMMP_DLL_EXPORT const char *dmmp_log_priority_str(int priority);
79
80 struct DMMP_DLL_EXPORT dmmp_context;
81
82 struct DMMP_DLL_EXPORT dmmp_mpath;
83
84 struct DMMP_DLL_EXPORT dmmp_path_group;
85
86 #define DMMP_PATH_GROUP_STATUS_UNKNOWN  0
87 #define DMMP_PATH_GROUP_STATUS_ENABLED  1
88 #define DMMP_PATH_GROUP_STATUS_DISABLED 2
89 #define DMMP_PATH_GROUP_STATUS_ACTIVE   3
90
91 struct DMMP_DLL_EXPORT dmmp_path;
92
93 #define DMMP_PATH_STATUS_UNKNOWN        0
94 //#define DMMP_PATH_STATUS_UNCHECKED    1
95 // ^ print.h does not expose this.
96 #define DMMP_PATH_STATUS_DOWN           2
97 #define DMMP_PATH_STATUS_UP             3
98 #define DMMP_PATH_STATUS_SHAKY          4
99 #define DMMP_PATH_STATUS_GHOST          5
100 #define DMMP_PATH_STATUS_PENDING        6
101 #define DMMP_PATH_STATUS_TIMEOUT        7
102 //#define DMMP_PATH_STATUS_REMOVED      8
103 // ^ print.h does not expose this.
104 #define DMMP_PATH_STATUS_DELAYED        9
105
106 /**
107  * dmmp_strerror() - Convert error code to string.
108  *
109  * Convert error code (int) to string (const char *):
110  *
111  *      * DMMP_OK -- "OK"
112  *
113  *      * DMMP_ERR_BUG -- "BUG of libdmmp library"
114  *
115  *      * DMMP_ERR_NO_MEMORY -- "Out of memory"
116  *
117  *      * DMMP_ERR_IPC_TIMEOUT -- "Timeout when communicate with multipathd,
118  *        try to set bigger timeout value via dmmp_context_timeout_set ()"
119  *
120  *      * DMMP_ERR_IPC_ERROR -- "Error when communicate with multipathd daemon"
121  *
122  *      * DMMP_ERR_NO_DAEMON -- "The multipathd daemon not started"
123  *
124  *      * DMMP_ERR_INCOMPATIBLE -- "The multipathd daemon version is not
125  *        compatible with current library"
126  *
127  *      * Other invalid error number -- "Invalid argument"
128  *
129  * @rc:
130  *      int. Return code by libdmmp functions. When provided error code is not a
131  *      valid error code, return "Invalid argument".
132  *
133  * Return:
134  *      const char *. The meaning of provided error code.
135  *
136  */
137 DMMP_DLL_EXPORT const char *dmmp_strerror(int rc);
138
139 /**
140  * dmmp_context_new() - Create struct dmmp_context.
141  *
142  * The default logging level (DMMP_LOG_PRIORITY_DEFAULT) is
143  * DMMP_LOG_PRIORITY_WARNING which means only warning and error message will be
144  * forward to log handler function.  The default log handler function will print
145  * log message to STDERR, to change so, please use dmmp_context_log_func_set()
146  * to set your own log handler, check manpage libdmmp.h(3) for detail.
147  *
148  * Return:
149  *      Pointer of 'struct dmmp_context'. Should be freed by
150  *      dmmp_context_free().
151  */
152 DMMP_DLL_EXPORT struct dmmp_context *dmmp_context_new(void);
153
154 /**
155  * dmmp_context_free() - Release the memory of struct dmmp_context.
156  *
157  * Release the memory of struct dmmp_context, but the userdata memory defined
158  * via dmmp_context_userdata_set() will not be touched.
159  *
160  * @ctx:
161  *      Pointer of 'struct dmmp_context'.
162  * Return:
163  *      void
164  */
165 DMMP_DLL_EXPORT void dmmp_context_free(struct dmmp_context *ctx);
166
167 /**
168  * dmmp_context_timeout_set() - Set IPC timeout.
169  *
170  * By default, the IPC to multipathd daemon will timeout after 60 seconds.
171  *
172  * @ctx:
173  *      Pointer of 'struct dmmp_context'.
174  *      If this pointer is NULL, your program will be terminated by assert.
175  *
176  * @tmo:
177  *      Timeout in milliseconds(1 seconds equal 1000 milliseconds).
178  *      0 means infinite, function only return when error or pass.
179  *
180  * Return:
181  *      void
182  */
183 DMMP_DLL_EXPORT void dmmp_context_timeout_set(struct dmmp_context *ctx,
184                                               unsigned int tmo);
185
186 /**
187  * dmmp_context_timeout_get() - Get IPC timeout.
188  *
189  * Retrieve timeout value of IPC connection to multipathd daemon.
190  *
191  * @ctx:
192  *      Pointer of 'struct dmmp_context'.
193  *      If this pointer is NULL, your program will be terminated by assert.
194  *
195  * Return:
196  *      unsigned int. Timeout in milliseconds.
197  */
198 DMMP_DLL_EXPORT unsigned int dmmp_context_timeout_get(struct dmmp_context *ctx);
199
200 /**
201  * dmmp_context_log_priority_set() - Set log priority.
202  *
203  *
204  * When library generates log message, only equal or more important(less value)
205  * message will be forwarded to log handler function. Valid log priority values
206  * are:
207  *
208  *      * DMMP_LOG_PRIORITY_ERROR -- 3
209  *
210  *      * DMMP_LOG_PRIORITY_WARNING -- 4
211  *
212  *      * DMMP_LOG_PRIORITY_INFO -- 5
213  *
214  *      * DMMP_LOG_PRIORITY_DEBUG -- 7
215  *
216  * @ctx:
217  *      Pointer of 'struct dmmp_context'.
218  *      If this pointer is NULL, your program will be terminated by assert.
219  *
220  * @priority:
221  *      int, log priority.
222  *
223  * Return:
224  *      void
225  */
226 DMMP_DLL_EXPORT void dmmp_context_log_priority_set(struct dmmp_context *ctx,
227                                                    int priority);
228
229 /**
230  * dmmp_context_log_priority_get() - Get log priority.
231  *
232  * Retrieve current log priority. Valid log priority values are:
233  *
234  *      * DMMP_LOG_PRIORITY_ERROR -- 3
235  *
236  *      * DMMP_LOG_PRIORITY_WARNING -- 4
237  *
238  *      * DMMP_LOG_PRIORITY_INFO -- 5
239  *
240  *      * DMMP_LOG_PRIORITY_DEBUG -- 7
241  *
242  * @ctx:
243  *      Pointer of 'struct dmmp_context'.
244  *      If this pointer is NULL, your program will be terminated by assert.
245  *
246  * Return:
247  *      int, log priority.
248  */
249 DMMP_DLL_EXPORT int dmmp_context_log_priority_get(struct dmmp_context *ctx);
250
251 /**
252  * dmmp_context_log_func_set() - Set log handler function.
253  *
254  * Set custom log handler. The log handler will be invoked when log message
255  * is equal or more important(less value) than log priority setting.
256  * Please check manpage libdmmp.h(3) for detail usage.
257  *
258  * @ctx:
259  *      Pointer of 'struct dmmp_context'.
260  *      If this pointer is NULL, your program will be terminated by assert.
261  * @log_func:
262  *      Pointer of log handler function. If set to NULL, all log will be
263  *      ignored.
264  *
265  * Return:
266  *      void
267  */
268 DMMP_DLL_EXPORT void dmmp_context_log_func_set
269         (struct dmmp_context *ctx,
270          void (*log_func)
271          (struct dmmp_context *ctx, int priority,
272           const char *file, int line, const char *func_name,
273           const char *format, va_list args));
274
275 /**
276  * dmmp_context_userdata_set() - Set user data pointer.
277  *
278  * Store user data pointer into 'struct dmmp_context'.
279  *
280  * @ctx:
281  *      Pointer of 'struct dmmp_context'.
282  *      If this pointer is NULL, your program will be terminated by assert.
283  * @userdata:
284  *      Pointer of user defined data.
285  *
286  * Return:
287  *      void
288  */
289 DMMP_DLL_EXPORT void dmmp_context_userdata_set(struct dmmp_context *ctx,
290                                                void *userdata);
291
292 /**
293  * dmmp_context_userdata_get() - Get user data pointer.
294  *
295  * Retrieve user data pointer from 'struct dmmp_context'.
296  *
297  * @ctx:
298  *      Pointer of 'struct dmmp_context'.
299  *      If this pointer is NULL, your program will be terminated by assert.
300  *
301  * Return:
302  *      void *. Pointer of user defined data.
303  */
304 DMMP_DLL_EXPORT void *dmmp_context_userdata_get(struct dmmp_context *ctx);
305
306 /**
307  * dmmp_mpath_array_get() - Query all existing multipath devices.
308  *
309  * Query all existing multipath devices and store them into a pointer array.
310  * The memory of 'dmmp_mps' should be freed via dmmp_mpath_array_free().
311  *
312  * @ctx:
313  *      Pointer of 'struct dmmp_context'.
314  *      If this pointer is NULL, your program will be terminated by assert.
315  * @dmmp_mps:
316  *      Output pointer array of 'struct dmmp_mpath'.
317  *      If this pointer is NULL, your program will be terminated by assert.
318  * @dmmp_mp_count:
319  *      Output pointer of uint32_t. Hold the size of 'dmmp_mps' pointer array.
320  *      If this pointer is NULL, your program will be terminated by assert.
321  *
322  * Return:
323  *      int. Valid error codes are:
324  *
325  *      * DMMP_OK
326  *
327  *      * DMMP_ERR_BUG
328  *
329  *      * DMMP_ERR_NO_MEMORY
330  *
331  *      * DMMP_ERR_NO_DAEMON
332  *
333  *      * DMMP_ERR_INCONSISTENT_DATA
334  *
335  *      Error number could be converted to string by dmmp_strerror().
336  */
337 DMMP_DLL_EXPORT int dmmp_mpath_array_get(struct dmmp_context *ctx,
338                                          struct dmmp_mpath ***dmmp_mps,
339                                          uint32_t *dmmp_mp_count);
340
341 /**
342  * dmmp_mpath_array_free() - Free 'struct dmmp_mpath' pointer array.
343  *
344  * Free the 'dmmp_mps' pointer array generated by dmmp_mpath_array_get().
345  * If provided 'dmmp_mps' pointer is NULL or dmmp_mp_count == 0, do nothing.
346  *
347  * @dmmp_mps:
348  *      Pointer of 'struct dmmp_mpath' array.
349  * @dmmp_mp_count:
350  *      uint32_t, the size of 'dmmp_mps' pointer array.
351  *
352  * Return:
353  *      void
354  */
355 DMMP_DLL_EXPORT void dmmp_mpath_array_free(struct dmmp_mpath **dmmp_mps,
356                                            uint32_t dmmp_mp_count);
357
358 /**
359  * dmmp_mpath_wwid_get() - Retrieve WWID of certain mpath.
360  *
361  * @dmmp_mp:
362  *      Pointer of 'struct dmmp_mpath'.
363  *      If this pointer is NULL, your program will be terminated by assert.
364  *
365  * Return:
366  *      const char *. No need to free this memory, the resources will get
367  *      freed when dmmp_mpath_array_free().
368  */
369 DMMP_DLL_EXPORT const char *dmmp_mpath_wwid_get(struct dmmp_mpath *dmmp_mp);
370
371 /**
372  * dmmp_mpath_name_get() - Retrieve name(alias) of certain mpath.
373  *
374  * Retrieve the name (also known as alias) of certain mpath.
375  * When the config 'user_friendly_names' been set 'no', the name will be
376  * identical to WWID retrieved by dmmp_mpath_wwid_get().
377  *
378  * @dmmp_mp:
379  *      Pointer of 'struct dmmp_mpath'.
380  *      If this pointer is NULL, your program will be terminated by assert.
381  *
382  * Return:
383  *      const char *. No need to free this memory, the resources will get
384  *      freed when dmmp_mpath_array_free().
385  */
386 DMMP_DLL_EXPORT const char *dmmp_mpath_name_get(struct dmmp_mpath *dmmp_mp);
387
388 /**
389  * dmmp_mpath_kdev_name_get() - Retrieve kernel DEVNAME of certain mpath.
390  *
391  * Retrieve DEVNAME name used by kernel uevent of specified mpath.
392  * Example: 'dm-1'.
393  *
394  * @dmmp_mp:
395  *      Pointer of 'struct dmmp_mpath'.
396  *      If this pointer is NULL, your program will be terminated by assert.
397  *
398  * Return:
399  *      const char *. No need to free this memory, the resources will get
400  *      freed when dmmp_mpath_array_free().
401  */
402 DMMP_DLL_EXPORT const char *dmmp_mpath_kdev_name_get
403         (struct dmmp_mpath *dmmp_mp);
404
405 /**
406  * dmmp_path_group_array_get() - Retrieve path groups pointer array.
407  *
408  * Retrieve the path groups of certain mpath.
409  *
410  * The memory of output pointer array is hold by 'struct dmmp_mpath', no
411  * need to free this memory, the resources will got freed when
412  * dmmp_mpath_array_free().
413  *
414  * @dmmp_mp:
415  *      Pointer of 'struct dmmp_mpath'.
416  *      If this pointer is NULL, your program will be terminated by assert.
417  * @dmmp_pgs:
418  *      Output pointer of 'struct dmmp_path_group' pointer array.
419  *      If this pointer is NULL, your program will be terminated by assert.
420  * @dmmp_pg_count:
421  *      Output pointer of uint32_t. Hold the size of 'dmmp_pgs' pointer array.
422  *      If this pointer is NULL, your program will be terminated by assert.
423  *
424  * Return:
425  *      void
426  */
427 DMMP_DLL_EXPORT void dmmp_path_group_array_get
428         (struct dmmp_mpath *dmmp_mp, struct dmmp_path_group ***dmmp_pgs,
429          uint32_t *dmmp_pg_count);
430
431 /**
432  * dmmp_path_group_id_get() - Retrieve path group ID.
433  *
434  * Retrieve the path group ID which could be used to switch active path group
435  * via command:
436  *
437  *      multipathd -k'switch multipath mpathb group $id'
438  *
439  * @dmmp_pg:
440  *      Pointer of 'struct dmmp_path_group'.
441  *      If this pointer is NULL, your program will be terminated by assert.
442  *
443  * Return:
444  *      uint32_t.
445  */
446 DMMP_DLL_EXPORT uint32_t dmmp_path_group_id_get
447         (struct dmmp_path_group *dmmp_pg);
448
449 /**
450  * dmmp_path_group_priority_get() - Retrieve path group priority.
451  *
452  * The enabled path group with highest priority will be next active path group
453  * if active path group down.
454  *
455  * @dmmp_pg:
456  *      Pointer of 'struct dmmp_path_group'.
457  *      If this pointer is NULL, your program will be terminated by assert.
458  *
459  * Return:
460  *      uint32_t.
461  */
462 DMMP_DLL_EXPORT uint32_t dmmp_path_group_priority_get
463         (struct dmmp_path_group *dmmp_pg);
464
465 /**
466  * dmmp_path_group_status_get() - Retrieve path group status.
467  *
468  * The valid path group statuses are:
469  *
470  *      * DMMP_PATH_GROUP_STATUS_UNKNOWN
471  *
472  *      * DMMP_PATH_GROUP_STATUS_ENABLED  -- standby to be active
473  *
474  *      * DMMP_PATH_GROUP_STATUS_DISABLED -- disabled due to all path down
475  *
476  *      * DMMP_PATH_GROUP_STATUS_ACTIVE -- selected to handle I/O
477  *
478  * @dmmp_pg:
479  *      Pointer of 'struct dmmp_path_group'.
480  *      If this pointer is NULL, your program will be terminated by assert.
481  *
482  * Return:
483  *      uint32_t.
484  */
485 DMMP_DLL_EXPORT uint32_t dmmp_path_group_status_get
486         (struct dmmp_path_group *dmmp_pg);
487
488 /**
489  * dmmp_path_group_status_str() - Convert path group status to string.
490  *
491  * Convert path group status uint32_t to string (const char *).
492  *
493  * @pg_status:
494  *      uint32_t. Path group status.
495  *      When provided value is not a valid path group status, return "Invalid
496  *      argument".
497  *
498  * Return:
499  *      const char *. Valid string are:
500  *
501  *              * "Invalid argument"
502  *
503  *              * "undef"
504  *
505  *              * "enabled"
506  *
507  *              * "disabled"
508  *
509  *              * "active"
510  */
511 DMMP_DLL_EXPORT const char *dmmp_path_group_status_str(uint32_t pg_status);
512
513 /**
514  * dmmp_path_group_selector_get() - Retrieve path group selector.
515  *
516  * Path group selector determine which path in active path group will be
517  * use to next I/O.
518  *
519  * @dmmp_pg:
520  *      Pointer of 'struct dmmp_path_group'.
521  *      If this pointer is NULL, your program will be terminated by assert.
522  *
523  * Return:
524  *      const char *.
525  */
526 DMMP_DLL_EXPORT const char *dmmp_path_group_selector_get
527         (struct dmmp_path_group *dmmp_pg);
528
529 /**
530  * dmmp_path_array_get() - Retrieve path pointer array.
531  *
532  * The memory of output pointer array is hold by 'struct dmmp_mpath', no
533  * need to free this memory, the resources will got freed when
534  * dmmp_mpath_array_free().
535  *
536  * @dmmp_pg:
537  *      Pointer of 'struct dmmp_path_group'.
538  *      If this pointer is NULL, your program will be terminated by assert.
539  * @dmmp_ps:
540  *      Output pointer of 'struct dmmp_path' pointer array.
541  *      If this pointer is NULL, your program will be terminated by assert.
542  * @dmmp_p_count:
543  *      Output pointer of uint32_t. Hold the size of 'dmmp_ps' pointer array.
544  *      If this pointer is NULL, your program will be terminated by assert.
545  *
546  * Return:
547  *      void
548  */
549 DMMP_DLL_EXPORT void dmmp_path_array_get(struct dmmp_path_group *dmmp_pg,
550                                          struct dmmp_path ***dmmp_ps,
551                                          uint32_t *dmmp_p_count);
552
553 /**
554  * dmmp_path_blk_name_get() - Retrieve block name.
555  *
556  * Retrieve block name of certain path. The example of block names are 'sda',
557  * 'nvme0n1'.
558  *
559  * @dmmp_p:
560  *      Pointer of 'struct dmmp_path'.
561  *      If this pointer is NULL, your program will be terminated by assert.
562  *
563  * Return:
564  *      const char *. No need to free this memory, the resources will get
565  *      freed when dmmp_mpath_array_free().
566  */
567 DMMP_DLL_EXPORT const char *dmmp_path_blk_name_get(struct dmmp_path *dmmp_p);
568
569 /**
570  * dmmp_path_status_get() - Retrieve the path status.
571  *
572  * The valid path statuses are:
573  *
574  *      * DMMP_PATH_STATUS_UNKNOWN
575  *
576  *      * DMMP_PATH_STATUS_DOWN
577  *
578  *      Path is down and you shouldn't try to send commands to it.
579  *
580  *      * DMMP_PATH_STATUS_UP
581  *
582  *      Path is up and I/O can be sent to it.
583  *
584  *      * DMMP_PATH_STATUS_SHAKY
585  *
586  *      Only emc_clariion checker when path not available for "normal"
587  *      operations.
588  *
589  *      * DMMP_PATH_STATUS_GHOST
590  *
591  *              Only hp_sw and rdac checkers.  Indicates a "passive/standby"
592  *              path on active/passive HP arrays. These paths will return valid
593  *              answers to certain SCSI commands (tur, read_capacity, inquiry,
594  *              start_stop), but will fail I/O commands.  The path needs an
595  *              initialization command to be sent to it in order for I/Os to
596  *              succeed.
597  *
598  *      * DMMP_PATH_STATUS_PENDING
599  *
600  *      Available for all async checkers when a check IO is in flight.
601  *
602  *      * DMMP_PATH_STATUS_TIMEOUT
603  *
604  *      Only tur checker when command timed out.
605  *
606  *      * DMMP_PATH_STATUS_DELAYED
607  *
608  *      If a path fails after being up for less than delay_watch_checks checks,
609  *      when it comes back up again, it will not be marked as up until it has
610  *      been up for delay_wait_checks checks. During this time, it is marked as
611  *      "delayed".
612  *
613  * @dmmp_p:
614  *      Pointer of 'struct dmmp_path'.
615  *      If this pointer is NULL, your program will be terminated by assert.
616  *
617  * Return:
618  *      uint32_t.
619  */
620 DMMP_DLL_EXPORT uint32_t dmmp_path_status_get(struct dmmp_path *dmmp_p);
621
622 /**
623  * dmmp_path_status_str() - Convert path status to string.
624  *
625  * Convert path status uint32_t to string (const char *):
626  *
627  *      * DMMP_PATH_STATUS_UNKNOWN -- "undef"
628  *
629  *      * DMMP_PATH_STATUS_DOWN -- "faulty"
630  *
631  *      * DMMP_PATH_STATUS_UP -- "ready"
632  *
633  *      * DMMP_PATH_STATUS_SHAKY -- "shaky"
634  *
635  *      * DMMP_PATH_STATUS_GHOST -- "ghost"
636  *
637  *      * DMMP_PATH_STATUS_PENDING -- "pending"
638  *
639  *      * DMMP_PATH_STATUS_TIMEOUT -- "timeout"
640  *
641  *      * DMMP_PATH_STATUS_REMOVED -- "removed"
642  *
643  *      * DMMP_PATH_STATUS_DELAYED -- "delayed"
644  *
645  * @path_status:
646  *      uint32_t. Path status.
647  *      When provided value is not a valid path status, return
648  *      "Invalid argument".
649  *
650  * Return:
651  *      const char *. The meaning of status value.
652  */
653 DMMP_DLL_EXPORT const char *dmmp_path_status_str(uint32_t path_status);
654
655 /**
656  * dmmp_flush_mpath() - Flush specified multipath device map if unused.
657  *
658  * Flush a multipath device map specified as parameter, if unused.
659  *
660  * @ctx:
661  *      Pointer of 'struct dmmp_context'.
662  *      If this pointer is NULL, your program will be terminated by assert.
663  * @mpath_name:
664  *      const char *. The name of multipath device map.
665  *
666  * Return:
667  *      int. Valid error codes are:
668  *
669  *      * DMMP_OK
670  *
671  *      * DMMP_ERR_BUG
672  *
673  *      * DMMP_ERR_NO_MEMORY
674  *
675  *      * DMMP_ERR_NO_DAEMON
676  *
677  *      * DMMP_ERR_MPATH_BUSY
678  *
679  *      * DMMP_ERR_MPATH_NOT_FOUND
680  *
681  *      * DMMP_ERR_INVALID_ARGUMENT
682  *
683  *      * DMMP_ERR_PERMISSION_DENY
684  *
685  *      Error number could be converted to string by dmmp_strerror().
686  */
687 DMMP_DLL_EXPORT int dmmp_flush_mpath(struct dmmp_context *ctx,
688                                      const char *mpath_name);
689
690 /**
691  * dmmp_reconfig() - Instruct multipathd daemon to do reconfiguration.
692  *
693  * Instruct multipathd daemon to do reconfiguration.
694  *
695  * @ctx:
696  *      Pointer of 'struct dmmp_context'.
697  *      If this pointer is NULL, your program will be terminated by assert.
698  *
699  * Return:
700  *      int. Valid error codes are:
701  *
702  *      * DMMP_OK
703  *
704  *      * DMMP_ERR_BUG
705  *
706  *      * DMMP_ERR_NO_MEMORY
707  *
708  *      * DMMP_ERR_NO_DAEMON
709  *
710  *      * DMMP_ERR_PERMISSION_DENY
711  *
712  *      Error number could be converted to string by dmmp_strerror().
713  */
714 DMMP_DLL_EXPORT int dmmp_reconfig(struct dmmp_context *ctx);
715
716 /**
717  * dmmp_last_error_msg() - Retrieves the last error message.
718  *
719  * Retrieves the last error message.
720  *
721  * @ctx:
722  *      Pointer of 'struct dmmp_context'.
723  *      If this pointer is NULL, your program will be terminated by assert.
724  *
725  * Return:
726  *      const char *. No need to free this memory, the resources will get
727  *      freed when dmmp_context_free().
728  */
729 DMMP_DLL_EXPORT const char *dmmp_last_error_msg(struct dmmp_context *ctx);
730
731 #ifdef __cplusplus
732 } /* End of extern "C" */
733 #endif
734
735 #endif /* End of _LIB_DMMP_H_ */