[dm-devel] [PATCH 4/7] libdmmp: allow building without perl
mwilck at suse.com
mwilck at suse.com
Fri Mar 26 21:29:41 UTC 2021
From: Martin Wilck <mwilck at suse.com>
Add the kernel-doc generated manpages of libdmmp to git, and
change the libdmmp Makefile to regenerate them (only) when
necessary.
This allows us to drop perl as a build-time requirement.
Signed-off-by: Martin Wilck <mwilck at suse.com>
---
libdmmp/Makefile | 37 ++++++-------
libdmmp/docs/man/dmmp_context_free.3 | 15 ++++++
libdmmp/docs/man/dmmp_context_log_func_set.3 | 21 ++++++++
.../docs/man/dmmp_context_log_priority_get.3 | 23 ++++++++
.../docs/man/dmmp_context_log_priority_set.3 | 29 ++++++++++
libdmmp/docs/man/dmmp_context_new.3 | 19 +++++++
libdmmp/docs/man/dmmp_context_timeout_get.3 | 15 ++++++
libdmmp/docs/man/dmmp_context_timeout_set.3 | 19 +++++++
libdmmp/docs/man/dmmp_context_userdata_get.3 | 15 ++++++
libdmmp/docs/man/dmmp_context_userdata_set.3 | 18 +++++++
libdmmp/docs/man/dmmp_flush_mpath.3 | 36 +++++++++++++
libdmmp/docs/man/dmmp_last_error_msg.3 | 16 ++++++
libdmmp/docs/man/dmmp_log_priority_str.3 | 24 +++++++++
libdmmp/docs/man/dmmp_mpath_array_free.3 | 18 +++++++
libdmmp/docs/man/dmmp_mpath_array_get.3 | 36 +++++++++++++
libdmmp/docs/man/dmmp_mpath_kdev_name_get.3 | 17 ++++++
libdmmp/docs/man/dmmp_mpath_name_get.3 | 18 +++++++
libdmmp/docs/man/dmmp_mpath_wwid_get.3 | 13 +++++
libdmmp/docs/man/dmmp_path_array_get.3 | 25 +++++++++
libdmmp/docs/man/dmmp_path_blk_name_get.3 | 17 ++++++
libdmmp/docs/man/dmmp_path_group_array_get.3 | 27 ++++++++++
libdmmp/docs/man/dmmp_path_group_id_get.3 | 18 +++++++
.../docs/man/dmmp_path_group_priority_get.3 | 16 ++++++
.../docs/man/dmmp_path_group_selector_get.3 | 16 ++++++
libdmmp/docs/man/dmmp_path_group_status_get.3 | 23 ++++++++
libdmmp/docs/man/dmmp_path_group_status_str.3 | 26 +++++++++
libdmmp/docs/man/dmmp_path_status_get.3 | 54 +++++++++++++++++++
libdmmp/docs/man/dmmp_path_status_str.3 | 34 ++++++++++++
libdmmp/docs/man/dmmp_reconfig.3 | 27 ++++++++++
libdmmp/docs/man/dmmp_strerror.3 | 33 ++++++++++++
libdmmp/docs/{ => man}/libdmmp.h.3 | 0
31 files changed, 683 insertions(+), 22 deletions(-)
create mode 100644 libdmmp/docs/man/dmmp_context_free.3
create mode 100644 libdmmp/docs/man/dmmp_context_log_func_set.3
create mode 100644 libdmmp/docs/man/dmmp_context_log_priority_get.3
create mode 100644 libdmmp/docs/man/dmmp_context_log_priority_set.3
create mode 100644 libdmmp/docs/man/dmmp_context_new.3
create mode 100644 libdmmp/docs/man/dmmp_context_timeout_get.3
create mode 100644 libdmmp/docs/man/dmmp_context_timeout_set.3
create mode 100644 libdmmp/docs/man/dmmp_context_userdata_get.3
create mode 100644 libdmmp/docs/man/dmmp_context_userdata_set.3
create mode 100644 libdmmp/docs/man/dmmp_flush_mpath.3
create mode 100644 libdmmp/docs/man/dmmp_last_error_msg.3
create mode 100644 libdmmp/docs/man/dmmp_log_priority_str.3
create mode 100644 libdmmp/docs/man/dmmp_mpath_array_free.3
create mode 100644 libdmmp/docs/man/dmmp_mpath_array_get.3
create mode 100644 libdmmp/docs/man/dmmp_mpath_kdev_name_get.3
create mode 100644 libdmmp/docs/man/dmmp_mpath_name_get.3
create mode 100644 libdmmp/docs/man/dmmp_mpath_wwid_get.3
create mode 100644 libdmmp/docs/man/dmmp_path_array_get.3
create mode 100644 libdmmp/docs/man/dmmp_path_blk_name_get.3
create mode 100644 libdmmp/docs/man/dmmp_path_group_array_get.3
create mode 100644 libdmmp/docs/man/dmmp_path_group_id_get.3
create mode 100644 libdmmp/docs/man/dmmp_path_group_priority_get.3
create mode 100644 libdmmp/docs/man/dmmp_path_group_selector_get.3
create mode 100644 libdmmp/docs/man/dmmp_path_group_status_get.3
create mode 100644 libdmmp/docs/man/dmmp_path_group_status_str.3
create mode 100644 libdmmp/docs/man/dmmp_path_status_get.3
create mode 100644 libdmmp/docs/man/dmmp_path_status_str.3
create mode 100644 libdmmp/docs/man/dmmp_reconfig.3
create mode 100644 libdmmp/docs/man/dmmp_strerror.3
rename libdmmp/docs/{ => man}/libdmmp.h.3 (100%)
diff --git a/libdmmp/Makefile b/libdmmp/Makefile
index 4175c3f..764a0bc 100644
--- a/libdmmp/Makefile
+++ b/libdmmp/Makefile
@@ -21,12 +21,13 @@ CFLAGS += $(LIB_CFLAGS) -fvisibility=hidden -I$(libdmmpdir) -I$(mpathcmddir) \
LIBDEPS += $(shell $(PKGCONFIG) --libs json-c) -L$(mpathcmddir) -lmpathcmd -lpthread
all: $(LIBS) doc
+.PHONY: doc doc.gz clean install uninstall check speed_test dep_clean
$(LIBS): $(OBJS)
$(CC) $(LDFLAGS) $(SHARED_FLAGS) -Wl,-soname=$@ -o $@ $(OBJS) $(LIBDEPS)
$(LN) $@ $(DEVLIB)
-install:
+install: doc.gz
mkdir -p $(DESTDIR)$(usrlibdir)
$(INSTALL_PROGRAM) -m 755 $(LIBS) $(DESTDIR)$(usrlibdir)/$(LIBS)
$(INSTALL_PROGRAM) -m 644 -D \
@@ -40,11 +41,7 @@ install:
$(DESTDIR)$(pkgconfdir)/$(PKGFILE)
perl -i -pe 's|__INCLUDEDIR__|$(includedir)|g' \
$(DESTDIR)$(pkgconfdir)/$(PKGFILE)
- @for file in docs/man/*.3.gz; do \
- $(INSTALL_PROGRAM) -m 644 -D \
- $$file \
- $(DESTDIR)$(man3dir)/ || exit $?; \
- done
+ $(INSTALL_PROGRAM) -m 644 -t $(DESTDIR)$(man3dir) docs/man/*.3.gz
uninstall:
$(RM) $(DESTDIR)$(usrlibdir)/$(LIBS)
@@ -58,7 +55,7 @@ uninstall:
clean: dep_clean
$(RM) core *.a *.o *.gz *.so *.so.*
- $(RM) -r docs/man
+ $(RM) docs/man/*.gz
$(MAKE) -C test clean
include $(wildcard $(OBJS:.o=.d))
@@ -69,23 +66,19 @@ check: all
speed_test: all
$(MAKE) -C test speed_test
-doc: docs/man/$(EXTRA_MAN_FILES).gz
+doc.gz: doc $(patsubst %,%.gz,$(wildcard docs/man/*.3))
-TEMPFILE := $(shell mktemp)
+doc: docs/man/dmmp_strerror.3
-docs/man/$(EXTRA_MAN_FILES).gz: $(HEADERS)
- @for file in $(EXTRA_MAN_FILES); do \
- $(INSTALL_PROGRAM) -v -m 644 -D docs/$$file docs/man/$$file; \
- done
- cat $(HEADERS) | \
- perl docs/doc-preclean.pl > "$(TEMPFILE)"
- perl docs/kernel-doc -man "$(TEMPFILE)" | \
- perl docs/split-man.pl docs/man
- -rm -f "$(TEMPFILE)"
- @for file in docs/man/*.3; do \
- gzip -f $$file; \
- done
- find docs/man -type f -name \*[0-9].gz
+docs/man/%.3.gz: docs/man/%.3
+ gzip -c $< >$@
+
+docs/man/dmmp_strerror.3: $(HEADERS)
+ TEMPFILE=$(shell mktemp); \
+ cat $^ | perl docs/doc-preclean.pl >$$TEMPFILE; \
+ perl docs/kernel-doc -man $$TEMPFILE | \
+ perl docs/split-man.pl docs/man; \
+ rm -f $$TEMPFILE
dep_clean:
$(RM) $(OBJS:.o=.d)
diff --git a/libdmmp/docs/man/dmmp_context_free.3 b/libdmmp/docs/man/dmmp_context_free.3
new file mode 100644
index 0000000..0d26f42
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_context_free.3
@@ -0,0 +1,15 @@
+.TH "dmmp_context_free" 3 "dmmp_context_free" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_context_free \- Release the memory of struct dmmp_context.
+.SH SYNOPSIS
+.B "void" dmmp_context_free
+.BI "(struct dmmp_context *" ctx ");"
+.SH ARGUMENTS
+.IP "ctx" 12
+Pointer of 'struct dmmp_context'.
+.SH "DESCRIPTION"
+
+Release the memory of struct dmmp_context, but the userdata memory defined
+via \fBdmmp_context_userdata_set\fP will not be touched.
+.SH "RETURN"
+void
diff --git a/libdmmp/docs/man/dmmp_context_log_func_set.3 b/libdmmp/docs/man/dmmp_context_log_func_set.3
new file mode 100644
index 0000000..986793d
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_context_log_func_set.3
@@ -0,0 +1,21 @@
+.TH "dmmp_context_log_func_set" 3 "dmmp_context_log_func_set" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_context_log_func_set \- Set log handler function.
+.SH SYNOPSIS
+.B "void" dmmp_context_log_func_set
+.BI "(struct dmmp_context *" ctx ","
+.BI "void (*" log_func ") (struct dmmp_context *ctx, int priority, const char *file, int line, const char *func_name, const char *format, va_list args));"
+.SH ARGUMENTS
+.IP "ctx" 12
+Pointer of 'struct dmmp_context'.
+If this pointer is NULL, your program will be terminated by assert.
+.IP "log_func" 12
+Pointer of log handler function. If set to NULL, all log will be
+ignored.
+.SH "DESCRIPTION"
+
+Set custom log handler. The log handler will be invoked when log message
+is equal or more important(less value) than log priority setting.
+Please check manpage libdmmp.h(3) for detail usage.
+.SH "RETURN"
+void
diff --git a/libdmmp/docs/man/dmmp_context_log_priority_get.3 b/libdmmp/docs/man/dmmp_context_log_priority_get.3
new file mode 100644
index 0000000..9a273a2
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_context_log_priority_get.3
@@ -0,0 +1,23 @@
+.TH "dmmp_context_log_priority_get" 3 "dmmp_context_log_priority_get" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_context_log_priority_get \- Get log priority.
+.SH SYNOPSIS
+.B "int" dmmp_context_log_priority_get
+.BI "(struct dmmp_context *" ctx ");"
+.SH ARGUMENTS
+.IP "ctx" 12
+Pointer of 'struct dmmp_context'.
+If this pointer is NULL, your program will be terminated by assert.
+.SH "DESCRIPTION"
+
+Retrieve current log priority. Valid log priority values are:
+
+* DMMP_LOG_PRIORITY_ERROR -- 3
+
+* DMMP_LOG_PRIORITY_WARNING -- 4
+
+* DMMP_LOG_PRIORITY_INFO -- 5
+
+* DMMP_LOG_PRIORITY_DEBUG -- 7
+.SH "RETURN"
+int, log priority.
diff --git a/libdmmp/docs/man/dmmp_context_log_priority_set.3 b/libdmmp/docs/man/dmmp_context_log_priority_set.3
new file mode 100644
index 0000000..469c5a4
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_context_log_priority_set.3
@@ -0,0 +1,29 @@
+.TH "dmmp_context_log_priority_set" 3 "dmmp_context_log_priority_set" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_context_log_priority_set \- Set log priority.
+.SH SYNOPSIS
+.B "void" dmmp_context_log_priority_set
+.BI "(struct dmmp_context *" ctx ","
+.BI "int " priority ");"
+.SH ARGUMENTS
+.IP "ctx" 12
+Pointer of 'struct dmmp_context'.
+If this pointer is NULL, your program will be terminated by assert.
+.IP "priority" 12
+int, log priority.
+.SH "DESCRIPTION"
+
+
+When library generates log message, only equal or more important(less value)
+message will be forwarded to log handler function. Valid log priority values
+are:
+
+* DMMP_LOG_PRIORITY_ERROR -- 3
+
+* DMMP_LOG_PRIORITY_WARNING -- 4
+
+* DMMP_LOG_PRIORITY_INFO -- 5
+
+* DMMP_LOG_PRIORITY_DEBUG -- 7
+.SH "RETURN"
+void
diff --git a/libdmmp/docs/man/dmmp_context_new.3 b/libdmmp/docs/man/dmmp_context_new.3
new file mode 100644
index 0000000..0eaeb00
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_context_new.3
@@ -0,0 +1,19 @@
+.TH "dmmp_context_new" 3 "dmmp_context_new" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_context_new \- Create struct dmmp_context.
+.SH SYNOPSIS
+.B "struct dmmp_context *" dmmp_context_new
+.BI "(" void ");"
+.SH ARGUMENTS
+.IP "void" 12
+no arguments
+.SH "DESCRIPTION"
+
+The default logging level (DMMP_LOG_PRIORITY_DEFAULT) is
+DMMP_LOG_PRIORITY_WARNING which means only warning and error message will be
+forward to log handler function. The default log handler function will print
+log message to STDERR, to change so, please use \fBdmmp_context_log_func_set\fP
+to set your own log handler, check manpage libdmmp.h(3) for detail.
+.SH "RETURN"
+Pointer of 'struct dmmp_context'. Should be freed by
+\fBdmmp_context_free\fP.
diff --git a/libdmmp/docs/man/dmmp_context_timeout_get.3 b/libdmmp/docs/man/dmmp_context_timeout_get.3
new file mode 100644
index 0000000..1df2793
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_context_timeout_get.3
@@ -0,0 +1,15 @@
+.TH "dmmp_context_timeout_get" 3 "dmmp_context_timeout_get" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_context_timeout_get \- Get IPC timeout.
+.SH SYNOPSIS
+.B "unsigned int" dmmp_context_timeout_get
+.BI "(struct dmmp_context *" ctx ");"
+.SH ARGUMENTS
+.IP "ctx" 12
+Pointer of 'struct dmmp_context'.
+If this pointer is NULL, your program will be terminated by assert.
+.SH "DESCRIPTION"
+
+Retrieve timeout value of IPC connection to multipathd daemon.
+.SH "RETURN"
+unsigned int. Timeout in milliseconds.
diff --git a/libdmmp/docs/man/dmmp_context_timeout_set.3 b/libdmmp/docs/man/dmmp_context_timeout_set.3
new file mode 100644
index 0000000..f3d7709
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_context_timeout_set.3
@@ -0,0 +1,19 @@
+.TH "dmmp_context_timeout_set" 3 "dmmp_context_timeout_set" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_context_timeout_set \- Set IPC timeout.
+.SH SYNOPSIS
+.B "void" dmmp_context_timeout_set
+.BI "(struct dmmp_context *" ctx ","
+.BI "unsigned int " tmo ");"
+.SH ARGUMENTS
+.IP "ctx" 12
+Pointer of 'struct dmmp_context'.
+If this pointer is NULL, your program will be terminated by assert.
+.IP "tmo" 12
+Timeout in milliseconds(1 seconds equal 1000 milliseconds).
+0 means infinite, function only return when error or pass.
+.SH "DESCRIPTION"
+
+By default, the IPC to multipathd daemon will timeout after 60 seconds.
+.SH "RETURN"
+void
diff --git a/libdmmp/docs/man/dmmp_context_userdata_get.3 b/libdmmp/docs/man/dmmp_context_userdata_get.3
new file mode 100644
index 0000000..fb713d5
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_context_userdata_get.3
@@ -0,0 +1,15 @@
+.TH "dmmp_context_userdata_get" 3 "dmmp_context_userdata_get" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_context_userdata_get \- Get user data pointer.
+.SH SYNOPSIS
+.B "void *" dmmp_context_userdata_get
+.BI "(struct dmmp_context *" ctx ");"
+.SH ARGUMENTS
+.IP "ctx" 12
+Pointer of 'struct dmmp_context'.
+If this pointer is NULL, your program will be terminated by assert.
+.SH "DESCRIPTION"
+
+Retrieve user data pointer from 'struct dmmp_context'.
+.SH "RETURN"
+void *. Pointer of user defined data.
diff --git a/libdmmp/docs/man/dmmp_context_userdata_set.3 b/libdmmp/docs/man/dmmp_context_userdata_set.3
new file mode 100644
index 0000000..c5bf63f
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_context_userdata_set.3
@@ -0,0 +1,18 @@
+.TH "dmmp_context_userdata_set" 3 "dmmp_context_userdata_set" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_context_userdata_set \- Set user data pointer.
+.SH SYNOPSIS
+.B "void" dmmp_context_userdata_set
+.BI "(struct dmmp_context *" ctx ","
+.BI "void *" userdata ");"
+.SH ARGUMENTS
+.IP "ctx" 12
+Pointer of 'struct dmmp_context'.
+If this pointer is NULL, your program will be terminated by assert.
+.IP "userdata" 12
+Pointer of user defined data.
+.SH "DESCRIPTION"
+
+Store user data pointer into 'struct dmmp_context'.
+.SH "RETURN"
+void
diff --git a/libdmmp/docs/man/dmmp_flush_mpath.3 b/libdmmp/docs/man/dmmp_flush_mpath.3
new file mode 100644
index 0000000..cdfd526
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_flush_mpath.3
@@ -0,0 +1,36 @@
+.TH "dmmp_flush_mpath" 3 "dmmp_flush_mpath" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_flush_mpath \- Flush specified multipath device map if unused.
+.SH SYNOPSIS
+.B "int" dmmp_flush_mpath
+.BI "(struct dmmp_context *" ctx ","
+.BI "const char *" mpath_name ");"
+.SH ARGUMENTS
+.IP "ctx" 12
+Pointer of 'struct dmmp_context'.
+If this pointer is NULL, your program will be terminated by assert.
+.IP "mpath_name" 12
+const char *. The name of multipath device map.
+.SH "DESCRIPTION"
+
+Flush a multipath device map specified as parameter, if unused.
+.SH "RETURN"
+int. Valid error codes are:
+
+* DMMP_OK
+
+* DMMP_ERR_BUG
+
+* DMMP_ERR_NO_MEMORY
+
+* DMMP_ERR_NO_DAEMON
+
+* DMMP_ERR_MPATH_BUSY
+
+* DMMP_ERR_MPATH_NOT_FOUND
+
+* DMMP_ERR_INVALID_ARGUMENT
+
+* DMMP_ERR_PERMISSION_DENY
+
+Error number could be converted to string by \fBdmmp_strerror\fP.
diff --git a/libdmmp/docs/man/dmmp_last_error_msg.3 b/libdmmp/docs/man/dmmp_last_error_msg.3
new file mode 100644
index 0000000..20acbc6
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_last_error_msg.3
@@ -0,0 +1,16 @@
+.TH "dmmp_last_error_msg" 3 "dmmp_last_error_msg" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_last_error_msg \- Retrieves the last error message.
+.SH SYNOPSIS
+.B "const char *" dmmp_last_error_msg
+.BI "(struct dmmp_context *" ctx ");"
+.SH ARGUMENTS
+.IP "ctx" 12
+Pointer of 'struct dmmp_context'.
+If this pointer is NULL, your program will be terminated by assert.
+.SH "DESCRIPTION"
+
+Retrieves the last error message.
+.SH "RETURN"
+const char *. No need to free this memory, the resources will get
+freed when \fBdmmp_context_free\fP.
diff --git a/libdmmp/docs/man/dmmp_log_priority_str.3 b/libdmmp/docs/man/dmmp_log_priority_str.3
new file mode 100644
index 0000000..3b5f828
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_log_priority_str.3
@@ -0,0 +1,24 @@
+.TH "dmmp_log_priority_str" 3 "dmmp_log_priority_str" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_log_priority_str \- Convert log priority to string.
+.SH SYNOPSIS
+.B "const char *" dmmp_log_priority_str
+.BI "(int " priority ");"
+.SH ARGUMENTS
+.IP "priority" 12
+int. Log priority.
+.SH "DESCRIPTION"
+
+Convert log priority to string (const char *).
+.SH "RETURN"
+const char *. Valid string are:
+
+* "ERROR" for DMMP_LOG_PRIORITY_ERROR
+
+* "WARN " for DMMP_LOG_PRIORITY_WARNING
+
+* "INFO " for DMMP_LOG_PRIORITY_INFO
+
+* "DEBUG" for DMMP_LOG_PRIORITY_DEBUG
+
+* "Invalid argument" for invalid log priority.
diff --git a/libdmmp/docs/man/dmmp_mpath_array_free.3 b/libdmmp/docs/man/dmmp_mpath_array_free.3
new file mode 100644
index 0000000..8c294e0
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_mpath_array_free.3
@@ -0,0 +1,18 @@
+.TH "dmmp_mpath_array_free" 3 "dmmp_mpath_array_free" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_mpath_array_free \- Free 'struct dmmp_mpath' pointer array.
+.SH SYNOPSIS
+.B "void" dmmp_mpath_array_free
+.BI "(struct dmmp_mpath **" dmmp_mps ","
+.BI "uint32_t " dmmp_mp_count ");"
+.SH ARGUMENTS
+.IP "dmmp_mps" 12
+Pointer of 'struct dmmp_mpath' array.
+.IP "dmmp_mp_count" 12
+uint32_t, the size of 'dmmp_mps' pointer array.
+.SH "DESCRIPTION"
+
+Free the 'dmmp_mps' pointer array generated by \fBdmmp_mpath_array_get\fP.
+If provided 'dmmp_mps' pointer is NULL or dmmp_mp_count == 0, do nothing.
+.SH "RETURN"
+void
diff --git a/libdmmp/docs/man/dmmp_mpath_array_get.3 b/libdmmp/docs/man/dmmp_mpath_array_get.3
new file mode 100644
index 0000000..e211db4
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_mpath_array_get.3
@@ -0,0 +1,36 @@
+.TH "dmmp_mpath_array_get" 3 "dmmp_mpath_array_get" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_mpath_array_get \- Query all existing multipath devices.
+.SH SYNOPSIS
+.B "int" dmmp_mpath_array_get
+.BI "(struct dmmp_context *" ctx ","
+.BI "struct dmmp_mpath ***" dmmp_mps ","
+.BI "uint32_t *" dmmp_mp_count ");"
+.SH ARGUMENTS
+.IP "ctx" 12
+Pointer of 'struct dmmp_context'.
+If this pointer is NULL, your program will be terminated by assert.
+.IP "dmmp_mps" 12
+Output pointer array of 'struct dmmp_mpath'.
+If this pointer is NULL, your program will be terminated by assert.
+.IP "dmmp_mp_count" 12
+Output pointer of uint32_t. Hold the size of 'dmmp_mps' pointer array.
+If this pointer is NULL, your program will be terminated by assert.
+.SH "DESCRIPTION"
+
+Query all existing multipath devices and store them into a pointer array.
+The memory of 'dmmp_mps' should be freed via \fBdmmp_mpath_array_free\fP.
+.SH "RETURN"
+int. Valid error codes are:
+
+* DMMP_OK
+
+* DMMP_ERR_BUG
+
+* DMMP_ERR_NO_MEMORY
+
+* DMMP_ERR_NO_DAEMON
+
+* DMMP_ERR_INCONSISTENT_DATA
+
+Error number could be converted to string by \fBdmmp_strerror\fP.
diff --git a/libdmmp/docs/man/dmmp_mpath_kdev_name_get.3 b/libdmmp/docs/man/dmmp_mpath_kdev_name_get.3
new file mode 100644
index 0000000..e802fe6
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_mpath_kdev_name_get.3
@@ -0,0 +1,17 @@
+.TH "dmmp_mpath_kdev_name_get" 3 "dmmp_mpath_kdev_name_get" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_mpath_kdev_name_get \- Retrieve kernel DEVNAME of certain mpath.
+.SH SYNOPSIS
+.B "const char *" dmmp_mpath_kdev_name_get
+.BI "(struct dmmp_mpath *" dmmp_mp ");"
+.SH ARGUMENTS
+.IP "dmmp_mp" 12
+Pointer of 'struct dmmp_mpath'.
+If this pointer is NULL, your program will be terminated by assert.
+.SH "DESCRIPTION"
+
+Retrieve DEVNAME name used by kernel uevent of specified mpath.
+For example: 'dm-1'.
+.SH "RETURN"
+const char *. No need to free this memory, the resources will get
+freed when \fBdmmp_mpath_array_free\fP.
diff --git a/libdmmp/docs/man/dmmp_mpath_name_get.3 b/libdmmp/docs/man/dmmp_mpath_name_get.3
new file mode 100644
index 0000000..d70579e
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_mpath_name_get.3
@@ -0,0 +1,18 @@
+.TH "dmmp_mpath_name_get" 3 "dmmp_mpath_name_get" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_mpath_name_get \- Retrieve name(alias) of certain mpath.
+.SH SYNOPSIS
+.B "const char *" dmmp_mpath_name_get
+.BI "(struct dmmp_mpath *" dmmp_mp ");"
+.SH ARGUMENTS
+.IP "dmmp_mp" 12
+Pointer of 'struct dmmp_mpath'.
+If this pointer is NULL, your program will be terminated by assert.
+.SH "DESCRIPTION"
+
+Retrieve the name (also known as alias) of certain mpath.
+When the config 'user_friendly_names' been set 'no', the name will be
+identical to WWID retrieved by \fBdmmp_mpath_wwid_get\fP.
+.SH "RETURN"
+const char *. No need to free this memory, the resources will get
+freed when \fBdmmp_mpath_array_free\fP.
diff --git a/libdmmp/docs/man/dmmp_mpath_wwid_get.3 b/libdmmp/docs/man/dmmp_mpath_wwid_get.3
new file mode 100644
index 0000000..3d060e9
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_mpath_wwid_get.3
@@ -0,0 +1,13 @@
+.TH "dmmp_mpath_wwid_get" 3 "dmmp_mpath_wwid_get" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_mpath_wwid_get \- Retrieve WWID of certain mpath.
+.SH SYNOPSIS
+.B "const char *" dmmp_mpath_wwid_get
+.BI "(struct dmmp_mpath *" dmmp_mp ");"
+.SH ARGUMENTS
+.IP "dmmp_mp" 12
+Pointer of 'struct dmmp_mpath'.
+If this pointer is NULL, your program will be terminated by assert.
+.SH "RETURN"
+const char *. No need to free this memory, the resources will get
+freed when \fBdmmp_mpath_array_free\fP.
diff --git a/libdmmp/docs/man/dmmp_path_array_get.3 b/libdmmp/docs/man/dmmp_path_array_get.3
new file mode 100644
index 0000000..53340b3
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_path_array_get.3
@@ -0,0 +1,25 @@
+.TH "dmmp_path_array_get" 3 "dmmp_path_array_get" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_path_array_get \- Retrieve path pointer array.
+.SH SYNOPSIS
+.B "void" dmmp_path_array_get
+.BI "(struct dmmp_path_group *" dmmp_pg ","
+.BI "struct dmmp_path ***" dmmp_ps ","
+.BI "uint32_t *" dmmp_p_count ");"
+.SH ARGUMENTS
+.IP "dmmp_pg" 12
+Pointer of 'struct dmmp_path_group'.
+If this pointer is NULL, your program will be terminated by assert.
+.IP "dmmp_ps" 12
+Output pointer of 'struct dmmp_path' pointer array.
+If this pointer is NULL, your program will be terminated by assert.
+.IP "dmmp_p_count" 12
+Output pointer of uint32_t. Hold the size of 'dmmp_ps' pointer array.
+If this pointer is NULL, your program will be terminated by assert.
+.SH "DESCRIPTION"
+
+The memory of output pointer array is hold by 'struct dmmp_mpath', no
+need to free this memory, the resources will got freed when
+\fBdmmp_mpath_array_free\fP.
+.SH "RETURN"
+void
diff --git a/libdmmp/docs/man/dmmp_path_blk_name_get.3 b/libdmmp/docs/man/dmmp_path_blk_name_get.3
new file mode 100644
index 0000000..da5f9f0
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_path_blk_name_get.3
@@ -0,0 +1,17 @@
+.TH "dmmp_path_blk_name_get" 3 "dmmp_path_blk_name_get" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_path_blk_name_get \- Retrieve block name.
+.SH SYNOPSIS
+.B "const char *" dmmp_path_blk_name_get
+.BI "(struct dmmp_path *" dmmp_p ");"
+.SH ARGUMENTS
+.IP "dmmp_p" 12
+Pointer of 'struct dmmp_path'.
+If this pointer is NULL, your program will be terminated by assert.
+.SH "DESCRIPTION"
+
+Retrieve block name of certain path. The example of block names are "sda",
+"nvme0n1".
+.SH "RETURN"
+const char *. No need to free this memory, the resources will get
+freed when \fBdmmp_mpath_array_free\fP.
diff --git a/libdmmp/docs/man/dmmp_path_group_array_get.3 b/libdmmp/docs/man/dmmp_path_group_array_get.3
new file mode 100644
index 0000000..6eee4a2
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_path_group_array_get.3
@@ -0,0 +1,27 @@
+.TH "dmmp_path_group_array_get" 3 "dmmp_path_group_array_get" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_path_group_array_get \- Retrieve path groups pointer array.
+.SH SYNOPSIS
+.B "void" dmmp_path_group_array_get
+.BI "(struct dmmp_mpath *" dmmp_mp ","
+.BI "struct dmmp_path_group ***" dmmp_pgs ","
+.BI "uint32_t *" dmmp_pg_count ");"
+.SH ARGUMENTS
+.IP "dmmp_mp" 12
+Pointer of 'struct dmmp_mpath'.
+If this pointer is NULL, your program will be terminated by assert.
+.IP "dmmp_pgs" 12
+Output pointer of 'struct dmmp_path_group' pointer array.
+If this pointer is NULL, your program will be terminated by assert.
+.IP "dmmp_pg_count" 12
+Output pointer of uint32_t. Hold the size of 'dmmp_pgs' pointer array.
+If this pointer is NULL, your program will be terminated by assert.
+.SH "DESCRIPTION"
+
+Retrieve the path groups of certain mpath.
+
+The memory of output pointer array is hold by 'struct dmmp_mpath', no
+need to free this memory, the resources will got freed when
+\fBdmmp_mpath_array_free\fP.
+.SH "RETURN"
+void
diff --git a/libdmmp/docs/man/dmmp_path_group_id_get.3 b/libdmmp/docs/man/dmmp_path_group_id_get.3
new file mode 100644
index 0000000..4f07b53
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_path_group_id_get.3
@@ -0,0 +1,18 @@
+.TH "dmmp_path_group_id_get" 3 "dmmp_path_group_id_get" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_path_group_id_get \- Retrieve path group ID.
+.SH SYNOPSIS
+.B "uint32_t" dmmp_path_group_id_get
+.BI "(struct dmmp_path_group *" dmmp_pg ");"
+.SH ARGUMENTS
+.IP "dmmp_pg" 12
+Pointer of 'struct dmmp_path_group'.
+If this pointer is NULL, your program will be terminated by assert.
+.SH "DESCRIPTION"
+
+Retrieve the path group ID which could be used to switch active path group
+via command:
+
+multipathd -k'switch multipath mpathb group $id'
+.SH "RETURN"
+uint32_t.
diff --git a/libdmmp/docs/man/dmmp_path_group_priority_get.3 b/libdmmp/docs/man/dmmp_path_group_priority_get.3
new file mode 100644
index 0000000..a48b270
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_path_group_priority_get.3
@@ -0,0 +1,16 @@
+.TH "dmmp_path_group_priority_get" 3 "dmmp_path_group_priority_get" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_path_group_priority_get \- Retrieve path group priority.
+.SH SYNOPSIS
+.B "uint32_t" dmmp_path_group_priority_get
+.BI "(struct dmmp_path_group *" dmmp_pg ");"
+.SH ARGUMENTS
+.IP "dmmp_pg" 12
+Pointer of 'struct dmmp_path_group'.
+If this pointer is NULL, your program will be terminated by assert.
+.SH "DESCRIPTION"
+
+The enabled path group with highest priority will be next active path group
+if active path group down.
+.SH "RETURN"
+uint32_t.
diff --git a/libdmmp/docs/man/dmmp_path_group_selector_get.3 b/libdmmp/docs/man/dmmp_path_group_selector_get.3
new file mode 100644
index 0000000..407b3f4
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_path_group_selector_get.3
@@ -0,0 +1,16 @@
+.TH "dmmp_path_group_selector_get" 3 "dmmp_path_group_selector_get" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_path_group_selector_get \- Retrieve path group selector.
+.SH SYNOPSIS
+.B "const char *" dmmp_path_group_selector_get
+.BI "(struct dmmp_path_group *" dmmp_pg ");"
+.SH ARGUMENTS
+.IP "dmmp_pg" 12
+Pointer of 'struct dmmp_path_group'.
+If this pointer is NULL, your program will be terminated by assert.
+.SH "DESCRIPTION"
+
+Path group selector determine which path in active path group will be
+use to next I/O.
+.SH "RETURN"
+const char *.
diff --git a/libdmmp/docs/man/dmmp_path_group_status_get.3 b/libdmmp/docs/man/dmmp_path_group_status_get.3
new file mode 100644
index 0000000..a81aeb3
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_path_group_status_get.3
@@ -0,0 +1,23 @@
+.TH "dmmp_path_group_status_get" 3 "dmmp_path_group_status_get" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_path_group_status_get \- Retrieve path group status.
+.SH SYNOPSIS
+.B "uint32_t" dmmp_path_group_status_get
+.BI "(struct dmmp_path_group *" dmmp_pg ");"
+.SH ARGUMENTS
+.IP "dmmp_pg" 12
+Pointer of 'struct dmmp_path_group'.
+If this pointer is NULL, your program will be terminated by assert.
+.SH "DESCRIPTION"
+
+The valid path group statuses are:
+
+* DMMP_PATH_GROUP_STATUS_UNKNOWN
+
+* DMMP_PATH_GROUP_STATUS_ENABLED -- standby to be active
+
+* DMMP_PATH_GROUP_STATUS_DISABLED -- disabled due to all path down
+
+* DMMP_PATH_GROUP_STATUS_ACTIVE -- selected to handle I/O
+.SH "RETURN"
+uint32_t.
diff --git a/libdmmp/docs/man/dmmp_path_group_status_str.3 b/libdmmp/docs/man/dmmp_path_group_status_str.3
new file mode 100644
index 0000000..e4a9f74
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_path_group_status_str.3
@@ -0,0 +1,26 @@
+.TH "dmmp_path_group_status_str" 3 "dmmp_path_group_status_str" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_path_group_status_str \- Convert path group status to string.
+.SH SYNOPSIS
+.B "const char *" dmmp_path_group_status_str
+.BI "(uint32_t " pg_status ");"
+.SH ARGUMENTS
+.IP "pg_status" 12
+uint32_t. Path group status.
+When provided value is not a valid path group status, return "Invalid
+argument".
+.SH "DESCRIPTION"
+
+Convert path group status uint32_t to string (const char *).
+.SH "RETURN"
+const char *. Valid string are:
+
+* "Invalid argument"
+
+* "undef"
+
+* "enabled"
+
+* "disabled"
+
+* "active"
diff --git a/libdmmp/docs/man/dmmp_path_status_get.3 b/libdmmp/docs/man/dmmp_path_status_get.3
new file mode 100644
index 0000000..025cfee
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_path_status_get.3
@@ -0,0 +1,54 @@
+.TH "dmmp_path_status_get" 3 "dmmp_path_status_get" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_path_status_get \- Retrieve the path status.
+.SH SYNOPSIS
+.B "uint32_t" dmmp_path_status_get
+.BI "(struct dmmp_path *" dmmp_p ");"
+.SH ARGUMENTS
+.IP "dmmp_p" 12
+Pointer of 'struct dmmp_path'.
+If this pointer is NULL, your program will be terminated by assert.
+.SH "DESCRIPTION"
+
+The valid path statuses are:
+
+* DMMP_PATH_STATUS_UNKNOWN
+
+* DMMP_PATH_STATUS_DOWN
+
+Path is down and you shouldn't try to send commands to it.
+
+* DMMP_PATH_STATUS_UP
+
+Path is up and I/O can be sent to it.
+
+* DMMP_PATH_STATUS_SHAKY
+
+Only emc_clariion checker when path not available for "normal"
+operations.
+
+* DMMP_PATH_STATUS_GHOST
+
+Only hp_sw and rdac checkers. Indicates a "passive/standby"
+path on active/passive HP arrays. These paths will return valid
+answers to certain SCSI commands (tur, read_capacity, inquiry,
+start_stop), but will fail I/O commands. The path needs an
+initialization command to be sent to it in order for I/Os to
+succeed.
+
+* DMMP_PATH_STATUS_PENDING
+
+Available for all async checkers when a check IO is in flight.
+
+* DMMP_PATH_STATUS_TIMEOUT
+
+Only tur checker when command timed out.
+
+* DMMP_PATH_STATUS_DELAYED
+
+If a path fails after being up for less than delay_watch_checks checks,
+when it comes back up again, it will not be marked as up until it has
+been up for delay_wait_checks checks. During this time, it is marked as
+"delayed".
+.SH "RETURN"
+uint32_t.
diff --git a/libdmmp/docs/man/dmmp_path_status_str.3 b/libdmmp/docs/man/dmmp_path_status_str.3
new file mode 100644
index 0000000..3944d39
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_path_status_str.3
@@ -0,0 +1,34 @@
+.TH "dmmp_path_status_str" 3 "dmmp_path_status_str" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_path_status_str \- Convert path status to string.
+.SH SYNOPSIS
+.B "const char *" dmmp_path_status_str
+.BI "(uint32_t " path_status ");"
+.SH ARGUMENTS
+.IP "path_status" 12
+uint32_t. Path status.
+When provided value is not a valid path status, return
+"Invalid argument".
+.SH "DESCRIPTION"
+
+Convert path status uint32_t to string (const char *):
+
+* DMMP_PATH_STATUS_UNKNOWN -- "undef"
+
+* DMMP_PATH_STATUS_DOWN -- "faulty"
+
+* DMMP_PATH_STATUS_UP -- "ready"
+
+* DMMP_PATH_STATUS_SHAKY -- "shaky"
+
+* DMMP_PATH_STATUS_GHOST -- "ghost"
+
+* DMMP_PATH_STATUS_PENDING -- "pending"
+
+* DMMP_PATH_STATUS_TIMEOUT -- "timeout"
+
+* DMMP_PATH_STATUS_REMOVED -- "removed"
+
+* DMMP_PATH_STATUS_DELAYED -- "delayed"
+.SH "RETURN"
+const char *. The meaning of status value.
diff --git a/libdmmp/docs/man/dmmp_reconfig.3 b/libdmmp/docs/man/dmmp_reconfig.3
new file mode 100644
index 0000000..a743e30
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_reconfig.3
@@ -0,0 +1,27 @@
+.TH "dmmp_reconfig" 3 "dmmp_reconfig" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_reconfig \- Instruct multipathd daemon to do reconfiguration.
+.SH SYNOPSIS
+.B "int" dmmp_reconfig
+.BI "(struct dmmp_context *" ctx ");"
+.SH ARGUMENTS
+.IP "ctx" 12
+Pointer of 'struct dmmp_context'.
+If this pointer is NULL, your program will be terminated by assert.
+.SH "DESCRIPTION"
+
+Instruct multipathd daemon to do reconfiguration.
+.SH "RETURN"
+int. Valid error codes are:
+
+* DMMP_OK
+
+* DMMP_ERR_BUG
+
+* DMMP_ERR_NO_MEMORY
+
+* DMMP_ERR_NO_DAEMON
+
+* DMMP_ERR_PERMISSION_DENY
+
+Error number could be converted to string by \fBdmmp_strerror\fP.
diff --git a/libdmmp/docs/man/dmmp_strerror.3 b/libdmmp/docs/man/dmmp_strerror.3
new file mode 100644
index 0000000..4d753d3
--- /dev/null
+++ b/libdmmp/docs/man/dmmp_strerror.3
@@ -0,0 +1,33 @@
+.TH "dmmp_strerror" 3 "dmmp_strerror" "March 2021" "Device Mapper Multipath API - libdmmp Manual"
+.SH NAME
+dmmp_strerror \- Convert error code to string.
+.SH SYNOPSIS
+.B "const char *" dmmp_strerror
+.BI "(int " rc ");"
+.SH ARGUMENTS
+.IP "rc" 12
+int. Return code by libdmmp functions. When provided error code is not a
+valid error code, return "Invalid argument".
+.SH "DESCRIPTION"
+
+Convert error code (int) to string (const char *):
+
+* DMMP_OK -- "OK"
+
+* DMMP_ERR_BUG -- "BUG of libdmmp library"
+
+* DMMP_ERR_NO_MEMORY -- "Out of memory"
+
+* DMMP_ERR_IPC_TIMEOUT -- "Timeout when communicate with multipathd,
+try to set bigger timeout value via dmmp_context_timeout_set ()"
+
+* DMMP_ERR_IPC_ERROR -- "Error when communicate with multipathd daemon"
+
+* DMMP_ERR_NO_DAEMON -- "The multipathd daemon not started"
+
+* DMMP_ERR_INCOMPATIBLE -- "The multipathd daemon version is not
+compatible with current library"
+
+* Other invalid error number -- "Invalid argument"
+.SH "RETURN"
+const char *. The meaning of provided error code.
diff --git a/libdmmp/docs/libdmmp.h.3 b/libdmmp/docs/man/libdmmp.h.3
similarity index 100%
rename from libdmmp/docs/libdmmp.h.3
rename to libdmmp/docs/man/libdmmp.h.3
--
2.30.1
More information about the dm-devel
mailing list