X-Git-Url: https://git.distorted.org.uk/~mdw/mLib/blobdiff_plain/20ba6b0b276f584060415023d68b59917de1e7e6..13ee740655965453b2f3fcd7093d2d8b13839903:/test/tvec.h

diff --git a/test/tvec.h b/test/tvec.h
index e9e785a..d16df58 100644
--- a/test/tvec.h
+++ b/test/tvec.h
@@ -57,8 +57,8 @@
  *				-> @tvec_mismatch@
  *					-> output @dumpreg@
  *						-> type @dump@
- *			-> env @after@
  *			-> output @etest@
+ *			-> env @after@
  *   finally
  *			-> output @egroup@
  *			-> env @teardown@
@@ -177,47 +177,50 @@ enum {
  */
 
 union tvec_regval {
-	/* The actual register value.  This is what the type handler sees.
-	 * Additional members can be added by setting `TVEC_REGSLOTS' before
-	 * including this file.
-	 *
-	 * A register value can be /initialized/, which simply means that its
-	 * contents represent a valid value according to its type -- the
-	 * register can be compared, dumped, serialized, parsed into, etc.
-	 * You can't do anything safely to an uninitialized register value
-	 * other than initialize it.
-	 */
+  /* The actual register value.  This is what the type handler sees.
+   * Additional members can be added by setting `TVEC_REGSLOTS' before
+   * including this file.
+   *
+   * A register value can be /initialized/, which simply means that its
+   * contents represent a valid value according to its type -- the register
+   * can be compared, dumped, serialized, parsed into, etc.  You can't do
+   * anything safely to an uninitialized register value other than initialize
+   * it.
+   */
 
   long i;				/* signed integer */
   unsigned long u;			/* unsigned integer */
   void *p;				/* pointer */
   double f;				/* floating point */
   struct { unsigned char *p; size_t sz; } bytes; /* binary string of bytes */
-  struct { char *p; size_t sz; } str;	/* text string */
+  struct { char *p; size_t sz; } text;	/* text string */
+  struct {				/* buffer */
+    unsigned char *p; size_t sz;	/* binary string */
+    size_t a, m;			/* residue and modulus */
+    size_t off;				/* offset into full buffer */
+  } buf;
 #ifdef TVEC_REGSLOTS
   TVEC_REGSLOTS
 #endif
 };
 
 struct tvec_reg {
-	/* A register.
-	 *
-	 * Note that all of the registers listed as being used by a
-	 * particular test group are initialized at all times[1] while that
-	 * test group is being processed.  (The other register slots don't
-	 * even have types associated with them, so there's nothing useful we
-	 * could do with them.)
-	 *
-	 * The `TVRF_LIVE' flag indicates that the register was assigned a
-	 * value by the test vector file: it's the right thing to use to
-	 * check whether an optional register is actually present.  Even
-	 * `dead' registers are still initialized, though.
-	 *
-	 * [1] This isn't quite true.  Between individual tests, the
-	 *     registers are released and reinitialized in order to reset
-	 *     them to known values ready for the next test.  But you won't
-	 *     see them at this point.
-	 */
+  /* A register.
+   *
+   * Note that all of the registers listed as being used by a particular test
+   * group are initialized at all times[1] while that test group is being
+   * processed.  (The other register slots don't even have types associated
+   * with them, so there's nothing useful we could do with them.)
+   *
+   * The `TVRF_LIVE' flag indicates that the register was assigned a value by
+   * the test vector file: it's the right thing to use to check whether an
+   * optional register is actually present.  Even `dead' registers are still
+   * initialized, though.
+   *
+   * [1] This isn't quite true.  Between individual tests, the registers are
+   *	 released and reinitialized in order to reset them to known values
+   *	 ready for the next test.  But you won't see them at this point.
+   */
 
   unsigned f;				/* flags */
 #define TVRF_LIVE 1u			/*   used in current test  */
@@ -225,13 +228,12 @@ struct tvec_reg {
 };
 
 struct tvec_regdef {
-	/* A register definition.  Register definitions list the registers
-	 * which are used by a particular test group (see `struct tvec_test'
-	 * below).
-	 *
-	 * A vector of register definitions is terminated by a definition
-	 * whose `name' slot is null.
-	 */
+  /* A register definition.  Register definitions list the registers which
+   * are used by a particular test group (see `struct tvec_test' below).
+   *
+   * A vector of register definitions is terminated by a definition whose
+   * `name' slot is null.
+   */
 
   const char *name;			/* register name (for input files) */
   unsigned i;				/* register index */
@@ -266,55 +268,55 @@ struct tvec_regty {
   /* A register type. */
 
   void (*init)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/);
-	/* Initialize the value in @*rv@.  This will be called before any
-	 * other function acting on the value, including @release@.
-	 */
+    /* Initialize the value in @*rv@.  This will be called before any other
+     * function acting on the value, including @release@.
+     */
 
   void (*release)(union tvec_regval */*rv*/,
 		  const struct tvec_regdef */*rd*/);
-	/* Release any resources associated with the value in @*rv@. */
+    /* Release any resources associated with the value in @*rv@. */
 
   int (*eq)(const union tvec_regval */*rv0*/,
 	    const union tvec_regval */*rv1*/,
 	    const struct tvec_regdef */*rd*/);
-	/* Return nonzero if @*rv0@ and @*rv1@ are equal values.
-	 * Asymmetric criteria are permitted: @tvec_checkregs@ calls @eq@
-	 * with the input register as @rv0@ and the output as @rv1@.
-	 */
+    /* Return nonzero if @*rv0@ and @*rv1@ are equal values.  Asymmetric
+     * criteria are permitted: @tvec_checkregs@ calls @eq@ with the input
+     * register as @rv0@ and the output as @rv1@.
+     */
 
   int (*tobuf)(buf */*b*/, const union tvec_regval */*rv*/,
 	       const struct tvec_regdef */*rd*/);
-	/* Serialize the value @*rv@, writing the result to @b@.  Return
-	 * zero on success, or @-1@ on error.
-	 */
+    /* Serialize the value @*rv@, writing the result to @b@.  Return zero on
+     * success, or %$-1$% on error.
+     */
 
   int (*frombuf)(buf */*b*/, union tvec_regval */*rv*/,
 		 const struct tvec_regdef */*rd*/);
-	/* Deserialize a value from @b@, storing it in @*rv@.  Return zero on
-	 * success, or @-1@ on error.
-	 */
+    /* Deserialize a value from @b@, storing it in @*rv@.  Return zero on
+     * success, or %$-1$% on error.
+     */
 
   int (*parse)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/,
 	       struct tvec_state */*tv*/);
-	/* Parse a value from @tv->fp@, storing it in @*rv@.  Return zero on
-	 * success, or @-1@ on error, having reported one or more errors via
-	 * @tvec_error@ or @tvec_syntax@.  A successful return should leave
-	 * the input position at the start of the next line; the caller will
-	 * flush the remainder of the line itself.
-	 */
+    /* Parse a value from @tv->fp@, storing it in @*rv@.  Return zero on
+     * success, or %$-1$% on error, having reported one or more errors via
+     * @tvec_error@ or @tvec_syntax@.  A successful return should leave the
+     * input position at the start of the next line; the caller will flush
+     * the remainder of the line itself.
+     */
 
   void (*dump)(const union tvec_regval */*rv*/,
 	       const struct tvec_regdef */*rd*/,
 	       unsigned /*style*/,
 	       const struct gprintf_ops */*gops*/, void */*go*/);
 #define TVSF_COMPACT 1u
-	/* Write a human-readable representation of the value @*rv@ using
-	 * @gprintf@ on @gops@ and @go@.  The @style@ is a collection of
-	 * flags: if @TVSF_COMPACT@ is set, then output should be minimal,
-	 * and must fit on a single line; otherwise, output may consist of
-	 * multiple lines and may contain redundant information if that is
-	 * likely to be useful to a human reader.
-	 */
+    /* Write a human-readable representation of the value @*rv@ using
+     * @gprintf@ on @gops@ and @go@.  The @style@ is a collection of flags:
+     * if @TVSF_COMPACT@ is set, then output should be minimal, and must fit
+     * on a single line; otherwise, output may consist of multiple lines and
+     * may contain redundant information if that is likely to be useful to a
+     * human reader.
+     */
 };
 
 /*----- Test descriptions -------------------------------------------------*/
@@ -340,28 +342,46 @@ typedef void tvec_testfn(const struct tvec_reg */*in*/,
 
 struct tvec_env;
 
+typedef int tvec_setvarfn(struct tvec_state */*tv*/, const char */*var*/,
+			  const union tvec_regval */*rv*/, void */*ctx*/);
+  /* Called after a variable is read.  Return zero on success or %$-1$% on
+   * error.  This function is never called if the test group is skipped.
+   */
+
+struct tvec_vardef {
+  size_t regsz;				/* (minimum) register size */
+  tvec_setvarfn *setvar;		/* function to set variable */
+  struct tvec_regdef def;		/* register definition */
+};
+
 typedef void tvec_envsetupfn(struct tvec_state */*tv*/,
 			     const struct tvec_env */*env*/,
 			     void */*pctx*/, void */*ctx*/);
   /* Initialize the context; called at the start of a test group; @pctx@ is
    * null for environments called by the core, but may be non-null for
    * subordinate environments.  If setup fails, the function should call
-   * @tvec_skipgroup@ with a suitable excuse.  The @set@ and @teardown@ entry
-   * points will still be called, but @before@, @run@, and @after@ will not.
+   * @tvec_skipgroup@ with a suitable excuse.  The @set@, @after@, and
+   * @teardown@ entry points will still be called, but @before@ and @run@
+   * will not.
    */
 
-typedef int tvec_envsetfn(struct tvec_state */*tv*/, const char */*var*/,
-			  const struct tvec_env */*env*/, void */*ctx*/);
-  /* Called when the parser finds a %|@var|%' setting to parse and store the
-   * value.  If @setup@ failed, this is still called (so as to skip the
-   * value), but @ctx@ is null.
+typedef const struct tvec_vardef *tvec_envfindvarfn
+  (struct tvec_state */*tv*/, const char */*name*/,
+   void **/*ctx_out*/, void */*ctx*/);
+  /* Called when the parser finds a %|@var|%' special variable.  If a
+   * suitable variable was found, set @*ctx_out@ to a suitable context and
+   * return the variable definition; the context will be passed to the
+   * variable definition's @setvar@ function.  If no suitable variable was
+   * found, then return null.
    */
 
 typedef void tvec_envbeforefn(struct tvec_state */*tv*/, void */*ctx*/);
   /* Called prior to running a test.  This is the right place to act on any
    * `%|@var|%' settings.  If preparation fails, the function should call
    * @tvec_skip@ with a suitable excuse.  This function is never called if
-   * the test group is skipped.
+   * the test group is skipped.  It %%\emph{is}%% called if the test will be
+   * skipped due to erroneous test data.  It should check the @TVSF_ACTIVE@
+   * flag if necessary.
    */
 
 typedef void tvec_envrunfn(struct tvec_state */*tv*/,
@@ -376,8 +396,10 @@ typedef void tvec_envrunfn(struct tvec_state */*tv*/,
 
 typedef void tvec_envafterfn(struct tvec_state */*tv*/, void */*ctx*/);
   /* Called after running or skipping a test.  Typical actions involve
-   * resetting whatever things were established by @set@.  This function is
-   * never called if the test group is skipped.
+   * resetting whatever things were established by @set@.  This function
+   * %%\emph{is}%% called if the test group is skipped or the test data is
+   * erroneous, so that the test environment can reset variables set by the
+   * @set@ entry point.  It should check the @TVSF_SKIP@ flag if necessary.
    */
 
 typedef void tvec_envteardownfn(struct tvec_state */*tv*/, void */*ctx*/);
@@ -396,7 +418,7 @@ struct tvec_env {
   size_t ctxsz;				/* environment context size */
 
   tvec_envsetupfn *setup;		/* setup for group */
-  tvec_envsetfn *set;			/* set variable */
+  tvec_envfindvarfn *findvar;		/* find variable */
   tvec_envbeforefn *before;		/* prepare for test */
   tvec_envrunfn *run;			/* run test function */
   tvec_envafterfn *after;		/* clean up after test */
@@ -447,6 +469,7 @@ struct tvec_state {
 #define TVSF_OUTMASK 0x00f0u		/*   test outcome (@TVOUT_...@) */
 #define TVSF_OUTSHIFT 4			/*   shift applied to outcome */
 #define TVSF_XFAIL 0x0100u		/*   test expected to fail */
+#define TVSF_MUFFLE 0x0200u		/*   muffle errors */
 
   /* Registers.  Available to execution environments. */
   unsigned nrout, nreg;		       /* number of output/total registers */
@@ -496,112 +519,116 @@ enum {
   TVBU_BYTE,				/* counting bytes (@rbuf >= 0@) */
   TVBU_LIMIT				/* (number of units) */
 };
-struct bench_timing;			/* forward declaration */
+struct bench_timing;	 /* include <mLib/bench.h> for the real definition */
 
 struct tvec_outops {
   /* Output operations. */
 
   void (*bsession)(struct tvec_output */*o*/, struct tvec_state */*tv*/);
-	/* Begin a test session.  The output driver will probably want to
-	 * save @tv@, because this isn't provided to any other methods.
-	 */
+    /* Begin a test session.  The output driver will probably want to
+     * save @tv@, because this isn't provided to any other methods.
+     */
 
   int (*esession)(struct tvec_output */*o*/);
-	/* End a session, and return the suggested exit code. */
+    /* End a session, and return the suggested exit code. */
 
   void (*bgroup)(struct tvec_output */*o*/);
-	/* Begin a test group.  The test group description is @tv->test@. */
+    /* Begin a test group.  The test group description is @tv->test@. */
 
   void (*skipgroup)(struct tvec_output */*o*/,
 		    const char */*excuse*/, va_list */*ap*/);
-	/* The group is being skipped; @excuse@ may be null or a format
-	 * string explaining why.  The @egroup@ method will not be called
-	 * separately.
-	 */
+    /* The group is being skipped; @excuse@ may be null or a format
+     * string explaining why.  The @egroup@ method will not be called
+     * separately.
+     */
 
   void (*egroup)(struct tvec_output */*o*/);
-	/* End a test group.  At least one test was attempted or @skipgroup@
-	 * would have been called instead.  If @tv->curr[TVOUT_LOSE]@ is
-	 * nonzero then the test group as a whole failed; otherwise it
-	 * passed.
-	 */
+    /* End a test group.  At least one test was attempted or @skipgroup@
+     * would have been called instead.  If @tv->curr[TVOUT_LOSE]@ is nonzero
+     * then the test group as a whole failed; otherwise it passed.
+     */
 
   void (*btest)(struct tvec_output */*o*/);
-	/* Begin a test case. */
+    /* Begin a test case. */
 
   void (*skip)(struct tvec_output */*o*/,
 	       const char */*excuse*/, va_list */*ap*/);
-	/* The test case is being skipped; @excuse@ may be null or a format
-	 * string explaining why.  The @etest@ function will still be called
-	 * (so this works differently from @skipgroup@ and @egroup@).  A test
-	 * case can be skipped at most once, and, if skipped, it cannot fail.
-	 */
+    /* The test case is being skipped; @excuse@ may be null or a format
+     * string explaining why.  The @etest@ function will still be called (so
+     * this works differently from @skipgroup@ and @egroup@).  A test case
+     * can be skipped at most once, and, if skipped, it cannot fail.
+     */
 
   void (*fail)(struct tvec_output */*o*/,
 	       const char */*detail*/, va_list */*ap*/);
-	/* The test case failed.
-	 *
-	 * The output driver should preferably report the filename (@infile@)
-	 * and line number (@test_lno@, not @lno@) for the failing test.
-	 *
-	 * The @detail@ may be null or a format string describing detail
-	 * about how the failing test was run which can't be determined from
-	 * the registers; a @detail@ is usually provided when (and only when)
-	 * the test environment potentially invokes the test function more
-	 * than once.
-	 *
-	 * A single test case can fail multiple times!
-	 */
+    /* The test case failed.
+     *
+     * The output driver should preferably report the filename (@infile@) and
+     * line number (@test_lno@, not @lno@) for the failing test.
+     *
+     * The @detail@ may be null or a format string describing detail about
+     * how the failing test was run which can't be determined from the
+     * registers; a @detail@ is usually provided when (and only when) the
+     * test environment potentially invokes the test function more than once.
+     *
+     * A single test case can fail multiple times!
+     */
 
   void (*dumpreg)(struct tvec_output */*o*/,
 		  unsigned /*disp*/, const union tvec_regval */*rv*/,
 		  const struct tvec_regdef */*rd*/);
-	/* Dump a register.  The `disposition' @disp@ explains what condition
-	 * the register is in; see @tvec_dumpreg@ and the @TVRD_...@ codes.
-	 * The register value is at @rv@, and its definition, including its
-	 * type, at @rd@.  Note that this function may be called on virtual
-	 * registers which aren't in either of the register vectors or
-	 * mentioned by the test description.  It may also be called with
-	 * @rv@ null, indicating that the register is not live.
-	 */
+    /* Dump a register.  The `disposition' @disp@ explains what condition the
+     * register is in; see @tvec_dumpreg@ and the @TVRD_...@ codes.  The
+     * register value is at @rv@, and its definition, including its type, at
+     * @rd@.  Note that this function may be called on virtual registers
+     * which aren't in either of the register vectors or mentioned by the
+     * test description.  It may also be called with @rv@ null, indicating
+     * that the register is not live.
+     */
 
   void (*etest)(struct tvec_output */*o*/, unsigned /*outcome*/);
-	/* The test case concluded with the given @outcome@ (one of the
-	 * @TVOUT_...@ codes.
-	 */
+    /* The test case concluded with the given @outcome@ (one of the
+     * @TVOUT_...@ codes.
+     */
 
   void (*bbench)(struct tvec_output */*o*/,
 		 const char */*ident*/, unsigned /*unit*/);
-	/* Begin a benchmark.  The @ident@ is a formatted string identifying
-	 * the benchmark based on the values of the input registered marked
-	 * @TVRF_ID@; the output driver is free to use this or come up with
-	 * its own way to identify the test, e.g., by inspecting the register
-	 * values for itself.  The @unit@ is one of the @TVBU_...@ constants
-	 * explaining what sort of thing is being measured.
-	 */
+    /* Begin a benchmark.  The @ident@ is a formatted string identifying the
+     * benchmark based on the values of the input registered marked
+     * @TVRF_ID@; the output driver is free to use this or come up with its
+     * own way to identify the test, e.g., by inspecting the register values
+     * for itself.  The @unit@ is one of the @TVBU_...@ constants explaining
+     * what sort of thing is being measured.
+     */
 
   void (*ebench)(struct tvec_output */*o*/,
 		 const char */*ident*/, unsigned /*unit*/,
 		 const struct bench_timing */*tm*/);
-	/* End a benchmark.  The @ident@ and @unit@ arguments are as for
-	 * @bbench@.  If @tm@ is zero then the measurement failed; otherwise
-	 * @tm->n@ counts total number of things (operations or bytes, as
-	 * indicated by @unit@) processed in the indicated time.
-	 */
+    /* End a benchmark.  The @ident@ and @unit@ arguments are as for
+     * @bbench@.  If @tm@ is zero then the measurement failed; otherwise
+     * @tm->n@ counts total number of things (operations or bytes, as
+     * indicated by @unit@) processed in the indicated time.
+     */
 
   void (*report)(struct tvec_output */*o*/, unsigned /*level*/,
 		 const char */*msg*/, va_list */*ap*/);
-	/* Report a message.  The driver should ideally report the filename
-	 * (@infile@) and line number (@lno@) prompting the error.
-	 */
+    /* Report a message.  The driver should ideally report the filename
+     * (@infile@) and line number (@lno@) prompting the error.
+     */
 
   void (*destroy)(struct tvec_output */*o*/);
-	/* Release any resources acquired by the driver. */
+    /* Release any resources acquired by the driver. */
 };
 
+#define TVEC_LEVELS(_)							\
+	_(NOTE, "notice", 4)						\
+	_(ERR, "ERROR", 8)
+
 enum {
-  TVLEV_NOTE = 4,			/* notice */
-  TVLEV_ERR = 8				/* error */
+#define TVEC_DEFLEVEL(tag, name, val) TVLEV_##tag = val,
+  TVEC_LEVELS(TVEC_DEFLEVEL)
+#undef TVEC_DEFLEVEL
+  TVLEV_LIMIT
 };
 
 /*----- Session lifecycle -------------------------------------------------*/
@@ -640,7 +667,7 @@ extern int tvec_end(struct tvec_state */*tv*/);
  *		@const char *infile@ = the name of the input file
  *		@FILE *fp@ = stream to read from
  *
- * Returns:	Zero on success, @-1@ on error.
+ * Returns:	Zero on success, %$-1$% on error.
  *
  * Use:		Read test vector data from @fp@ and exercise test functions.
  *		THe return code doesn't indicate test failures: it's only
@@ -684,7 +711,7 @@ extern void tvec_parseargs(int /*argc*/, char */*argv*/[],
  *		@const char *file@ = pathname of file to read
  *		@const char *arg@ = argument to interpret
  *
- * Returns:	Zero on success, @-1@ on error.
+ * Returns:	Zero on success, %$-1$% on error.
  *
  * Use:		Read test vector data from stdin or a named file.  The
  *		@tvec_readarg@ function reads from stdin if @arg@ is `%|-|%',
@@ -700,7 +727,7 @@ extern int tvec_readarg(struct tvec_state */*tv*/, const char */*arg*/);
  * Arguments:	@struct tvec_state *tv@ = test vector state
  *		@const char *dflt@ = defsault filename or null
  *
- * Returns:	Zero on success, @-1@ on error.
+ * Returns:	Zero on success, %$-1$% on error.
  *
  * Use:		Reads from the default test vector data.  If @file@ is null,
  *		then read from standard input, unless that's a terminal; if
@@ -719,7 +746,7 @@ extern int tvec_readdflt(struct tvec_state */*tv*/, const char */*file*/);
  *		@int *argpos_inout@ = current argument position (updated)
  *		@const char *dflt@ = default filename or null
  *
- * Returns:	Zero on success, @-1@ on error.
+ * Returns:	Zero on success, %$-1$% on error.
  *
  * Use:		Reads from the sources indicated by the command-line
  *		arguments, in order, interpreting each as for @tvec_readarg@;
@@ -764,8 +791,9 @@ extern int tvec_main(int /*argc*/, char */*argv*/[],
  *		the @setup@ function fails.
  */
 
-extern void PRINTF_LIKE(2, 3)
-  tvec_skipgroup(struct tvec_state */*tv*/, const char */*excuse*/, ...);
+extern PRINTF_LIKE(2, 3)
+  void tvec_skipgroup(struct tvec_state */*tv*/,
+		      const char */*excuse*/, ...);
 extern void tvec_skipgroup_v(struct tvec_state */*tv*/,
 			     const char */*excuse*/, va_list */*ap*/);
 
@@ -781,46 +809,11 @@ extern void tvec_skipgroup_v(struct tvec_state */*tv*/,
  *		the @before@ function fails.
  */
 
-extern void PRINTF_LIKE(2, 3)
-  tvec_skip(struct tvec_state */*tv*/, const char */*excuse*/, ...);
+extern PRINTF_LIKE(2, 3)
+  void tvec_skip(struct tvec_state */*tv*/, const char */*excuse*/, ...);
 extern void tvec_skip_v(struct tvec_state */*tv*/,
 			const char */*excuse*/, va_list */*ap*/);
 
-/* --- @tvec_resetoutputs@ --- *
- *
- * Arguments:	@struct tvec_state *tv@ = test-vector state
- *
- * Returns:	---
- *
- * Use:		Reset (releases and reinitializes) the output registers in
- *		the test state.  This is mostly of use to test environment
- *		@run@ functions, between invocations of the test function.
- */
-
-extern void tvec_resetoutputs(struct tvec_state */*tv*/);
-
-extern void tvec_initregs(struct tvec_state */*tv*/);
-extern void tvec_releaseregs(struct tvec_state */*tv*/);
-
-/* --- @tvec_checkregs@ --- *
- *
- * Arguments:	@struct tvec_state *tv@ = test-vector state
- *
- * Returns:	Zero on success, @-1@ on mismatch.
- *
- * Use:		Compare the active output registers (according to the current
- *		test group definition) with the corresponding input register
- *		values.  A mismatch occurs if the two values differ
- *		(according to the register type's @eq@ method), or if the
- *		input is live but the output is dead.
- *
- *		This function only checks for a mismatch and returns the
- *		result; it takes no other action.  In particular, it doesn't
- *		report a failure, or dump register values.
- */
-
-extern int tvec_checkregs(struct tvec_state */*tv*/);
-
 /* --- @tvec_fail@, @tvec_fail_v@ --- *
  *
  * Arguments:	@struct tvec_state *tv@ = test-vector state
@@ -838,8 +831,8 @@ extern int tvec_checkregs(struct tvec_state */*tv*/);
  *		safely be left null if the test function is run only once.
  */
 
-extern void PRINTF_LIKE(2, 3)
-  tvec_fail(struct tvec_state */*tv*/, const char */*detail*/, ...);
+extern PRINTF_LIKE(2, 3)
+  void tvec_fail(struct tvec_state */*tv*/, const char */*detail*/, ...);
 extern void tvec_fail_v(struct tvec_state */*tv*/,
 			const char */*detail*/, va_list */*ap*/);
 
@@ -865,6 +858,55 @@ extern void tvec_dumpreg(struct tvec_state */*tv*/,
 			 unsigned /*disp*/, const union tvec_regval */*rv*/,
 			 const struct tvec_regdef */*rd*/);
 
+/* --- @tvec_initregs@, @tvec_releaseregs@ --- *
+ *
+ * Arguments:	@struct tvec_state *tv@ = test-vector state
+ *
+ * Returns:	---
+ *
+ * Use:		Initialize or release, respectively, the registers required
+ *		by the current test.  All of the registers, both input and
+ *		output, are effected.  Initialized registers are not marked
+ *		live.
+ */
+
+extern void tvec_initregs(struct tvec_state */*tv*/);
+extern void tvec_releaseregs(struct tvec_state */*tv*/);
+
+/* --- @tvec_resetoutputs@ --- *
+ *
+ * Arguments:	@struct tvec_state *tv@ = test-vector state
+ *
+ * Returns:	---
+ *
+ * Use:		Reset (releases and reinitializes) the output registers in
+ *		the test state.  This is mostly of use to test environment
+ *		@run@ functions, between invocations of the test function.
+ *		Output registers are marked live if and only if the
+ *		corresponding input register is live.
+ */
+
+extern void tvec_resetoutputs(struct tvec_state */*tv*/);
+
+/* --- @tvec_checkregs@ --- *
+ *
+ * Arguments:	@struct tvec_state *tv@ = test-vector state
+ *
+ * Returns:	Zero on success, %$-1$% on mismatch.
+ *
+ * Use:		Compare the active output registers (according to the current
+ *		test group definition) with the corresponding input register
+ *		values.  A mismatch occurs if the two values differ
+ *		(according to the register type's @eq@ method), or if the
+ *		input is live but the output is dead.
+ *
+ *		This function only checks for a mismatch and returns the
+ *		result; it takes no other action.  In particular, it doesn't
+ *		report a failure, or dump register values.
+ */
+
+extern int tvec_checkregs(struct tvec_state */*tv*/);
+
 /* --- @tvec_mismatch@ --- *
  *
  * Arguments:	@struct tvec_state *tv@ = test-vector state
@@ -896,8 +938,8 @@ extern void tvec_mismatch(struct tvec_state */*tv*/, unsigned /*f*/);
  *		obvious way.
  */
 
-extern void PRINTF_LIKE(2, 3)
-  tvec_check(struct tvec_state */*tv*/, const char */*detail*/, ...);
+extern PRINTF_LIKE(2, 3)
+  void tvec_check(struct tvec_state */*tv*/, const char */*detail*/, ...);
 extern void tvec_check_v(struct tvec_state */*tv*/,
 			 const char */*detail*/, va_list */*ap*/);
 
@@ -994,13 +1036,13 @@ extern void tvec_begintest(struct tvec_state */*tv*/,
 #define TVEC_BEGINTEST(tv)						\
 	do tvec_begintest(tv, __FILE__, __LINE__); while (0)
 
-/* --- *tvec_endtest@ --- *
+/* --- @tvec_endtest@ --- *
  *
  * Arguments:	@struct tvec_state *tv@ = test-vector state
  *
  * Returns:	---
  *
- * Use:		End a ad-hoc test case,  The statistics are updated and the
+ * Use:		End an ad-hoc test case,  The statistics are updated and the
  *		outcome is reported to the output formatter.
  */
 
@@ -1053,10 +1095,10 @@ extern void tvec_endtest(struct tvec_state */*tv*/);
  *		the failure message.
  */
 
-extern int PRINTF_LIKE(5, 6)
-  tvec_claim(struct tvec_state */*tv*/, int /*ok*/,
-	     const char */*file*/, unsigned /*lno*/,
-	     const char */*msg*/, ...);
+extern PRINTF_LIKE(5, 6)
+  int tvec_claim(struct tvec_state */*tv*/, int /*ok*/,
+		 const char */*file*/, unsigned /*lno*/,
+		 const char */*msg*/, ...);
 extern int tvec_claim_v(struct tvec_state */*tv*/, int /*ok*/,
 			const char */*file*/, unsigned /*lno*/,
 			const char */*msg*/, va_list */*ap*/);
@@ -1106,6 +1148,9 @@ struct tvec_benchctx {
   const struct tvec_benchenv *be;	/* environment configuration */
   struct bench_state *bst;		/* benchmark state */
   double dflt_target;			/* default time in seconds */
+  unsigned f;				/* flags */
+#define TVBF_SETTRG 1u			/*   set `@target' */
+#define TVBF_SETMASK (TVBF_SETTRG))	/*   mask of @TVBF_SET...@ */
   void *subctx;				/* subsidiary environment context */
 };
 
@@ -1123,7 +1168,7 @@ extern struct bench_state *tvec_benchstate;
  */
 
 extern tvec_envsetupfn tvec_benchsetup;
-extern tvec_envsetfn tvec_benchset;
+extern tvec_envfindvarfn tvec_benchfindvar;
 extern tvec_envbeforefn tvec_benchbefore;
 extern tvec_envrunfn tvec_benchrun;
 extern tvec_envafterfn tvec_benchafter;
@@ -1132,7 +1177,7 @@ extern tvec_envteardownfn tvec_benchteardown;
 #define TVEC_BENCHENV							\
   { sizeof(struct tvec_benchctx),					\
     tvec_benchsetup,							\
-    tvec_benchset,							\
+    tvec_benchfindvar,							\
     tvec_benchbefore,							\
     tvec_benchrun,							\
     tvec_benchafter,							\
@@ -1161,17 +1206,21 @@ extern void tvec_benchreport
 
 struct tvec_remotecomms {
   int infd, outfd;			/* input and output descriptors */
-  dbuf bin, bout;			/* input and output buffers */
+  dbuf bout;				/* output buffer */
+  unsigned char *bin;			/* input buffer */
+  size_t binoff, binlen, binsz;		/* input offset, length, and size */
+  size_t t;				/* temporary offset */
   unsigned f;				/* flags */
 #define TVRF_BROKEN 0x0001u		/*   communications have failed */
-					/*   bits 8--15 for upper layer */
 };
-#define TVEC_REMOTECOMMS_INIT { -1, -1, DBUF_INIT, DBUF_INIT, 0 }
+#define TVEC_REMOTECOMMS_INIT { -1, -1, DBUF_INIT, 0, 0, 0, 0, 0, 0 }
 
 struct tvec_remotectx {
   struct tvec_state *tv;		/* test vector state */
   struct tvec_remotecomms rc;		/* communication state */
   const struct tvec_remoteenv *re;	/* environment configuration */
+  void *subctx;				/* subenvironment context */
+  struct tvec_vardef vd;		/* temporary variable definition */
   unsigned ver;				/* protocol version */
   pid_t kid;				/* child process id */
   int errfd;				/* child stderr descriptor */
@@ -1179,20 +1228,39 @@ struct tvec_remotectx {
   dstr prgwant, progress;		/* progress: wanted/reported */
   unsigned exwant, exit;		/* exit status wanted/reported */
 #define TVRF_RCNMASK 0x0300u		/*   reconnection behaviour: */
-#define TVRCN_SKIP 0x0000u		/*     skip unless connected */
-#define TVRCN_DEMAND 0x0100u		/*     connect on demand */
+#define TVRCN_DEMAND 0x0000u		/*     connect on demand */
+#define TVRCN_SKIP 0x0100u		/*     skip unless connected */
 #define TVRCN_FORCE 0x0200u		/*     force reconnection */
 #define TVRF_MUFFLE 0x0400u		/*   muffle child stderr */
+#define TVRF_SETEXIT 0x0800u		/*   set `@exit' */
+#define TVRF_SETPRG 0x1000u		/*   set `@progress' */
+#define TVRF_SETRCN 0x2000u		/*   set `@reconnect' */
+#define TVRF_SETMASK (TVRF_SETEXIT | TVRF_SETPRG | TVRF_SETRCN)
+					/*   mask of @TVTF_SET...@ */
 };
 
 typedef int tvec_connectfn(pid_t */*kid_out*/, int */*infd_out*/,
 			   int */*outfd_out*/, int */*errfd_out*/,
 			   struct tvec_state */*tv*/,
 			   const struct tvec_remoteenv */*env*/);
+  /* A connection function.  On entry, @tv@ holds the test-vector state, and
+   * @env@ is the test group's remote environment structure, which will
+   * typically really be some subclass of @struct tvec_remoteenv@ containing
+   * additional parameters for establishing the child process.
+   *
+   * On successful completion, the function stores input and output
+   * descriptors (which need not be distinct) in @*infd_out@ and
+   * @*outfd_out@, and returns zero; if it creates a child process, it should
+   * additionally store the child's process-id in @*kid_out@ and store in
+   * @*errfd_out@ a descriptor from which the child's error output can be
+   * read.  On error, the function should report an appropriate message via
+   * @tvec_error@ and return %$-1$%.
+   */
 
 struct tvec_remoteenv_slots {
   tvec_connectfn *connect;		/* connection function */
   const struct tvec_env *env;		/* subsidiary environment */
+  unsigned dflt_reconn;			/* default reconnection */
 };
 
 struct tvec_remoteenv {
@@ -1227,35 +1295,155 @@ union tvec_remoteenv_subclass_kludge {
   struct tvec_remoteexec exec;
 };
 
+/* Exit status.
+ *
+ * We don't use the conventional encoding returned by the @wait@(2) family of
+ * system calls because it's too hard for our flags type to decode.  Instead,
+ * we use our own encoding.
+ *
+ * The exit code or signal number ends up in the `value' field in the low 12
+ * bits; bit 12 is set if the value field holds a signal, and it if holds an
+ * exit code.  Bits 13--15 hold a code which describes the status of a child
+ * process or connection.
+ */
+#define TVXF_VALMASK 0x0fffu		/* value (exit code or signal) */
+#define TVXF_SIG 0x1000u		/* value is signal, not exit code */
+#define TVXF_CAUSEMASK 0xe000u		/* mask for cause bits */
+#define TVXST_RUN 0x0000u		/*   still running */
+#define TVXST_EXIT 0x2000u		/*   child exited */
+#define TVXST_KILL 0x4000u		/*   child killed by signal */
+#define TVXST_CONT 0x6000u		/*   child continued (?) */
+#define TVXST_STOP 0x8000u		/*   child stopped (?) */
+#define TVXST_DISCONN 0xa000u		/*   disconnected */
+#define TVXST_UNK 0xc000u		/*   unknown */
+#define TVXST_ERR 0xe000u	      /*   local error prevented diagnosis */
+
+/* Remote environment. */
 extern tvec_envsetupfn tvec_remotesetup;
-extern tvec_envsetfn tvec_remoteset;
+extern tvec_envfindvarfn tvec_remotefindvar;
+extern tvec_envbeforefn tvec_remotebefore;
 extern tvec_envrunfn tvec_remoterun;
 extern tvec_envafterfn tvec_remoteafter;
 extern tvec_envteardownfn tvec_remoteteardown;
 #define TVEC_REMOTEENV							\
   { sizeof(struct tvec_remotectx),					\
     tvec_remotesetup,							\
-    tvec_remoteset,							\
-    0,									\
+    tvec_remotefindvar,							\
+    tvec_remotebefore,							\
     tvec_remoterun,							\
     tvec_remoteafter,							\
     tvec_remoteteardown }
 
-extern int tvec_setprogress(const char */*status*/);
+/* --- @tvec_setprogress@, @tvec_setprogress_v@ --- *
+ *
+ * Arguments:	@const char *status@ = progress status token format
+ *		@va_list ap@ = argument tail
+ *
+ * Returns:	---
+ *
+ * Use:		Reports the progress of a test execution to the client.
+ *
+ *		The framework makes use of tokens beginning with %|%|%:
+ *
+ *		  * %|%IDLE|%: during the top-level server code;
+ *
+ *		  * %|%SETUP|%: during the enclosing environment's @before@
+ *		    function;
+ *
+ *		  * %|%RUN|%: during the environment's @run@ function, or the
+ *		    test function; and
+ *
+ *		  * %|%DONE|%: during the enclosing environment's @after@
+ *		    function.
+ *
+ *		The intent is that a test can use the progress token to check
+ *		that a function which is expected to crash does so at the
+ *		correct point, so it's expected that more complex test
+ *		functions and/or environments will set their own progress
+ *		tokens to reflect what's going on.
+ */
+
+extern PRINTF_LIKE(1, 2) int tvec_setprogress(const char */*status*/, ...);
+extern int tvec_setprogress_v(const char */*status*/, va_list */*ap*/);
+
+/* --- @tvec_remoteserver@ --- *
+ *
+ * Arguments:	@int infd@, @int outfd@ = input and output file descriptors
+ *		@const struct tvec_config *config@ = test configuration
+ *
+ * Returns:	Suggested exit code.
+ *
+ * Use:		Run a test server, reading packets from @infd@ and writing
+ *		responses and notifications to @outfd@, and invoking tests as
+ *		described by @config@.
+ *
+ *		This function is not particularly general purpose.  It
+ *		expects to `take over' the process, and makes use of private
+ *		global variables.
+ */
 
 extern int tvec_remoteserver(int /*infd*/, int /*outfd*/,
 			     const struct tvec_config */*config*/);
 
 extern tvec_connectfn tvec_fork, tvec_exec;
 
-#define TVEC_REMOTEFORK( subenv, tests)					\
+#define TVEC_REMOTEFORK(subenv, tests)					\
 	TVEC_REMOTEENV, { tvec_fork, subenv }, { tests }
 
 #define TVEC_REMOTEEXEC(subenv, args)					\
 	TVEC_REMOTEENV, { tvec_exec, subenv }, { args }
 
+/*----- Timeouts ----------------------------------------------------------*/
+
+struct tvec_timeoutenv {
+  struct tvec_env _env;
+  int timer;			/* the timer (@ITIMER_...@) */
+  double t;				/* time to wait (in seconds) */
+  const struct tvec_env *env;		/* subsidiary environment */
+};
+
+struct tvec_timeoutctx {
+  const struct tvec_timeoutenv *te;	/* saved environment description */
+  int timer;				/* timer code (as overridden) */
+  double t;				/* time to wait (as overridden) */
+  unsigned f;				/* flags */
+#define TVTF_SETTMO 1u			/*   set `@timeout' */
+#define TVTF_SETTMR 2u			/*   set `@timer' */
+#define TVTF_SETMASK (TVTF_SETTMO | TVTF_SETTMR)
+					/*   mask of @TVTF_SET...@ */
+  void *subctx;
+};
+
+extern tvec_envsetupfn tvec_timeoutsetup;
+extern tvec_envfindvarfn tvec_timeoutfindvar;
+extern tvec_envbeforefn tvec_timeoutbefore;
+extern tvec_envrunfn tvec_timeoutrun;
+extern tvec_envafterfn tvec_timeoutafter;
+extern tvec_envteardownfn tvec_timeoutteardown;
+#define TVEC_TIMEOUTENV							\
+	{ sizeof(struct tvec_timeoutctx),				\
+	  tvec_timeoutsetup,						\
+	  tvec_timeoutfindvar,						\
+	  tvec_timeoutbefore,						\
+	  tvec_timeoutrun,						\
+	  tvec_timeoutafter,						\
+	  tvec_timeoutteardown }
+#define TVEC_TIMEOUTINIT(timer, t) TVEC_TIMEOUTENV, timer, t
+
 /*----- Output functions --------------------------------------------------*/
 
+/* --- @tvec_strlevel@ --- *
+ *
+ * Arguments:	@unsigned level@ = level code
+ *
+ * Returns:	A human-readable description.
+ *
+ * Use:		Converts a level code into something that you can print in a
+ *		message.
+ */
+
+extern  const char *tvec_strlevel(unsigned /*level*/);
+
 /* --- @tvec_report@, @tvec_report_v@ --- *
  *
  * Arguments:	@struct tvec_state *tv@ = test-vector state
@@ -1267,9 +1455,9 @@ extern tvec_connectfn tvec_fork, tvec_exec;
  *		@TVLEV_ERR@ or higher force a nonzero exit code.
  */
 
-extern void PRINTF_LIKE(3, 4)
-  tvec_report(struct tvec_state */*tv*/, unsigned /*level*/,
-	      const char */*msg*/, ...);
+extern PRINTF_LIKE(3, 4)
+  void tvec_report(struct tvec_state */*tv*/, unsigned /*level*/,
+		   const char */*msg*/, ...);
 extern void tvec_report_v(struct tvec_state */*tv*/, unsigned /*level*/,
 			  const char */*msg*/, va_list */*ap*/);
 
@@ -1278,7 +1466,7 @@ extern void tvec_report_v(struct tvec_state */*tv*/, unsigned /*level*/,
  * Arguments:	@struct tvec_state *tv@ = test-vector state
  *		@const char *msg@, @va_list ap@ = error message
  *
- * Returns:	The @tvec_error@ function returns @-1@ as a trivial
+ * Returns:	The @tvec_error@ function returns %$-1$% as a trivial
  *		convenience; @tvec_notice@ does not return a value.
  *
  * Use:		Report an error or a notice.  Errors are distinct from test
@@ -1288,10 +1476,10 @@ extern void tvec_report_v(struct tvec_state */*tv*/, unsigned /*level*/,
  *		category.
  */
 
-extern int PRINTF_LIKE(2, 3)
-  tvec_error(struct tvec_state */*tv*/, const char */*msg*/, ...);
-extern void PRINTF_LIKE(2, 3)
-  tvec_notice(struct tvec_state */*tv*/, const char */*msg*/, ...);
+extern PRINTF_LIKE(2, 3)
+  int tvec_error(struct tvec_state */*tv*/, const char */*msg*/, ...);
+extern PRINTF_LIKE(2, 3)
+  void tvec_notice(struct tvec_state */*tv*/, const char */*msg*/, ...);
 
 /* --- @tvec_humanoutput@ --- *
  *
@@ -1319,16 +1507,16 @@ extern struct tvec_output *tvec_humanoutput(FILE */*fp*/);
  *		(`Test Anything Protocol') format.
  *
  *		TAP comes from the Perl community, but has spread rather
- *		further.  This driver produces TAP version 13.  The driver
- *		produces a TAP `test point' -- i.e., a result reported as
- *		`ok' or `not ok' -- for each input test group.  Failure
- *		reports and register dumps are produced as diagnostic
- *		messages before the final group result.  (TAP permits
- *		structuerd YAML data after the test-point result, which could
- *		be used to report details, but (a) postponing the details
- *		until after the report is inconvenient, and (b) there is no
- *		standardization for the YAML anyway, so in practice it's no
- *		more useful than the unstructured diagnostics.
+ *		further.  This driver produces TAP version 14, but pretends
+ *		to be version 13.  The driver produces a TAP `test point' --
+ *		i.e., a result reported as `ok' or `not ok' -- for each input
+ *		test group.  Failure reports and register dumps are produced
+ *		as diagnostic messages before the final group result.  (TAP
+ *		permits structuerd YAML data after the test-point result,
+ *		which could be used to report details, but (a) postponing the
+ *		details until after the report is inconvenient, and (b) there
+ *		is no standardization for the YAML anyway, so in practice
+ *		it's no more useful than the unstructured diagnostics.
  */
 
 extern struct tvec_output *tvec_tapoutput(FILE */*fp*/);
@@ -1377,7 +1565,7 @@ extern struct tvec_output *tvec_dfltout(FILE */*fp*/);
  *		@unsigned nr@ = number of entries in the @rv@ vector
  *		@size_t regsz@ = true size of each element of @rv@
  *
- * Returns:	Zero on success, @-1@ on failure.
+ * Returns:	Zero on success, %$-1$% on failure.
  *
  * Use:		Serialize a collection of register values.
  *
@@ -1400,7 +1588,7 @@ extern int tvec_serialize(const struct tvec_reg */*rv*/, buf */*b*/,
  *		@unsigned nr@ = number of entries in the @rv@ vector
  *		@size_t regsz@ = true size of each element of @rv@
  *
- * Returns:	Zero on success, @-1@ on failure.
+ * Returns:	Zero on success, %$-1$% on failure.
  *
  * Use:		Deserialize a collection of register values.
  *
@@ -1435,26 +1623,13 @@ extern int tvec_deserialize(struct tvec_reg */*rv*/, buf */*b*/,
  *     current line number.
  */
 
-/* --- @tvec_skipspc@ --- *
- *
- * Arguments:	@struct tvec_state *tv@ = test-vector state
- *
- * Returns:	---
- *
- * Use:		Advance over any whitespace characters other than newlines.
- *		This will stop at `;', end-of-file, or any other kind of
- *		non-whitespace; and it won't consume a newline.
- */
-
-extern void tvec_skipspc(struct tvec_state */*tv*/);
-
 /* --- @tvec_syntax@, @tvec_syntax_v@ --- *
  *
  * Arguments:	@struct tvec_state *tv@ = test-vector state
  *		@int ch@ = the character found (in @fgetc@ format)
  *		@const char *expect@, @va_list ap@ = what was expected
  *
- * Returns:	@-1@
+ * Returns:	%$-1$%.
  *
  * Use:		Report a syntax error quoting @ch@ and @expect@.  If @ch@ is
  *		a newline, then back up so that it can be read again (e.g.,
@@ -1462,18 +1637,57 @@ extern void tvec_skipspc(struct tvec_state */*tv*/);
  *		advance the line number).
  */
 
-extern int PRINTF_LIKE(3, 4)
-  tvec_syntax(struct tvec_state */*tv*/, int /*ch*/,
-	      const char */*expect*/, ...);
+extern PRINTF_LIKE(3, 4)
+  int tvec_syntax(struct tvec_state */*tv*/, int /*ch*/,
+		  const char */*expect*/, ...);
 extern int tvec_syntax_v(struct tvec_state */*tv*/, int /*ch*/,
 			 const char */*expect*/, va_list */*ap*/);
 
+/* --- @tvec_unkreg@ --- *
+ *
+ * Arguments:	@struct tvec_state *tv@ = test-vector state
+ *		@const char *name@ = register or pseudoregister name
+ *
+ * Returns:	%$-1$%.
+ *
+ * Use:		Reports an error that the register or pseudoregister is
+ *		unrecognized.
+ */
+
+extern int tvec_unkreg(struct tvec_state */*tv*/, const char */*name*/);
+
+/* --- @tvec_dupreg@ --- *
+ *
+ * Arguments:	@struct tvec_state *tv@ = test-vector state
+ *		@const char *name@ = register or pseudoregister name
+ *
+ * Returns:	%$-1$%.
+ *
+ * Use:		Reports an error that the register or pseudoregister has been
+ *		assigned already in the current test.
+ */
+
+extern int tvec_dupreg(struct tvec_state */*tv*/, const char */*name*/);
+
+/* --- @tvec_skipspc@ --- *
+ *
+ * Arguments:	@struct tvec_state *tv@ = test-vector state
+ *
+ * Returns:	---
+ *
+ * Use:		Advance over any whitespace characters other than newlines.
+ *		This will stop at `;', end-of-file, or any other kind of
+ *		non-whitespace; and it won't consume a newline.
+ */
+
+extern void tvec_skipspc(struct tvec_state */*tv*/);
+
 /* --- @tvec_flushtoeol@ --- *
  *
  * Arguments:	@struct tvec_state *tv@ = test-vector state
  *		@unsigned f@ = flags (@TVFF_...@)
  *
- * Returns:	Zero on success, @-1@ on error.
+ * Returns:	Zero on success, %$-1$% on error.
  *
  * Use:		Advance to the start of the next line, consuming the
  *		preceding newline.
@@ -1493,7 +1707,7 @@ extern int tvec_flushtoeol(struct tvec_state */*tv*/, unsigned /*f*/);
  *
  * Arguments:	@struct tvec_state *tv@ = test-vector state
  *
- * Returns:	Zero if there is a next token which can be read; @-1@ if no
+ * Returns:	Zero if there is a next token which can be read; %$-1$% if no
  *		token is available.
  *
  * Use:		Advance to the next whitespace-separated token, which may be
@@ -1507,21 +1721,22 @@ extern int tvec_flushtoeol(struct tvec_state */*tv*/, unsigned /*f*/);
  *
  *		If this function returns zero, then the next character in the
  *		file begins a suitable token which can be read and
- *		processed.  If it returns @-1@ then there is no such token,
+ *		processed.  If it returns %$-1$% then there is no such token,
  *		and the file position is left correctly.  The line number
  *		count is updated appropriately.
  */
 
 extern int tvec_nexttoken(struct tvec_state */*tv*/);
 
-/* --- @tvec_readword@ --- *
+/* --- @tvec_readword@, @tvec_readword_v@ --- *
  *
  * Arguments:	@struct tvec_state *tv@ = test-vector state
  *		@dstr *d@ = string to append the word to
+ *		@const char **p_inout@ = pointer into string, updated
  *		@const char *delims@ = additional delimiters to stop at
  *		@const char *expect@, @va_list ap@ = what was expected
  *
- * Returns:	Zero on success, @-1@ on failure.
+ * Returns:	Zero on success, %$-1$% on failure.
  *
  * Use:		A `word' consists of characters other than whitespace, null
  *		characters, and other than those listed in @delims@;
@@ -1530,8 +1745,8 @@ extern int tvec_nexttoken(struct tvec_state */*tv*/);
  *		include `;' in @delims@.  This is a common behaviour.)
  *
  *		If there is no word beginning at the current file position,
- *		then return @-1@; furthermore, if @expect@ is not null, then
- *		report an appropriate error via @tvec_syntax@.
+ *		then return %$-1$%; furthermore, if @expect@ is not null,
+ *		then report an appropriate error via @tvec_syntax@.
  *
  *		Otherwise, the word is accumulated in @d@ and zero is
  *		returned; if @d@ was not empty at the start of the call, the
@@ -1540,14 +1755,23 @@ extern int tvec_nexttoken(struct tvec_state */*tv*/);
  *		word constituents, a null terminator is written to @d@, and
  *		it is safe to treat the string in @d@ as being null-
  *		terminated.
+ *
+ *		If @p_inout@ is not null, then @*p_inout@ must be a pointer
+ *		into @d->buf@, which will be adjusted so that it will
+ *		continue to point at the same position even if the buffer is
+ *		reallocated.  As a subtle tweak, if @*p_inout@ initially
+ *		points at the end of the buffer, then it will be adjusted to
+ *		point at the beginning of the next word, rather than at the
+ *		additional intervening space.
  */
 
-extern int PRINTF_LIKE(4, 5)
-  tvec_readword(struct tvec_state */*tv*/, dstr */*d*/,
-		const char */*delims*/, const char */*expect*/, ...);
+extern PRINTF_LIKE(5, 6)
+  int tvec_readword(struct tvec_state */*tv*/, dstr */*d*/,
+		    const char **/*p_inout*/, const char */*delims*/,
+		    const char */*expect*/, ...);
 extern int tvec_readword_v(struct tvec_state */*tv*/, dstr */*d*/,
-			   const char */*delims*/, const char */*expect*/,
-			   va_list */*ap*/);
+			   const char **/*p_inout*/, const char */*delims*/,
+			   const char */*expect*/, va_list */*ap*/);
 
 /*----- Integer types: signed and unsigned --------------------------------*/
 
@@ -1651,10 +1875,11 @@ extern int tvec_claimeq_uint(struct tvec_state */*tv*/,
 
 /*----- Floating-point type -----------------------------------------------*/
 
-/* Floating-point are either NaN (`#nan', if supported by the platform);
- * positive or negative infinity (`#inf', `+#inf', or, preferred, `#+inf',
- * and `-#inf' or, preferred, `#-inf', if supported by the platform), or a
- * number in strtod(3) syntax.
+/* Floating-point values are either NaN (%|#nan|%, if supported by the
+ * platform); positive or negative infinity (%|#inf|%, %|+#inf|%, or
+ * %|#+inf|% (preferring the last), and %|-#inf|% or %|#-inf|% (preferring
+ * the latter), if supported by the platform); or a number in strtod(3)
+ * syntax.
  *
  * The comparison rules for floating-point numbers are complex: see
  * @tvec_claimeqish_float@ for details.
@@ -1755,6 +1980,37 @@ extern int tvec_claimeq_float(struct tvec_state */*tv*/,
 #define TVEC_CLAIMEQ_FLOAT(tv, f0, f1)					\
 	(tvec_claimeq_float(tv, f0, f1, __FILE__, __LINE__, #f0 " /= " #f1))
 
+extern const struct tvec_floatinfo tvflt_finite, tvflt_nonneg;
+
+/*----- Durations ---------------------------------------------------------*/
+
+/* A duration measures a time interval in seconds.  The input format consists
+ * of a nonnegative decimal floating-point number in @strtod@ format followed
+ * by an optional unit specification.
+ *
+ * No @tvec_claimeq_...@ function is provided for durations: use
+ * @tvec_claimeq_float@.
+ */
+
+extern const struct tvec_regty tvty_duration;
+
+/* --- @tvec_parsedurunit@ --- *
+ *
+ * Arguments:	@double *scale_out@ = where to leave the scale
+ *		@const char **p_inout@ = input unit string, updated
+ *
+ * Returns:	Zero on success, %$-1$% on error.
+ *
+ * Use:		If @*p_inout@ begins with a unit string followed by the end
+ *		of the string or some non-alphanumeric character, then store
+ *		the corresponding scale factor in @*scale_out@, advance
+ *		@*p_inout@ past the unit string, and return zero.  Otherwise,
+ *		return %$-1$%.
+ */
+
+extern int tvec_parsedurunit(double */*scale_out*/,
+			     const char **/*p_inout*/);
+
 /*----- Enumerated types --------------------------------------------------*/
 
 /* An enumeration describes a set of values of some underlying type, each of
@@ -1770,7 +2026,7 @@ extern int tvec_claimeq_float(struct tvec_state */*tv*/,
  * On input, an enumerated value may be given by name or as a literal value.
  * For enumerations based on numeric types, the literal values can be written
  * in the same syntax as the underlying values.  For enumerations based on
- * pointers, the only permitted literal is `#nil', which denotes a null
+ * pointers, the only permitted literal is %|#nil|%, which denotes a null
  * pointer.  On output, names are preferred (with the underlying value given
  * in a comment).
  */
@@ -1871,18 +2127,19 @@ TVEC_MISCSLOTS(DECLCLAIM)
  * fields; more precisely, each name is associated with a value and a
  * covering bitmask.
  *
- * The input syntax is a sequence of items separated by `|' signs.  Each item
- * may be the symbolic name of a field value, or a literal unsigned integer.
- * The masks associated with the given symbolic names must be disjoint.  The
- * resulting numerical value is simply the bitwise OR of the given values.
+ * The input syntax is a sequence of items separated by `%|||%' signs.  Each
+ * item may be the symbolic name of a field value, or a literal unsigned
+ * integer.  The masks associated with the given symbolic names must be
+ * disjoint.  The resulting numerical value is simply the bitwise OR of the
+ * given values.
  *
  * On output, the table of symbolic names and their associated values and
  * masks is repeatedly scanned, in order, to find disjoint matches -- i.e.,
  * entries whose value matches the target value in the bit positions
  * indicated by the mask, and whose mask doesn't overlap with any previously
- * found matches; the names are then output, separated by `|'.  Any remaining
- * nonzero bits not covered by any of the matching masks are output as a
- * single literal integer, in hex.
+ * found matches; the names are then output, separated by `%|||%'.  Any
+ * remaining nonzero bits not covered by any of the matching masks are output
+ * as a single literal integer, in hex.
  */
 
 extern const struct tvec_regty tvty_flags;
@@ -1945,8 +2202,9 @@ extern int tvec_claimeq_flags(struct tvec_state */*tv*/,
 /* A character value holds a character, as read by @fgetc@.  The special
  * @EOF@ value can also be represented.
  *
- * On input, a character value can be given by name, with a leading `%|#|%';
- * or a character or `%|\|%'-escape sequence, optionally in single quotes.
+ * On input, a character value can be given by symbolic name, with a leading
+ * `%|#|%'; or a character or `%|\|%'-escape sequence, optionally in single
+ * quotes.
  *
  * The following escape sequences and character names are recognized.
  *
@@ -2063,6 +2321,9 @@ extern int tvec_claimeq_char(struct tvec_state */*tv*/,
  *   * `%|!repeat|% %$n$% %|{|% %%\textit{string}%% %|}|%', which includes
  *     %$n$% copies of the (compound) string.
  *
+ * The only difference between text and binary strings is that the initial
+ * coding scheme is %|bare|% for text strings and %|hex|% for binary strings.
+ *
  * Either kind of string can contain internal nul characters.  A trailing nul
  * is appended -- beyond the stated input length -- to input strings as a
  * convenience to test functions.  Test functions may include such a nul
@@ -2072,9 +2333,9 @@ extern int tvec_claimeq_char(struct tvec_state */*tv*/,
  * string (in bytes) will be checked against the permitted range.
  */
 
-extern const struct tvec_regty tvty_string, tvty_bytes;
+extern const struct tvec_regty tvty_text, tvty_bytes;
 
-/* --- @tvec_claimeq_string@, @TVEC_CLAIMEQ_STRING@ --- *
+/* --- @tvec_claimeq_text@, @TVEC_CLAIMEQ_TEXT@ --- *
  *
  * Arguments:	@struct tvec_state *tv@ = test-vector state
  *		@const char *p0@, @size_t sz0@ = first string with length
@@ -2092,22 +2353,22 @@ extern const struct tvec_regty tvty_string, tvty_bytes;
  *		mismatched values are dumped: @p0@ is printed as the output
  *		value and @p1@ is printed as the input reference.
  *
- *		The @TVEC_CLAIM_STRING@ macro is similar, only it (a)
+ *		The @TVEC_CLAIM_TEXT@ macro is similar, only it (a)
  *		identifies the file and line number of the call site
  *		automatically, and (b) implicitly quotes the source text of
  *		the @ch0@ and @ch1@ arguments in the failure message.
  */
 
-extern int tvec_claimeq_string(struct tvec_state */*tv*/,
-			       const char */*p0*/, size_t /*sz0*/,
-			       const char */*p1*/, size_t /*sz1*/,
-			       const char */*file*/, unsigned /*lno*/,
-			       const char */*expr*/);
-#define TVEC_CLAIMEQ_STRING(tv, p0, sz0, p1, sz1)			\
-	(tvec_claimeq_string(tv, p0, sz0, p1, sz1, __FILE__, __LINE__,	\
-			     #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
+extern int tvec_claimeq_text(struct tvec_state */*tv*/,
+			     const char */*p0*/, size_t /*sz0*/,
+			     const char */*p1*/, size_t /*sz1*/,
+			     const char */*file*/, unsigned /*lno*/,
+			     const char */*expr*/);
+#define TVEC_CLAIMEQ_TEXT(tv, p0, sz0, p1, sz1)				\
+	(tvec_claimeq_text(tv, p0, sz0, p1, sz1, __FILE__, __LINE__,	\
+			   #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
 
-/* --- @tvec_claimeq_strz@, @TVEC_CLAIMEQ_STRZ@ --- *
+/* --- @tvec_claimeq_textz@, @TVEC_CLAIMEQ_TEXTZ@ --- *
  *
  * Arguments:	@struct tvec_state *tv@ = test-vector state
  *		@const char *p0, *p1@ = two strings to compare
@@ -2120,16 +2381,15 @@ extern int tvec_claimeq_string(struct tvec_state */*tv*/,
  * Use:		Check that strings at @p0@ and @p1@ are equal, as for
  *		@tvec_claimeq_string@, except that the strings are assumed
  *		null-terminated, so their lengths don't need to be supplied
- *		explicitly.  The macro is similarly like
- *		@TVEC_CLAIMEQ_STRING@.
+ *		explicitly.  The macro is similarly like @TVEC_CLAIMEQ_TEXT@.
  */
 
-extern int tvec_claimeq_strz(struct tvec_state */*tv*/,
-			     const char */*p0*/, const char */*p1*/,
-			     const char */*file*/, unsigned /*lno*/,
-			     const char */*expr*/);
-#define TVEC_CLAIMEQ_STRZ(tv, p0, p1)					\
-	(tvec_claimeq_strz(tv, p0, p1, __FILE__, __LINE__, #p0 " /= " #p1))
+extern int tvec_claimeq_textz(struct tvec_state */*tv*/,
+			      const char */*p0*/, const char */*p1*/,
+			      const char */*file*/, unsigned /*lno*/,
+			      const char */*expr*/);
+#define TVEC_CLAIMEQ_TEXTZ(tv, p0, p1)					\
+	(tvec_claimeq_textz(tv, p0, p1, __FILE__, __LINE__, #p0 " /= " #p1))
 
 /* --- @tvec_claimeq_bytes@, @TVEC_CLAIMEQ_BYTES@ --- *
  *
@@ -2164,7 +2424,7 @@ extern int tvec_claimeq_bytes(struct tvec_state */*tv*/,
 	(tvec_claimeq(tv, p0, sz0, p1, sz1, __FILE__, __LINE__,		\
 		      #p0 "[" #sz0 "] /= " #p1 "[" #sz1 "]"))
 
-/* --- @tvec_allocstring@, @tvec_allocbytes@ --- *
+/* --- @tvec_alloctext@, @tvec_allocbytes@ --- *
  *
  * Arguments:	@union tvec_regval *rv@ = register value
  *		@size_t sz@ = required size
@@ -2180,28 +2440,69 @@ extern int tvec_claimeq_bytes(struct tvec_state */*tv*/,
  *		the old buffer contents are simply discarded if reallocation
  *		is necessary.  Instead, use a @dbuf@ or @dstr@.
  *
- *		The @tvec_allocstring@ function sneakily allocates an extra
+ *		The @tvec_alloctext@ function sneakily allocates an extra
  *		byte for a terminating zero.  The @tvec_allocbytes@ function
  *		doesn't do this.
  */
 
-extern void tvec_allocstring(union tvec_regval */*rv*/, size_t /*sz*/);
+extern void tvec_alloctext(union tvec_regval */*rv*/, size_t /*sz*/);
 extern void tvec_allocbytes(union tvec_regval */*rv*/, size_t /*sz*/);
 
 /*----- Buffer type -------------------------------------------------------*/
 
 /* Buffer registers are primarily used for benchmarking.  Only a buffer's
- * size is significant: its contents are ignored on comparison and output,
- * and unspecified on input.
+ * allocation parameters are significant: its contents are ignored on
+ * comparison and output, and unspecified on input.
  *
- * The input is simply the buffer size, as an integer, optionally suffixed
- * with a unit `kB', `MB', `GB', `TB', `PB', `EB', `ZB', `YB' (with or
- * without the `B') denoting a power of 1024.  Units are used on output only
- * when the size would be expressed exactly.
+ * The input format gives the buffer's size, and an optional alignment
+ * specification, in the form %|SZ [`@' M [`+' A]]|%.  Each of %|SZ|%, %|M|%
+ * and %|A|% are sizes, as an integer, optionally suffixed with a unit `kB',
+ * `MB', `GB', `TB', `PB', `EB', `ZB', `YB' (with or without the `B')
+ * denoting a power of 1024.  The %|SZ|% gives the (effective) buffer size.
+ * %|M|% is the `alignment quantum' and %|A|% is the `alignment offset'; both
+ * default to zero, but if %|M|% is nonzero then the start of the buffer is
+ * aligned such that it is %|A|% more than a multiple of %|M|% bytes.  Note
+ * that %|M|% need not be a power of two, though this is common.
+ *
+ * Units other than `B' are used on output only when the size would be
+ * expressed exactly.
+ *
+ * Buffers are %%\emph{not}%% allocated by default.  In benchmarks, this is
+ * best done in a @before@ function.
+ *
+ * No @claimeq@ functions or macros are provided for buffers because they
+ * don't seem very useful.
  */
 
 extern const struct tvec_regty tvty_buffer;
 
+/* --- @tvec_initbuffer@ --- *
+ *
+ * Arguments:	@union tvec_regval *rv@ = register value
+ *		@const union tvec_regval *src@ = source buffer
+ *		@size_t sz@ = size to allocate
+ *
+ * Returns:	---
+ *
+ * Use:		Initialize the alignment parameters in @rv@ to match @src@,
+ *		and the size to @sz@.
+ */
+
+extern void tvec_initbuffer(union tvec_regval */*rv*/,
+			    const union tvec_regval */*src*/, size_t /*sz*/);
+
+/* --- @tvec_allocbuffer@ --- *
+ *
+ * Arguments:	@union tvec_regval *rv@ = register value
+ *
+ * Returns:	---
+ *
+ * Use:		Allocate @sz@ bytes to the buffer and fill the space with a
+ *		distinctive pattern.
+ */
+
+extern void tvec_allocbuffer(union tvec_regval */*rv*/);
+
 /*----- That's all, folks -------------------------------------------------*/
 
 #ifdef __cplusplus