Implement a "read-only" version of nextpart()

The system test helper function nextpart() always updates the "lines
read so far" marker ("<file>.prev") when it is called, which somewhat
limits its flexibility.  Add two new helper functions, nextpartpeek()
and nextpartreset(), so that certain parts of log files can be easily
examined more than once.  Add some documentation to help understand the
purpose of each function in the nextpart*() family.

bin/tests/system/conf.sh.in

@@ -289,13 +289,78 @@ keyfile_to_managed_keys() {
     keyfile_to_keys_section "managed-keys" "initial-key " $*
 }
 
-# nextpart: read everything that's been appended to a file since the
-# last time 'nextpart' was called.
-nextpart () {
-    [ -f $1.prev ] || echo "0" > $1.prev
+# nextpart*() - functions for reading files incrementally
+#
+# These functions aim to facilitate looking for (or waiting for)
+# messages which may be logged more than once throughout the lifetime of
+# a given named instance by outputting just the part of the file which
+# has been appended since the last time we read it.
+#
+# Calling some of these functions causes temporary *.prev files to be
+# created that need to be cleaned up manually (usually by a given system
+# test's clean.sh script).
+#
+# Note that unlike other nextpart*() functions, nextpartread() is not
+# meant to be directly used in system tests; its sole purpose is to
+# reduce code duplication below.
+#
+# A quick usage example:
+#
+#     $ echo line1 > named.log
+#     $ echo line2 >> named.log
+#     $ nextpart named.log
+#     line1
+#     line2
+#     $ echo line3 >> named.log
+#     $ nextpart named.log
+#     line3
+#     $ nextpart named.log
+#     $ echo line4 >> named.log
+#     $ nextpartpeek named.log
+#     line4
+#     $ nextpartpeek named.log
+#     line4
+#     $ nextpartreset named.log
+#     $ nextpartpeek named.log
+#     line1
+#     line2
+#     line3
+#     line4
+#     $ nextpart named.log
+#     line1
+#     line2
+#     line3
+#     line4
+#     $ nextpart named.log
+#     $
+
+# nextpartreset: reset the marker used by nextpart() and nextpartpeek()
+# so that it points to the start of the given file
+nextpartreset() {
+    echo "0" > $1.prev
+}
+
+# nextpartread: read everything that's been appended to a file since the
+# last time nextpart() was called and print it to stdout, print the
+# total number of lines read from that file so far to stderr
+nextpartread() {
+    [ -f $1.prev ] || nextpartreset $1
     prev=`cat $1.prev`
     awk "NR > $prev "'{ print }
-         END          { print NR > "/dev/stderr" }' $1 2> $1.prev
+         END          { print NR > "/dev/stderr" }' $1
+}
+
+# nextpart: read everything that's been appended to a file since the
+# last time nextpart() was called
+nextpart() {
+	nextpartread $1 2> $1.prev.tmp
+	mv $1.prev.tmp $1.prev
+}
+
+# nextpartpeek: read everything that's been appended to a file since the
+# last time nextpart() was called
+nextpartpeek() {
+	nextpartread $1 2> /dev/null
 }
 
 # copy_setports - Copy Configuration File and Replace Ports

bin/tests/system/conf.sh.win32

@@ -266,13 +266,78 @@ keyfile_to_managed_keys() {
     keyfile_to_keys_section "managed-keys" "initial-key " $*
 }
 
-# nextpart: read everything that's been appended to a file since the
-# last time 'nextpart' was called.
-nextpart () {
-    [ -f $1.prev ] || echo "0" > $1.prev
+# nextpart*() - functions for reading files incrementally
+#
+# These functions aim to facilitate looking for (or waiting for)
+# messages which may be logged more than once throughout the lifetime of
+# a given named instance by outputting just the part of the file which
+# has been appended since the last time we read it.
+#
+# Calling some of these functions causes temporary *.prev files to be
+# created that need to be cleaned up manually (usually by a given system
+# test's clean.sh script).
+#
+# Note that unlike other nextpart*() functions, nextpartread() is not
+# meant to be directly used in system tests; its sole purpose is to
+# reduce code duplication below.
+#
+# A quick usage example:
+#
+#     $ echo line1 > named.log
+#     $ echo line2 >> named.log
+#     $ nextpart named.log
+#     line1
+#     line2
+#     $ echo line3 >> named.log
+#     $ nextpart named.log
+#     line3
+#     $ nextpart named.log
+#     $ echo line4 >> named.log
+#     $ nextpartpeek named.log
+#     line4
+#     $ nextpartpeek named.log
+#     line4
+#     $ nextpartreset named.log
+#     $ nextpartpeek named.log
+#     line1
+#     line2
+#     line3
+#     line4
+#     $ nextpart named.log
+#     line1
+#     line2
+#     line3
+#     line4
+#     $ nextpart named.log
+#     $
+
+# nextpartreset: reset the marker used by nextpart() and nextpartpeek()
+# so that it points to the start of the given file
+nextpartreset() {
+    echo "0" > $1.prev
+}
+
+# nextpartread: read everything that's been appended to a file since the
+# last time 'nextpart' was called and print it to stdout, print the
+# total number of lines read from that file so far to stderr
+nextpartread() {
+    [ -f $1.prev ] || nextpartreset $1
     prev=`cat $1.prev`
     awk "NR > $prev "'{ print }
-         END          { print NR > "/dev/stderr" }' $1 2> $1.prev
+         END          { print NR > "/dev/stderr" }' $1
+}
+
+# nextpart: read everything that's been appended to a file since the
+# last time 'nextpart' was called
+nextpart() {
+	nextpartread $1 2> $1.prev.tmp
+	mv $1.prev.tmp $1.prev
+}
+
+# nextpartpeek: read everything that's been appended to a file since the
+# last time 'nextpart' was called
+nextpartpeek() {
+	nextpartread $1 2> /dev/null
 }
 
 # copy_setports - Copy Configuration File and Replace Ports