From: Martin Wilck <mwi...@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 <mwi...@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 -- dm-devel mailing list dm-devel@redhat.com https://listman.redhat.com/mailman/listinfo/dm-devel