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