+/* --- @tvec_main@ --- *
+ *
+ * Arguments: @int argc@ = number of command-line arguments
+ * @char *argv[]@ = vector of argument strings
+ * @const struct tvec_config *cofig@ = test vector configuration
+ * @const char *dflt@ = default filename or null
+ *
+ * Returns: Exit code.
+ *
+ * Use: All-in-one test vector front-end. Parse options from the
+ * command-line as for @tvec_parseargs@, and then process the
+ * remaining positional arguments as for @tvec_readargs@. The
+ * function constructs and disposes of a test vector state.
+ */
+
+extern int tvec_main(int /*argc*/, char */*argv*/[],
+ const struct tvec_config */*config*/,
+ const char */*dflt*/);
+
+/*----- Test processing ---------------------------------------------------*/
+
+/* --- @tvec_skipgroup@, @tvec_skipgroup_v@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const char *excuse@, @va_list *ap@ = reason why skipped
+ *
+ * Returns: ---
+ *
+ * Use: Skip the current group. This should only be called from a
+ * test environment @setup@ function; a similar effect occurs if
+ * the @setup@ function fails.
+ */
+
+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*/);
+
+/* --- @tvec_skip@, @tvec_skip_v@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const char *excuse@, @va_list *ap@ = reason why test skipped
+ *
+ * Returns: ---
+ *
+ * Use: Skip the current test. This should only be called from a
+ * test environment @run@ function; a similar effect occurs if
+ * the @before@ function fails.
+ */
+
+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_fail@, @tvec_fail_v@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const char *detail@, @va_list *ap@ = description of test
+ *
+ * Returns: ---
+ *
+ * Use: Report the current test as a failure. This function can be
+ * called multiple times for a single test, e.g., if the test
+ * environment's @run@ function invokes the test function
+ * repeatedly; but a single test that fails repeatedly still
+ * only counts as a single failure in the statistics. The
+ * @detail@ string and its format parameters can be used to
+ * distinguish which of several invocations failed; it can
+ * safely be left null if the test function is run only once.
+ */
+
+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*/);
+
+/* --- @tvec_dumpreg@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @unsigned disp@ = the register disposition (@TVRD_...@)
+ * @const union tvec_regval *tv@ = register value, or null
+ * @const struct tvec_regdef *rd@ = register definition
+ *
+ * Returns: ---
+ *
+ * Use: Dump a register value to the output. This is the lowest-
+ * level function for dumping registers, and calls the output
+ * formatter directly.
+ *
+ * Usually @tvec_mismatch@ is much more convenient. Low-level
+ * access is required for reporting `virtual' registers
+ * corresponding to test environment settings.
+ */
+
+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
+ * @unsigned f@ = flags (@TVMF_...@)
+ *
+ * Returns: ---
+ *
+ * Use: Dumps registers suitably to report a mismatch. The flag bits
+ * @TVMF_IN@ and @TVF_OUT@ select input-only and output
+ * registers. If both are reset then nothing happens.
+ * Suppressing the output registers may be useful, e.g., if the
+ * test function crashed rather than returning outputs.
+ */
+
+#define TVMF_IN 1u
+#define TVMF_OUT 2u
+extern void tvec_mismatch(struct tvec_state */*tv*/, unsigned /*f*/);
+
+/* --- @tvec_check@, @tvec_check_v@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const char *detail@, @va_list *ap@ = description of test
+ *
+ * Returns: ---
+ *
+ * Use: Check the register values, reporting a failure and dumping
+ * the registers in the event of a mismatch. This just wraps up
+ * @tvec_checkregs@, @tvec_fail@ and @tvec_mismatch@ in the
+ * obvious way.
+ */
+
+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*/);
+
+/*----- Ad-hoc testing ----------------------------------------------------*/
+
+/* --- @tvec_adhoc@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @struct tvec_test *t@ = space for a test definition
+ *
+ * Returns: ---
+ *
+ * Use: Begin ad-hoc testing, i.e., without reading a file of
+ * test-vector data.
+ *
+ * The structure at @t@ will be used to record information about
+ * the tests underway, which would normally come from a static
+ * test definition. The other functions in this section assume
+ * that @tvec_adhoc@ has been called.
+ */
+
+extern void tvec_adhoc(struct tvec_state */*tv*/, struct tvec_test */*t*/);
+
+/* --- @tvec_begingroup@, @TVEC_BEGINGROUP@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const char *name@ = name for this test group
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ *
+ * Returns: ---
+ *
+ * Use: Begin an ad-hoc test group with the given name. The @file@
+ * and @lno@ can be anything, but it's usually best if they
+ * refer to the source code performing the test: the macro
+ * @TVEC_BEGINGROUP@ does this automatically.
+ */
+
+extern void tvec_begingroup(struct tvec_state */*tv*/, const char */*name*/,
+ const char */*file*/, unsigned /*lno*/);
+#define TVEC_BEGINGROUP(tv, name) \
+ do tvec_begingroup(tv, name, __FILE__, __LINE__); while (0)
+
+/* --- @tvec_endgroup@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ *
+ * Returns: ---
+ *
+ * Use: End an ad-hoc test group. The statistics are updated and the
+ * outcome is reported to the output formatter.
+ */
+
+extern void tvec_endgroup(struct tvec_state */*tv*/);
+
+/* --- @TVEC_TESTGROUP@, @TVEC_TESTGROUP_TAG@ --- *
+ *
+ * Arguments: @tag@ = label-disambiguation tag
+ * @const struct tvec_state *tv = test-vector state
+ * @const char *name@ = test-group name
+ *
+ * Returns: ---
+ *
+ * Use: Control-structure macro: @TVEC_TESTGROUP(tv, name) stmt@
+ * establishes a test group with the given @name@ (attributing
+ * it to the source file and lie number), executes @stmt@, and
+ * ends the test group. If @stmt@ invokes @break@ then the test
+ * group is skipped. @TVEC_TESTGROUP_TAG@ is the same, with an
+ * additional @tag@ argument for use in higher-level macros.
+ */
+
+#define TVEC_TESTGROUP_TAG(tag, tv, name) \
+ MC_WRAP(tag##__around, \
+ { TVEC_BEGINGROUP(tv, name); }, \
+ { tvec_endgroup(tv); }, \
+ { if (!((tv)->f&TVSF_SKIP)) tvec_skipgroup(tv, 0); \
+ tvec_endgroup(tv); })
+#define TVEC_TESTGROUP(tv, name) TVEC_TESTGROUP_TAG(grp, tv, name)
+
+/* --- @tvec_begintest@, @TVEC_BEGINTEST@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ *
+ * Returns: ---
+ *
+ * Use: Begin an ad-hoc test case. The @file@ and @lno@ can be
+ * anything, but it's usually best if they refer to the source
+ * code performing the test: the macro @TVEC_BEGINGROUP@ does
+ * this automatically.
+ */
+
+extern void tvec_begintest(struct tvec_state */*tv*/,
+ const char */*file*/, unsigned /*lno*/);
+#define TVEC_BEGINTEST(tv) \
+ do tvec_begintest(tv, __FILE__, __LINE__); while (0)
+
+/* --- @tvec_endtest@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ *
+ * Returns: ---
+ *
+ * Use: End an ad-hoc test case, The statistics are updated and the
+ * outcome is reported to the output formatter.
+ */
+
+extern void tvec_endtest(struct tvec_state */*tv*/);
+
+/* --- @TVEC_TEST@, @TVEC_TEST_TAG@ --- *
+ *
+ * Arguments: @tag@ = label-disambiguation tag
+ * @struct tvec_test *t@ = space for a test definition
+ *
+ * Returns: ---
+ *
+ * Use: Control-structure macro: @TVEC_TEST(tv) stmt@ begins a test
+ * case, executes @stmt@, and ends the test case. If @stmt@
+ * invokes @break@ then the test case is skipped.
+ * @TVEC_TEST_TAG@ is the same, with an additional @tag@ argumet
+ * for use in higher-level macros.
+ */
+
+#define TVEC_TEST_TAG(tag, tv) \
+ MC_WRAP(tag##__around, \
+ { TVEC_BEGINTEST(tv); }, \
+ { tvec_endtest(tv); }, \
+ { if ((tv)->f&TVSF_ACTIVE) tvec_skip((tv), 0); \
+ tvec_endtest(tv); })
+#define TVEC_TEST(tv) TVEC_TEST_TAG(test, tv)
+
+/* --- @tvec_claim@, @tvec_claim_v@, @TVEC_CLAIM@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @int ok@ = a flag
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *msg@, @va_list *ap@ = message to report on
+ * failure
+ *
+ * Returns: The value @ok@.
+ *
+ * Use: Check that a claimed condition holds, as (part of) a test.
+ * If no test case is underway (i.e., if @TVSF_OPEN@ is reset in
+ * @tv->f@), then a new test case is begun and ended. The
+ * @file@ and @lno@ are passed to the output formatter to be
+ * reported in case of a failure. If @ok@ is nonzero, then
+ * nothing else happens; so, in particular, if @tvec_claim@
+ * established a new test case, then the test case succeeds. If
+ * @ok@ is zero, then a failure is reported, quoting @msg@.
+ *
+ * The @TVEC_CLAIM@ 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 @ok@ condition in
+ * the failure message.
+ */
+
+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*/);
+#define TVEC_CLAIM(tv, cond) \
+ (tvec_claim(tv, !!(cond), __FILE__, __LINE__, "%s untrue", #cond))
+
+/* --- @tvec_claimeq@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const struct tvec_regty *ty@ = register type
+ * @const union tvec_misc *arg@ = register type argument
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if the input and output values of register 0 are
+ * equal, zero if they differ.
+ *
+ * Use: Check that the input and output values of register 0 are
+ * equal (according to the register type @ty@). As for
+ * @tvec_claim@ above, a test case is automatically begun and
+ * ended if none is already underway. If the values are
+ * unequal, then @tvec_fail@ is called, quoting @expr@, and the
+ * mismatched values are dumped.
+ *
+ * This function is not expected to be called directly, but
+ * through type-specific wrapper functions or macros such as
+ * @TVEC_CLAIMEQ_INT@.
+ */
+
+extern int tvec_claimeq(struct tvec_state */*tv*/,
+ const struct tvec_regty */*ty*/,
+ const union tvec_misc */*arg*/,
+ const char */*file*/, unsigned /*lno*/,
+ const char */*expr*/);
+
+/*----- Benchmarking ------------------------------------------------------*/
+
+struct tvec_benchenv {
+ struct tvec_env _env; /* benchmarking is an environment */
+ struct bench_state **bst; /* benchmark state anchor or null */
+ unsigned long niter; /* iterations done per unit */
+ int riter, rbuf; /* iterations and buffer registers */
+ const struct tvec_env *env; /* subordinate environment */
+};
+
+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 */
+};
+
+extern struct bench_state *tvec_benchstate;
+
+/* --- Environment implementation --- *
+ *
+ * The following special variables are supported.
+ *
+ * * %|@target|% is the (approximate) number of seconds to run the
+ * benchmark.
+ *
+ * Unrecognized variables are passed to the subordinate environment, if there
+ * is one. Other events are passed through to the subsidiary environment.
+ */
+
+extern tvec_envsetupfn tvec_benchsetup;
+extern tvec_envfindvarfn tvec_benchfindvar;
+extern tvec_envbeforefn tvec_benchbefore;
+extern tvec_envrunfn tvec_benchrun;
+extern tvec_envafterfn tvec_benchafter;
+extern tvec_envteardownfn tvec_benchteardown;
+
+#define TVEC_BENCHENV \
+ { sizeof(struct tvec_benchctx), \
+ tvec_benchsetup, \
+ tvec_benchfindvar, \
+ tvec_benchbefore, \
+ tvec_benchrun, \
+ tvec_benchafter, \
+ tvec_benchteardown }
+#define TVEC_BENCHINIT TVEC_BENCHENV, &tvec_benchstate
+
+/* --- @tvec_benchreport@ --- *
+ *
+ * Arguments: @const struct gprintf_ops *gops@ = print operations
+ * @void *go@ = print destination
+ * @unsigned unit@ = the unit being measured (~TVBU_...@)
+ * @const struct bench_timing *tm@ = the benchmark result
+ *
+ * Returns: ---
+ *
+ * Use: Formats a report about the benchmark performance. This
+ * function is intended to be called on by an output
+ * @ebench@ function.
+ */
+
+extern void tvec_benchreport
+ (const struct gprintf_ops */*gops*/, void */*go*/,
+ unsigned /*unit*/, const struct bench_timing */*tm*/);
+
+/*----- Remote execution --------------------------------------------------*/
+
+struct tvec_remotecomms {
+ int infd, outfd; /* input and output descriptors */
+ 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 */
+};
+#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 */
+ lbuf errbuf; /* child stderr line buffer */
+ dstr prgwant, progress; /* progress: wanted/reported */
+ unsigned exwant, exit; /* exit status wanted/reported */
+#define TVRF_RCNMASK 0x0300u /* reconnection behaviour: */
+#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 {
+ struct tvec_env _env;
+ struct tvec_remoteenv_slots r;
+};
+
+struct tvec_remotefork_slots {
+ const struct tvec_test *tests; /* child tests (or null) */
+};
+
+struct tvec_remotefork {
+ struct tvec_env _env;
+ struct tvec_remoteenv_slots r;
+ struct tvec_remotefork_slots f;
+};
+
+struct tvec_remoteexec_slots {
+ const char *const *args; /* command line to execute */
+};
+
+struct tvec_remoteexec {
+ struct tvec_env _env;
+ struct tvec_remoteenv_slots r;
+ struct tvec_remoteexec_slots x;
+};
+
+union tvec_remoteenv_subclass_kludge {
+ struct tvec_env _env;
+ struct tvec_remoteenv renv;
+ struct tvec_remotefork fork;
+ 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_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_remotefindvar, \
+ tvec_remotebefore, \
+ tvec_remoterun, \
+ tvec_remoteafter, \
+ tvec_remoteteardown }
+
+/* --- @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) \
+ 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
+ * @const char *msg@, @va_list ap@ = error message
+ *
+ * Returns: ---
+ *
+ * Use: Report an message with a given severity. Messages with level
+ * @TVLEV_ERR@ or higher force a nonzero exit code.
+ */
+
+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*/);
+
+/* --- @tvec_error@, @tvec_notice@ --- *
+ *
+ * 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
+ * convenience; @tvec_notice@ does not return a value.
+ *
+ * Use: Report an error or a notice. Errors are distinct from test
+ * failures, and indicate that a problem was encountered which
+ * compromised the activity of testing. Notices are important
+ * information which doesn't fit into any other obvious
+ * category.
+ */
+
+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@ --- *
+ *
+ * Arguments: @FILE *fp@ = output file to write on
+ *
+ * Returns: An output formatter.
+ *
+ * Use: Return an output formatter which writes on @fp@ with the
+ * expectation that a human will be watching and interpreting
+ * the output. If @fp@ denotes a terminal, the display shows a
+ * `scoreboard' indicating the outcome of each test case
+ * attempted, and may in addition use colour and other
+ * highlighting.
+ */
+
+extern struct tvec_output *tvec_humanoutput(FILE */*fp*/);
+
+/* --- @tvec_tapoutput@ --- *
+ *
+ * Arguments: @FILE *fp@ = output file to write on
+ *
+ * Returns: An output formatter.
+ *
+ * Use: Return an output formatter which writes on @fp@ in `TAP'
+ * (`Test Anything Protocol') format.
+ *
+ * TAP comes from the Perl community, but has spread rather
+ * 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*/);
+
+/* --- @tvec_dfltoutput@ --- *
+ *
+ * Arguments: @FILE *fp@ = output file to write on
+ *
+ * Returns: An output formatter.
+ *
+ * Use: Selects and instantiates an output formatter suitable for
+ * writing on @fp@. The policy is subject to change, but
+ * currently the `human' output format is selected if @fp@ is
+ * interactive (i.e., if @isatty(fileno(fp))@ is true), and
+ * otherwise the `tap' format is used.
+ */
+
+extern struct tvec_output *tvec_dfltout(FILE */*fp*/);
+
+/*------ Serialization utilities ------------------------------------------*/
+
+/* Serialization format.
+ *
+ * The `candidate register definitions' are those entries @r@ in the @regs@
+ * vector whose index @r.i@ is strictly less than @nr@. The `selected
+ * register definitions' are those candidate register definitions @r@ for
+ * which the indicated register @rv[r.i]@ has the @TVRF_LIVE@ flag set. The
+ * serialized output begins with a header bitmap: if there are %$n$%
+ * candidate register definitions then the header bitmap consists of %$\lceil
+ * n/8 \rceil$% bytes. Bits are ordered starting from the least significant
+ * bit of the first byte, end ending at the most significant bit of the final
+ * byte. The bit corresponding to a candidate register definition is set if
+ * and only if that register defintion is selected. The header bitmap is
+ * then followed by the serializations of the selected registers -- i.e., for
+ * each selected register definition @r@, the serialized value of register
+ * @rv[r.i]@ -- simply concatenated together, with no padding or alignment.
+ */
+
+/* --- @tvec_serialize@ --- *
+ *
+ * Arguments: @const struct tvec_reg *rv@ = vector of registers
+ * @buf *b@ = buffer to write on
+ * @const struct tvec_regdef *regs@ = vector of register
+ * descriptions, terminated by an entry with a null
+ * @name@ slot
+ * @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.
+ *
+ * Use: Serialize a collection of register values.
+ *
+ * The serialized output is written to the buffer @b@. Failure
+ * can be caused by running out of buffer space, or a failing
+ * type handler.
+ */
+
+extern int tvec_serialize(const struct tvec_reg */*rv*/, buf */*b*/,
+ const struct tvec_regdef */*regs*/,
+ unsigned /*nr*/, size_t /*regsz*/);
+
+/* --- @tvec_deserialize@ --- *
+ *
+ * Arguments: @struct tvec_reg *rv@ = vector of registers
+ * @buf *b@ = buffer to write on
+ * @const struct tvec_regdef *regs@ = vector of register
+ * descriptions, terminated by an entry with a null
+ * @name@ slot
+ * @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.
+ *
+ * Use: Deserialize a collection of register values.
+ *
+ * The size of the register vector @nr@ and the register
+ * definitions @regs@ must match those used when producing the
+ * serialization. For each serialized register value,
+ * deserialize and store the value into the appropriate register
+ * slot, and set the @TVRF_LIVE@ flag on the register. See
+ * @tvec_serialize@ for a description of the format.
+ *
+ * Failure results only from a failing register type handler.
+ */
+
+extern int tvec_deserialize(struct tvec_reg */*rv*/, buf */*b*/,
+ const struct tvec_regdef */*regs*/,
+ unsigned /*nr*/, size_t /*regsz*/);
+
+/*----- Input utilities ---------------------------------------------------*/
+
+/* These are provided by the core for the benefit of type @parse@ methods,
+ * and test-environment @set@ functions, which get to read from the test
+ * input file. The latter are usually best implemented by calling on the
+ * former.
+ *
+ * The two main rules are as follows.
+ *
+ * * Leave the file position at the beginning of the line following
+ * whatever it was that you read.
+ *
+ * * When you read and consume a newline (which you do at least once, by
+ * the previous rule), then increment @tv->lno@ to keep track of the
+ * current line number.
+ */
+
+/* --- @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$%.
+ *
+ * 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.,
+ * by @tvec_flushtoeol@ or @tvec_nexttoken@, which will also
+ * advance the line number).
+ */
+
+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.
+ *
+ * Use: Advance to the start of the next line, consuming the
+ * preceding newline.
+ *
+ * A syntax error is reported if no newline character is found,
+ * i.e., the file ends in mid-line. A syntax error is also
+ * reported if material other than whitespace or a comment is
+ * found before the end of the line end, and @TVFF_ALLOWANY@ is
+ * not set in @f@. The line number count is updated
+ * appropriately.
+ */
+
+#define TVFF_ALLOWANY 1u
+extern int tvec_flushtoeol(struct tvec_state */*tv*/, unsigned /*f*/);
+
+/* --- @tvec_nexttoken@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ *
+ * 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
+ * on the next line.
+ *
+ * Tokens are separated by non-newline whitespace, comments, and
+ * newlines followed by whitespace; a newline /not/ followed by
+ * whitespace instead begins the next assignment, and two
+ * newlines separated only by whitespace terminate the data for
+ * a test.
+ *
+ * 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,
+ * 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_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.
+ *
+ * Use: A `word' consists of characters other than whitespace, null
+ * characters, and other than those listed in @delims@;
+ * furthermore, a word does not begin with a `;'. (If you want
+ * reading to stop at comments not preceded by whitespace, then
+ * 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@.
+ *
+ * Otherwise, the word is accumulated in @d@ and zero is
+ * returned; if @d@ was not empty at the start of the call, the
+ * newly read word is separated from the existing material by a
+ * single space character. Since null bytes are never valid
+ * 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 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 **/*p_inout*/, const char */*delims*/,
+ const char */*expect*/, va_list */*ap*/);
+
+/*----- Integer types: signed and unsigned --------------------------------*/
+
+/* Integers may be input in decimal, hex, binary, or octal, following
+ * approximately usual conventions.
+ *
+ * * Signed integers may be preceded with a `+' or `-' sign.
+ *
+ * * Decimal integers are just a sequence of decimal digits `0' ... `9'.
+ *
+ * * Octal integers are a sequence of digits `0' ... `7', preceded by `0o'
+ * or `0O'.
+ *
+ * * Hexadecimal integers are a sequence of digits `0' ... `9', `a'
+ * ... `f', or `A' ... `F', preceded by `0x' or `0X'.
+ *
+ * * Radix-B integers are a sequence of digits `0' ... `9', `a' ... `f', or
+ * `A' ... `F', each with value less than B, preceded by `Br' or `BR',
+ * where 0 < B < 36 is expressed in decimal without any leading `0' or
+ * internal underscores `_'.
+ *
+ * * A digit sequence may contain internal underscore `_' separators, but
+ * not before or after all of the digits; and two consecutive `_'
+ * characters are not permitted.
+ */
+
+extern const struct tvec_regty tvty_int, tvty_uint;
+
+/* The @arg.p@ slot may be null or a pointer to @struct tvec_irange@ or
+ * @struct tvec_urange@ as appropriate. The bounds are inclusive; use, e.g.,
+ * @LONG_MAX@ explicitly if one or the other bound is logically inapplicable.
+ */
+struct tvec_irange { long min, max; };
+struct tvec_urange { unsigned long min, max; };
+
+/* Bounds corresponding to common integer types. */
+extern const struct tvec_irange
+ tvrange_schar, tvrange_short, tvrange_int, tvrange_long,
+ tvrange_sbyte, tvrange_i16, tvrange_i32;
+extern const struct tvec_urange
+ tvrange_uchar, tvrange_ushort, tvrange_uint, tvrange_ulong, tvrange_size,
+ tvrange_byte, tvrange_u16, tvrange_u32;
+
+/* --- @tvec_claimeq_int@, @TVEC_CLAIMEQ_INT@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @long i0, i1@ = two signed integers
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if @i0@ and @i1@ are equal, otherwise zero.
+ *
+ * Use: Check that values of @i0@ and @i1@ are equal. As for
+ * @tvec_claim@ above, a test case is automatically begun and
+ * ended if none is already underway. If the values are
+ * unequal, then @tvec_fail@ is called, quoting @expr@, and the
+ * mismatched values are dumped: @i0@ is printed as the output
+ * value and @i1@ is printed as the input reference.
+ *
+ * The @TVEC_CLAIM_INT@ 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 @i0@ and @i1@
+ * arguments in the failure message.
+ */
+
+extern int tvec_claimeq_int(struct tvec_state */*tv*/,
+ long /*i0*/, long /*i1*/,
+ const char */*file*/, unsigned /*lno*/,
+ const char */*expr*/);
+#define TVEC_CLAIMEQ_INT(tv, i0, i1) \
+ (tvec_claimeq_int(tv, i0, i1, __FILE__, __LINE__, #i0 " /= " #i1))
+
+/* --- @tvec_claimeq_uint@, @TVEC_CLAIMEQ_UINT@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @unsigned long u0, u1@ = two unsigned integers
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if @u0@ and @u1@ are equal, otherwise zero.
+ *
+ * Use: Check that values of @u0@ and @u1@ are equal. As for
+ * @tvec_claim@ above, a test case is automatically begun and
+ * ended if none is already underway. If the values are
+ * unequal, then @tvec_fail@ is called, quoting @expr@, and the
+ * mismatched values are dumped: @u0@ is printed as the output
+ * value and @u1@ is printed as the input reference.
+ *
+ * The @TVEC_CLAIM_UINT@ 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 @u0@ and @u1@ arguments in the failure message.
+ */
+
+extern int tvec_claimeq_uint(struct tvec_state */*tv*/,
+ unsigned long /*u0*/, unsigned long /*u1*/,
+ const char */*file*/, unsigned /*lno*/,
+ const char */*expr*/);
+#define TVEC_CLAIMEQ_UINT(tv, u0, u1) \
+ (tvec_claimeq_uint(tv, u0, u1, __FILE__, __LINE__, #u0 " /= " #u1))
+
+/*----- Floating-point type -----------------------------------------------*/
+
+/* 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.
+ */
+
+extern const struct tvec_regty tvty_float;
+
+struct tvec_floatinfo {
+ /* Details about acceptable floating-point values. */
+
+ unsigned f; /* flags (@TVFF_...@ bits) */
+#define TVFF_NOMIN 1u /* ignore @min@ (allow -inf) */
+#define TVFF_NOMAX 2u /* ignore @max@ (allow +inf) */
+#define TVFF_NANOK 4u /* permit NaN */
+#define TVFF_EQMASK 0xf0 /* how to compare */
+#define TVFF_EXACT 0x00 /* must equal exactly */
+#define TVFF_ABSDELTA 0x10 /* must be within @delta@ */
+#define TVFF_RELDELTA 0x20 /* diff < @delta@ fraction */
+ double min, max; /* smallest/largest value allowed */
+ double delta; /* maximum tolerable difference */
+};
+
+/* --- @tvec_claimeqish_float@, @TVEC_CLAIMEQISH_FLOAT@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @double f0, f1@ = two floating-point numbers
+ * @unsigned f@ = flags (@TVFF_...@)
+ * @double delta@ = maximum tolerable difference
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if @f0@ and @u1@ are sufficiently close, otherwise
+ * zero.
+ *
+ * Use: Check that values of @f0@ and @f1@ are sufficiently close.
+ * As for @tvec_claim@ above, a test case is automatically begun
+ * and ended if none is already underway. If the values are
+ * too far apart, then @tvec_fail@ is called, quoting @expr@,
+ * and the mismatched values are dumped: @f0@ is printed as the
+ * output value and @f1@ is printed as the input reference.
+ *
+ * The details for the comparison are as follows.
+ *
+ * * A NaN value matches any other NaN, and nothing else.
+ *
+ * * An infinity matches another infinity of the same sign,
+ * and nothing else.
+ *
+ * * If @f&TVFF_EQMASK@ is @TVFF_EXACT@, then any
+ * representable number matches only itself: in particular,
+ * positive and negative zero are considered distinct.
+ * (This allows tests to check that they land on the correct
+ * side of branch cuts, for example.)
+ *
+ * * If @f&TVFF_EQMASK@ is @TVFF_ABSDELTA@, then %$x$% matches
+ * %$y$% when %$|x - y| < \delta$%.
+ *
+ * * If @f&TVFF_EQMASK@ is @TVFF_RELDELTA@, then %$x$% matches
+ * %$y$% when %$|1 - y/x| < \delta$%. (Note that this
+ * criterion is asymmetric FIXME
+ *
+ * The @TVEC_CLAIM_FLOAT@ 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 @f0@ and @f1@ arguments (and @delta@) in the failure
+ * message.
+ */
+
+extern int tvec_claimeqish_float(struct tvec_state */*tv*/,
+ double /*f0*/, double /*f1*/,
+ unsigned /*f*/, double /*delta*/,
+ const char */*file*/, unsigned /*lno*/,
+ const char */*expr*/);
+#define TVEC_CLAIMEQISH_FLOAT(tv, f0, f1, f, delta) \
+ (tvec_claimeqish_float(tv, f0, f1, f, delta, , __FILE__, __LINE__, \
+ #f0 " /= " #f1 " (+/- " #delta ")"))
+
+/* --- @tvec_claimeq_float@, @TVEC_CLAIMEQ_FLOAT@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @double f0, f1@ = two floating-point numbers
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if @f0@ and @u1@ are identical, otherwise zero.
+ *
+ * Use: Check that values of @f0@ and @f1@ are identical. The
+ * function is exactly equivalent to @tvec_claimeqish_float@
+ * with @f == TVFF_EXACT@; the macro is similarly like
+ * @TVEC_CLAIMEQISH_FLOAT@ with @f == TVFF_EXACT@, except that
+ * it doesn't bother to quote a delta.
+ */
+
+extern int tvec_claimeq_float(struct tvec_state */*tv*/,
+ double /*f0*/, double /*f1*/,
+ const char */*file*/, unsigned /*lno*/,
+ const char */*expr*/);
+#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;
+
+/*----- Enumerated types --------------------------------------------------*/
+
+/* An enumeration describes a set of values of some underlying type, each of
+ * which has a symbolic name. Values outside of the defined set can occur --
+ * on output, because of bugs in the tested code, or on input to test
+ * handling of unexpected values.
+ *
+ * There is a distinct enumerated type for each of the branches of
+ * @tvec_misc@. In the following, we write @t@ for the type code, which is
+ * @i@ for signed integer, @u@ for unsigned integer, @f@ for floating-point,
+ * and @p@ for pointer.
+ *
+ * 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
+ * pointer. On output, names are preferred (with the underlying value given
+ * in a comment).
+ */
+
+#define DEFENUMTY(tag, ty, slot) \
+ extern const struct tvec_regty tvty_##slot##enum;
+TVEC_MISCSLOTS(DEFENUMTY)
+#undef DEFENUMTY
+
+/* A @struct tvec_tassoc@ associates a string tag with a value. */
+#define DEFASSOC(tag_, ty, slot) \
+ struct tvec_##slot##assoc { const char *tag; ty slot; };
+TVEC_MISCSLOTS(DEFASSOC)
+#undef DEFASSOC
+
+#define TVEC_ENDENUM { 0, 0 }
+
+/* Information about an enumerated type. */
+#define DEFINFO(tag, ty, slot) \
+ struct tvec_##slot##enuminfo { \
+ const char *name; /* type name for diagnostics */ \
+ const struct tvec_##slot##assoc *av; /* name/value mappings */ \
+ EXTRA_##tag##_INFOSLOTS /* type-specific extra info */ \
+ };
+
+#define EXTRA_INT_INFOSLOTS \
+ const struct tvec_irange *ir; /* allowed range of raw values */
+
+#define EXTRA_UINT_INFOSLOTS \
+ const struct tvec_urange *ur; /* allowed range of raw values */
+
+#define EXTRA_FLT_INFOSLOTS \
+ const struct tvec_floatinfo *fi; /* range and matching policy */
+
+#define EXTRA_PTR_INFOSLOTS /* (nothing) */
+
+TVEC_MISCSLOTS(DEFINFO)
+
+#undef EXTRA_INT_INFOSLOTS
+#undef EXTRA_UINT_INFOSLOTS
+#undef EXTRA_FLT_INFOSLOTS
+#undef EXTRA_PTR_INFOSLOTS
+
+#undef DEFINFO
+
+/* Standard enumerations. */
+extern const struct tvec_ienuminfo tvenum_bool;
+extern const struct tvec_ienuminfo tvenum_cmp;
+
+/* --- @tvec_claimeq_tenum@, @TVEC_CLAIMEQ_TENUM@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const struct tvec_typeenuminfo *ei@ = enumeration type info
+ * @ty t0, t1@ = two values
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if @t0@ and @t1@ are equal, otherwise zero.
+ *
+ * Use: Check that values of @t0@ and @t1@ are equal. As for
+ * @tvec_claim@ above, a test case is automatically begun and
+ * ended if none is already underway. If the values are
+ * unequal, then @tvec_fail@ is called, quoting @expr@, and the
+ * mismatched values are dumped: @t0@ is printed as the output
+ * value and @t1@ is printed as the input reference.
+ *
+ * The @TVEC_CLAIM_TENUM@ 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 @t0@ and @t1@ arguments in the failure message.
+ */
+
+#define DECLCLAIM(tag, ty, slot) \
+ extern int tvec_claimeq_##slot##enum \
+ (struct tvec_state */*tv*/, \
+ const struct tvec_##slot##enuminfo */*ei*/, \
+ ty /*t0*/, ty /*t1*/, \
+ const char */*file*/, unsigned /*lno*/, const char */*expr*/);
+TVEC_MISCSLOTS(DECLCLAIM)
+#undef DECLCLAIM
+#define TVEC_CLAIMEQ_IENUM(tv, ei, i0, i1) \
+ (tvec_claimeq_ienum(tv, ei, i0, i1, \
+ __FILE__, __LINE__, #i0 " /= " #i1))
+#define TVEC_CLAIMEQ_UENUM(tv, ei, u0, u1) \
+ (tvec_claimeq_uenum(tv, ei, u0, u1, \
+ __FILE__, __LINE__, #u0 " /= " #u1))
+#define TVEC_CLAIMEQ_FENUM(tv, ei, f0, f1) \
+ (tvec_claimeq_fenum(tv, ei, f0, f1, \
+ __FILE__, __LINE__, #f0 " /= " #f1))
+#define TVEC_CLAIMEQ_PENUM(tv, ei, p0, p1) \
+ (tvec_claimeq_penum(tv, ei, p0, p1, \
+ __FILE__, __LINE__, #p0 " /= " #p1))
+
+/*----- Flags type --------------------------------------------------------*/
+
+/* A flags value packs a number of fields into a single nonnegative integer.
+ * Symbolic names are associated with the possible values of the various
+ * 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.
+ *
+ * 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.
+ */
+
+extern const struct tvec_regty tvty_flags;
+
+struct tvec_flag {
+ /* Definition of a single flag or bitfield value.
+ *
+ * Each named setting comes with a value @v@ and a mask @m@; the mask
+ * should cover all of the value bits, i.e., @(v&~m) == 0@.
+ */
+
+ const char *tag; /* name */
+ unsigned long m, v; /* mask and value */
+};
+
+#define TVEC_ENDFLAGS { 0, 0, 0 }
+
+struct tvec_flaginfo {
+ /* Information about a flags type. */
+
+ const char *name; /* type name for diagnostics */
+ const struct tvec_flag *fv; /* name/mask/value mappings */
+ const struct tvec_urange *range; /* permitted range for literals */
+};
+
+/* --- @tvec_claimeq_flags@, @TVEC_CLAIMEQ_FLAGS@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @const struct tvec_flaginfo *fi@ = flags type info
+ * @unsigned long f0, f1@ = two values
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if @f0@ and @f1@ are equal, otherwise zero.
+ *
+ * Use: Check that values of @f0@ and @f1@ are equal. As for
+ * @tvec_claim@ above, a test case is automatically begun and
+ * ended if none is already underway. If the values are
+ * unequal, then @tvec_fail@ is called, quoting @expr@, and the
+ * mismatched values are dumped: @f0@ is printed as the output
+ * value and @f1@ is printed as the input reference.
+ *
+ * The @TVEC_CLAIM_FLAGS@ 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 @f0@ and @f1@ arguments in the failure message.
+ */
+
+extern int tvec_claimeq_flags(struct tvec_state */*tv*/,
+ const struct tvec_flaginfo */*fi*/,
+ unsigned long /*f0*/, unsigned long /*f1*/,