multipath-tools: Introducing multipath C API
[multipath-tools/.git] / libdmmp / docs / libdmmp.h.3
1 .TH "libdmmp.h" 3 "January 2016" "Device Mapper Multipath API - libdmmp Manual"
2
3 .SH NAME
4 libdmmp.h \- Device Mapper Multipath API.
5
6 .SH SYNOPSIS
7 #include <libdmmp/libdmmp.h>
8
9 .SH "DESCRIPTION"
10
11 All the libdmmp public functions ships its own man pages.
12 Use 'man 3 <function_name>' to check the detail usage.
13
14 .SH "USAGE"
15
16 To use libdmmp in your project, we suggest to use the 'pkg-config' way:
17
18  * Add this line into your configure.ac:
19
20     PKG_CHECK_MODULES([LIBDMMP], [libdmmp])
21
22  * Add these lines into your Makefile.am:
23
24     foo_LDFLAGS += $(LIBDMMP_LIBS)
25     foo_CFLAGS += $(LIBDMMP_CFLAGS)
26
27 .SH LOG HANDLING
28
29 The log handler function could be set via 'dmmp_context_log_func_set()'.
30 The log priority could be set via 'dmmp_context_log_priority_set()'.
31
32 By default, the log priorities is 'DMMP_LOG_PRIORITY_WARNING'.
33 By default, the log handler is print log to STDERR, and its code is listed
34 below in case you want to create your own log handler.
35
36         static int _DMMP_LOG_STRERR_ALIGN_WIDTH = 80;
37
38         static void _log_stderr(struct dmmp_context *ctx,
39                                 enum dmmp_log_priority priority,
40                                 const char *file, int line,
41                                 const char *func_name,
42                                 const char *format, va_list args)
43         {
44             int printed_bytes = 0;
45
46             printed_bytes += fprintf(stderr, "libdmmp %s: ",
47                                      dmmp_log_priority_str(priority));
48             printed_bytes += vfprintf(stderr, format, args);
49             userdata = dmmp_context_userdata_get(ctx);
50             if (userdata != NULL)
51                 fprintf(stderr, "(with user data at memory address %p)",
52                         userdata);
53
54             if (printed_bytes < _DMMP_LOG_STRERR_ALIGN_WIDTH) {
55                 fprintf(stderr, "%*s # %s:%s():%d\n",
56                         _DMMP_LOG_STRERR_ALIGN_WIDTH - printed_bytes, "", file,
57                         func_name, line);
58             } else {
59                 fprintf(stderr, " # %s:%s():%d\n", file, func_name, line);
60             }
61         }
62
63
64 .SH "SAMPLE CODE"
65
66     #include <libdmmp/libdmmp.h>
67
68     int main(int argc, char *argv[]) {
69         struct dmmp_context *ctx = NULL;
70         struct dmmp_mpath **dmmp_mps = NULL;
71         struct dmmp_path_group **dmmp_pgs = NULL;
72         struct dmmp_path **dmmp_ps = NULL;
73         uint32_t dmmp_mp_count = 0;
74         uint32_t dmmp_pg_count = 0;
75         uint32_t dmmp_p_count = 0;
76         const char *name = NULL;
77         const char *wwid = NULL;
78         uint32_t i = 0;
79         int rc = DMMP_OK;
80
81         ctx = dmmp_context_new();
82         dmmp_context_log_priority_set(ctx, DMMP_LOG_PRIORITY_DEBUG);
83         // By default, log will be printed to STDERR, you could
84         // change that via dmmp_context_log_func_set()
85         rc = dmmp_mpath_array_get(ctx, &dmmp_mps, &dmmp_mp_count);
86         if (rc != DMMP_OK) {
87             printf("dmmp_mpath_array_get() failed with %d: %s", rc,
88                    dmmp_strerror(rc));
89             goto out;
90         }
91         for (i = 0; i < dmmp_mp_count; ++i) {
92                 name = dmmp_mpath_name_get(dmmp_mps[i]);
93                 wwid = dmmp_mpath_wwid_get(dmmp_mps[i]);
94                 printf("dmmp_mpath_array_get(): Got mpath: %s %s\n", name,
95                        wwid);
96                 // You could use dmmp_path_group_array_get() to retrieve
97                 // path group information and then invoke dmmp_path_array_get()
98                 // for path information.
99         }
100
101      out:
102         dmmp_context_free(ctx);
103         dmmp_mpath_array_free(dmmp_mps, dmmp_mp_count);
104         if (rc != DMMP_OK)
105             exit(1);
106         exit(0);
107     }
108
109 .SH "LICENSE"
110 GPLv2+
111
112 .SH "BUG"
113 Please report bug to <dm-devel@redhat.com>