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