pmlogcheck: extensions, refactor and fixups

- allow multiple archive options on command line, to check more than
  one archive at a time (itch scratched) ... previosuly we used the
  first archive and silently (!!) ignored all the trailing arguments
  from the command line ... this involves a major refactor to main()
  and special care to make sure pass0(), pass1(), pass2() and pass3()
  are safely re-callable
- when "archive" is a file name, process each archive at most once
  (even if multiple files are part of the same archive)
- fix pass2() error: derived metrics logged to an archive have
  some special PMID rules that pmlogcheck needs to understand

man/man1/pmlogcheck.1

@@ -23,16 +23,43 @@
 [\f3\-S\f1 \f2start\f1]
 [\f3\-T\f1 \f2finish\f1]
 [\f3\-Z\f1 \f2timezone\f1]
-\f2archive\f1
+\f2archive\f1 ...
+.de EX
+.in +0.5i
+.ie t .ft CB
+.el .ft B
+.ie t .sp .5v
+.el .sp
+.ta \\w' 'u*8
+.nf
+..
+.de EE
+.fi
+.ie t .sp .5v
+.el .sp
+.ft R
+.in
+..
 .SH DESCRIPTION
 .B pmlogcheck
 prints information about the nature of any invalid data which it detects
-in the files of a PCP archive.
+in the files of PCP archives.
 .PP
-The archive has the base name
+Each archive has the base name
 .I archive
 and must have been previously created using
 .BR pmlogger (1).
+Alternatively,
+.I archive
+can be the name of a physical file that forms part of a PCP archive.
+.PP
+When multiple
+.I archive
+options are present, all of the corresponding PCP archives will be
+checked, however if the
+.I archive
+options are file names, then each associated PCP archive will be checked
+at most once.
 .SH OPTIONS
 The available command line options are:
 .TP 5
@@ -183,6 +210,27 @@ in addition to the time at which the counter wrap occurred.
 If the extent of the data being checked is less than 24 hours, a more
 precise format is used (time is displayed with millisecond precision, but
 without the date).
+.SH EXAMPLES
+The following are all equivalent:
+.EX
+$ pmlogcheck myarchive
+.br
+$ pmlogcheck myarchive.0
+.br
+$ pmlogcheck myarchive.meta
+.br
+$ pmlogcheck myarchive.0 myarchive.meta
+.EE
+.PP
+If the current directory contains multiple PCP archives, then
+the command
+.EX
+$ pmlogcheck *.meta*
+.EE
+will check them all, as there is one
+.B .meta
+file for each PCP archive, but this file may have been compressed
+(hence the trailing \fB*\fP).
 .SH FILES
 .TP 5
 .I $PCP_VAR_DIR/pmns/*
@@ -214,4 +262,5 @@ and
 .BR PMNS (5).
 
 .\" control lines for scripts/man-spell
-.\" +ok+ endtime starttime
+.\" +ok+ endtime starttime myarchive {from example}
+.\" +ok+ sp {from troff .sp}

qa/1578

@@ -0,0 +1,86 @@
+#!/bin/sh
+# PCP QA Test No. 1578
+# pmlogcheck with archive ... extension (more than one archive)
+#
+# non-valgrind variant, see qa/1579 for the valgrind variant
+#
+# Copyright (c) 2024 Ken McDonell.  All Rights Reserved.
+#
+
+if [ $# -eq 0 ]
+then
+    seq=`basename $0`
+    echo "QA output created by $seq"
+else
+    # use $seq from caller, unless not set
+    [ -n "$seq" ] || seq=`basename $0`
+    echo "QA output created by `basename $0` $*"
+fi
+
+# get standard environment, filters and checks
+. ./common.product
+. ./common.filter
+. ./common.check
+
+$sudo rm -rf $tmp $tmp.* $seq.full
+
+do_valgrind=false
+if [ "$1" = "--valgrind" ]
+then
+    _check_valgrind
+    do_valgrind=true
+elif which valgrind >/dev/null 2>&1
+then
+    [ "$PCPQA_VALGRIND" = both ] || \
+        _notrun "valgrind variant qa/1579 will be run"
+fi
+
+_cleanup()
+{
+    cd $here
+    $sudo rm -rf $tmp $tmp.*
+}
+
+status=0	# success is the default!
+trap "_cleanup; exit \$status" 0 1 2 3 15
+
+_filter()
+{
+    sed \
+	-e "s@$tmp@TMP@g" \
+    # end
+}
+
+# real QA test starts here
+
+echo "lots of archive base names ..."
+if $do_valgrind
+then
+    _run_valgrind pmlogcheck -w -v archives/all-ubuntu.22.04 archives/moomba.client archives/kenj-pc-2 archives/omnibus_v2 archives/omnibus_v3 archives/ok-mv-foo archives/small
+else
+    pmlogcheck -w -v archives/all-ubuntu.22.04 archives/moomba.client archives/kenj-pc-2 archives/omnibus_v2 archives/omnibus_v3 archives/ok-mv-foo archives/small 2>&1
+fi \
+| _filter
+
+echo
+echo "lots of .meta names"
+if $do_valgrind
+then
+    _run_valgrind pmlogcheck -w -v archives/all-ubuntu.22.04.meta* archives/moomba.client.meta* archives/kenj-pc-2.meta* archives/omnibus_v2.meta* archives/omnibus_v3.meta* archives/ok-mv-foo.meta* archives/small.meta*
+else
+    pmlogcheck -w -v archives/all-ubuntu.22.04.meta* archives/moomba.client.meta* archives/kenj-pc-2.meta* archives/omnibus_v2.meta* archives/omnibus_v3.meta* archives/ok-mv-foo.meta* archives/small.meta* 2>&1
+fi \
+| _filter
+
+echo
+echo "lots of names for the same base names ..."
+if $do_valgrind
+then
+    _run_valgrind pmlogcheck -w -v archives/all-ubuntu.22.04.* archives/ok-mv-foo.*
+else
+    pmlogcheck -w -v archives/all-ubuntu.22.04.* archives/ok-mv-foo.*
+fi \
+| _filter
+
+# success, all done
+exit

qa/1578.out

@@ -0,0 +1,154 @@
+QA output created by 1578
+lots of archive base names ...
+Scanning for components of archive "archives/all-ubuntu.22.04"
+archives/all-ubuntu.22.04.index: start pass0 ... found 14 records
+archives/all-ubuntu.22.04.meta.xz: start pass0 ... found 12303 records
+archives/all-ubuntu.22.04.0.xz: start pass0 ... found 20 records
+archives/all-ubuntu.22.04: start pass1 (check temporal index)
+archives/all-ubuntu.22.04: start pass2
+archives/all-ubuntu.22.04: start pass3
+Processed 19 pmResult records
+Scanning for components of archive "archives/moomba.client"
+archives/moomba.client.index: start pass0 ... found 4 records
+archives/moomba.client.meta: start pass0 ... found 13 records
+archives/moomba.client.0: start pass0 ... found 12 records
+archives/moomba.client: start pass1 (check temporal index)
+archives/moomba.client: start pass2
+archives/moomba.client: start pass3
+Processed 30 pmResult records
+Scanning for components of archive "archives/kenj-pc-2"
+archives/kenj-pc-2.index: start pass0 ... found 37 records
+archives/kenj-pc-2.meta: start pass0 ... found 58 records
+archives/kenj-pc-2.0: start pass0 ... found 102 records
+archives/kenj-pc-2: start pass1 (check temporal index)
+archives/kenj-pc-2: start pass2
+archives/kenj-pc-2: start pass3
+Processed 131 pmResult records
+Scanning for components of archive "archives/omnibus_v2"
+archives/omnibus_v2.index: start pass0 ... found 24 records
+archives/omnibus_v2.meta: start pass0 ... found 123 records
+archives/omnibus_v2.0: start pass0 ... found 39 records
+archives/omnibus_v2: start pass1 (check temporal index)
+archives/omnibus_v2: start pass2
+archives/omnibus_v2: start pass3
+Processed 169 pmResult records
+Processed 2 <mark> records
+Scanning for components of archive "archives/omnibus_v3"
+archives/omnibus_v3.index: start pass0 ... found 24 records
+archives/omnibus_v3.meta: start pass0 ... found 123 records
+archives/omnibus_v3.0: start pass0 ... found 39 records
+archives/omnibus_v3: start pass1 (check temporal index)
+archives/omnibus_v3: start pass2
+archives/omnibus_v3: start pass3
+Processed 207 pmResult records
+Processed 4 <mark> records
+Scanning for components of archive "archives/ok-mv-foo"
+archives/ok-mv-foo.index: start pass0 ... found 6 records
+archives/ok-mv-foo.meta: start pass0 ... found 12 records
+archives/ok-mv-foo.0: start pass0 ... found 5 records
+archives/ok-mv-foo.1: start pass0 ... found 4 records
+archives/ok-mv-foo.2: start pass0 ... found 3 records
+archives/ok-mv-foo: start pass1 (check temporal index)
+archives/ok-mv-foo: start pass2
+archives/ok-mv-foo: start pass3
+Processed 216 pmResult records
+Processed 4 <mark> records
+Scanning for components of archive "archives/small"
+archives/small.index: start pass0 ... found 20 records
+archives/small.meta: start pass0 ... found 128 records
+archives/small.0.xz: start pass0 ... found 841 records
+archives/small: start pass1 (check temporal index)
+archives/small: start pass2
+archives/small: start pass3
+Processed 1056 pmResult records
+Processed 4 <mark> records
+
+lots of .meta names
+Scanning for components of archive "archives/all-ubuntu.22.04.meta.xz"
+archives/all-ubuntu.22.04.index: start pass0 ... found 14 records
+archives/all-ubuntu.22.04.meta.xz: start pass0 ... found 12303 records
+archives/all-ubuntu.22.04.0.xz: start pass0 ... found 20 records
+archives/all-ubuntu.22.04: start pass1 (check temporal index)
+archives/all-ubuntu.22.04: start pass2
+archives/all-ubuntu.22.04: start pass3
+Processed 19 pmResult records
+Scanning for components of archive "archives/moomba.client.meta"
+archives/moomba.client.index: start pass0 ... found 4 records
+archives/moomba.client.meta: start pass0 ... found 13 records
+archives/moomba.client.0: start pass0 ... found 12 records
+archives/moomba.client: start pass1 (check temporal index)
+archives/moomba.client: start pass2
+archives/moomba.client: start pass3
+Processed 30 pmResult records
+Scanning for components of archive "archives/kenj-pc-2.meta"
+archives/kenj-pc-2.index: start pass0 ... found 37 records
+archives/kenj-pc-2.meta: start pass0 ... found 58 records
+archives/kenj-pc-2.0: start pass0 ... found 102 records
+archives/kenj-pc-2: start pass1 (check temporal index)
+archives/kenj-pc-2: start pass2
+archives/kenj-pc-2: start pass3
+Processed 131 pmResult records
+Scanning for components of archive "archives/omnibus_v2.meta"
+archives/omnibus_v2.index: start pass0 ... found 24 records
+archives/omnibus_v2.meta: start pass0 ... found 123 records
+archives/omnibus_v2.0: start pass0 ... found 39 records
+archives/omnibus_v2: start pass1 (check temporal index)
+archives/omnibus_v2: start pass2
+archives/omnibus_v2: start pass3
+Processed 169 pmResult records
+Processed 2 <mark> records
+Scanning for components of archive "archives/omnibus_v3.meta"
+archives/omnibus_v3.index: start pass0 ... found 24 records
+archives/omnibus_v3.meta: start pass0 ... found 123 records
+archives/omnibus_v3.0: start pass0 ... found 39 records
+archives/omnibus_v3: start pass1 (check temporal index)
+archives/omnibus_v3: start pass2
+archives/omnibus_v3: start pass3
+Processed 207 pmResult records
+Processed 4 <mark> records
+Scanning for components of archive "archives/ok-mv-foo.meta"
+archives/ok-mv-foo.index: start pass0 ... found 6 records
+archives/ok-mv-foo.meta: start pass0 ... found 12 records
+archives/ok-mv-foo.0: start pass0 ... found 5 records
+archives/ok-mv-foo.1: start pass0 ... found 4 records
+archives/ok-mv-foo.2: start pass0 ... found 3 records
+archives/ok-mv-foo: start pass1 (check temporal index)
+archives/ok-mv-foo: start pass2
+archives/ok-mv-foo: start pass3
+Processed 216 pmResult records
+Processed 4 <mark> records
+Scanning for components of archive "archives/small.meta"
+archives/small.index: start pass0 ... found 20 records
+archives/small.meta: start pass0 ... found 128 records
+archives/small.0.xz: start pass0 ... found 841 records
+archives/small: start pass1 (check temporal index)
+archives/small: start pass2
+archives/small: start pass3
+Processed 1056 pmResult records
+Processed 4 <mark> records
+
+lots of names for the same base names ...
+Scanning for components of archive "archives/all-ubuntu.22.04.0.xz"
+archives/all-ubuntu.22.04.index: start pass0 ... found 14 records
+archives/all-ubuntu.22.04.meta.xz: start pass0 ... found 12303 records
+archives/all-ubuntu.22.04.0.xz: start pass0 ... found 20 records
+archives/all-ubuntu.22.04: start pass1 (check temporal index)
+archives/all-ubuntu.22.04: start pass2
+archives/all-ubuntu.22.04: start pass3
+Processed 19 pmResult records
+archives/all-ubuntu.22.04.index: skip, already checked this archive
+archives/all-ubuntu.22.04.meta.xz: skip, already checked this archive
+Scanning for components of archive "archives/ok-mv-foo.0"
+archives/ok-mv-foo.index: start pass0 ... found 6 records
+archives/ok-mv-foo.meta: start pass0 ... found 12 records
+archives/ok-mv-foo.0: start pass0 ... found 5 records
+archives/ok-mv-foo.1: start pass0 ... found 4 records
+archives/ok-mv-foo.2: start pass0 ... found 3 records
+archives/ok-mv-foo: start pass1 (check temporal index)
+archives/ok-mv-foo: start pass2
+archives/ok-mv-foo: start pass3
+Processed 28 pmResult records
+archives/ok-mv-foo.1: skip, already checked this archive
+archives/ok-mv-foo.2: skip, already checked this archive
+archives/ok-mv-foo.index: skip, already checked this archive
+archives/ok-mv-foo.meta: skip, already checked this archive

qa/1579

@@ -0,0 +1,37 @@
+#!/bin/sh
+# PCP QA Test No. 1579
+# pmlogcheck with archive ... extension (more than one archive)
+#
+# valgrind variant, see qa/1578 for the non-valgrind variant
+#
+# check-group-include: pmlogcheck
+#
+# Copyright (c) 2024 Ken McDonell.  All Rights Reserved.
+#
+
+seq=`basename $0`
+echo "QA output created by $seq"
+
+# get standard environment, filters and checks
+. ./common.product
+. ./common.filter
+. ./common.check
+
+_check_valgrind
+
+_cleanup()
+{
+    cd $here
+    $sudo rm -rf $tmp $tmp.*
+}
+
+status=0	# success is the default!
+$sudo rm -rf $tmp $tmp.* $seq.full
+trap "_cleanup; exit \$status" 0 1 2 3 15
+
+# real QA test starts here
+export seq
+./1578 --valgrind
+
+# success, all done
+exit