nut-scanner code and docs: refactor with nutscan_ip_range_list_t type…

… for ip_ranges[] list and helper metadata, and methods as part of libnutscan [networkupstools#2244, networkupstools#2511]

Not bumping library version, because it was recently bumped as
part of other PRs about this issue. Technically the scope of the
library has been changed by new exported methods and header lines.

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>

docs/man/Makefile.am

@@ -198,6 +198,9 @@ SRC_DEV_PAGES = \
 	nutscan_display_ups_conf_with_sanity_check.txt \
 	nutscan_display_ups_conf.txt \
 	nutscan_display_parsable.txt \
+	nutscan_init_ip_ranges.txt \
+	nutscan_free_ip_ranges.txt \
+	nutscan_add_ip_range.txt \
 	nutscan_cidr_to_ip.txt \
 	nutscan_new_device.txt \
 	nutscan_free_device.txt \
@@ -316,6 +319,9 @@ MAN3_DEV_PAGES = \
 	nutscan_display_ups_conf_with_sanity_check.3 \
 	nutscan_display_ups_conf.3 \
 	nutscan_display_parsable.3 \
+	nutscan_init_ip_ranges.3 \
+	nutscan_free_ip_ranges.3 \
+	nutscan_add_ip_range.3 \
 	nutscan_cidr_to_ip.3 \
 	nutscan_new_device.3 \
 	nutscan_free_device.3 \
@@ -391,6 +397,9 @@ HTML_DEV_MANS = \
 	nutscan_display_ups_conf_with_sanity_check.html \
 	nutscan_display_ups_conf.html \
 	nutscan_display_parsable.html \
+	nutscan_init_ip_ranges.html \
+	nutscan_free_ip_ranges.html \
+	nutscan_add_ip_range.html \
 	nutscan_cidr_to_ip.html \
 	nutscan_new_device.html \
 	nutscan_free_device.html \

docs/man/nutscan.txt

@@ -68,6 +68,9 @@ linkman:nutscan_display_parsable[3], linkman:nutscan_display_ups_conf[3],
 linkman:nutscan_new_device[3], linkman:nutscan_free_device[3],
 linkman:nutscan_add_device_to_device[3],
 linkman:nutscan_add_option_to_device[3],
+linkman:nutscan_init_ip_ranges[3],
+linkman:nutscan_free_ip_ranges[3],
+linkman:nutscan_add_ip_range[3],
 linkman:nutscan_cidr_to_ip[3]
 
 Internet resources:

docs/man/nutscan_add_ip_range.txt

@@ -0,0 +1,74 @@
+NUTSCAN_FREE_IP_RANGES(3)
+=========================
+
+NAME
+----
+
+nutscan_add_ip_range - Add an entry with IP address range (start and end
+address) to a `nutscan_ip_range_list_t` structure.
+
+SYNOPSIS
+--------
+
+ #include <nut-scan.h>
+
+ /* One IP address range: */
+ typedef struct nutscan_ip_range_s {
+    char * start_ip;
+    char * end_ip;
+    struct nutscan_ip_range_s * next;
+ } nutscan_ip_range_t;
+
+ /* List of IP address ranges and helper data: */
+ typedef struct nutscan_ip_range_list_s {
+    nutscan_ip_range_t * ip_ranges;
+    nutscan_ip_range_t * ip_ranges_last;
+    size_t ip_ranges_count;
+ } nutscan_ip_range_list_t;
+
+
+ size_t nutscan_add_ip_range(
+    nutscan_ip_range_list_t *irl,
+    char * start_ip,
+    char * end_ip);
+
+DESCRIPTION
+-----------
+
+The *nutscan_add_ip_range()* function can create and add a `nutscan_ip_range_t`
+entry based on provided inputs to the specified `nutscan_ip_range_list_t`
+structure.  The resulting amount of entries in the structure is returned,
+or 0 in case of non-fatal errors.
+
+This function skips work if:
+
+* the structure pointer is `NULL` (0 is returned);
+* neither `start_ip` nor `end_ip` were provided, i.e. they have `NULL` values
+  (current list length from the structure is returned);
+* failed to allocate the entry (fatal).
+
+If only one of `start_ip` or `end_ip` values was provided (not `NULL`), a
+single-address range is created with both addresses set to the same pointer
+value.
+
+The structure should be initialized before use by `nutscan_init_ip_ranges()`.
+
+The caller must free the contents of the structure after completing its use
+by calling `nutscan_free_ip_ranges()` (after which the structure can be
+re-used for a new list), and explicitly `free()` the structure object itself if
+it was allocated dynamically (e.g. by calling `nutscan_init_ip_ranges(NULL)`).
+
+NOTES
+-----
+
+Technically, the function is currently defined in 'nutscan-ip.h' file.
+
+Currently there are no checks for duplicate or overlapping entries, so the
+same IP addresses and whole IP address ranges can be added to the list (and
+would eventually be scanned) many times.
+
+SEE ALSO
+--------
+
+linkman:nutscan_init_ip_ranges[3], linkman:nutscan_free_ip_ranges[3],
+linkman:nutscan_cidr_to_ip[3]

docs/man/nutscan_free_ip_ranges.txt

@@ -0,0 +1,40 @@
+NUTSCAN_FREE_IP_RANGES(3)
+=========================
+
+NAME
+----
+
+nutscan_free_ip_ranges - Free contents of a `nutscan_ip_range_list_t`
+structure populated (and optionally created) by `nutscan_init_ip_ranges()`
+and, more importantly, filled by a series of `nutscan_add_ip_range()` calls.
+
+SYNOPSIS
+--------
+
+ #include <nut-scan.h>
+
+ void nutscan_free_ip_ranges(nutscan_ip_range_list_t *irl);
+
+DESCRIPTION
+-----------
+
+The *nutscan_free_ip_ranges()* function can free a `nutscan_ip_range_list_t`
+structure. Doing so, it frees the whole linked list of `nutscan_ip_range_t`
+entries, and zeroes out helper properties.
+
+The structure itself is not freed (as it can be a statically allocated
+variable on the stack), and can be re-used for a new list if needed.
+
+The caller must free the structure object if it was allocated dynamically
+(e.g. by calling `nutscan_init_ip_ranges(NULL)`).
+
+NOTES
+-----
+
+Technically, the function is currently defined in 'nutscan-ip.h' file.
+
+SEE ALSO
+--------
+
+linkman:nutscan_init_ip_ranges[3], linkman:nutscan_add_ip_range[3],
+linkman:nutscan_cidr_to_ip[3]

docs/man/nutscan_init_ip_ranges.txt

@@ -0,0 +1,41 @@
+NUTSCAN_INIT_IP_RANGES(3)
+=========================
+
+NAME
+----
+
+nutscan_init_ip_ranges - Initialize contents of a `nutscan_ip_range_list_t`
+structure (and optionally create one in the first place).
+
+SYNOPSIS
+--------
+
+ #include <nut-scan.h>
+
+ nutscan_ip_range_list_t * nutscan_init_ip_ranges(nutscan_ip_range_list_t *irl);
+
+DESCRIPTION
+-----------
+
+The *nutscan_init_ip_ranges()* function can prepare a `nutscan_ip_range_list_t`
+structure by zeroing out its fields.  If the argument is `NULL`, the structure
+is dynamically allocated.  Either way, a pointer to it is returned.
+
+A structure passed by caller is not assumed to have any valid contents to free,
+as it may have garbage from stack after allocation.
+
+The caller must free the contents of the structure after completing its use
+by calling `nutscan_free_ip_ranges` (after which the structure can be re-used),
+and explicitly `free()` the structure object itself if it was allocated
+dynamically (e.g. by calling `nutscan_init_ip_ranges(NULL)`).
+
+NOTES
+-----
+
+Technically, the function is currently defined in 'nutscan-ip.h' file.
+
+SEE ALSO
+--------
+
+linkman:nutscan_free_ip_ranges[3], linkman:nutscan_add_ip_range[3],
+linkman:nutscan_cidr_to_ip[3]

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 3178 utf-8
+personal_ws-1.1 en 3179 utf-8
 AAC
 AAS
 ABI
@@ -2090,6 +2090,7 @@ ipp
 ippon
 ipv
 ipxe
+irl
 isDefault
 isbmex
 ish