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 */
#ifdef TVEC_REGSLOTS
TVEC_REGSLOTS
#endif
typedef int tvec_envsetfn(struct tvec_state */*tv*/,
const char */*var*/, 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.
+ * value. Return %$+1$% on success, %$0$% if the variable name was not
+ * recognized, or %$-1$% on any other error (which should have been
+ * reported via @tvec_error@).
*/
typedef void tvec_envbeforefn(struct tvec_state */*tv*/, void */*ctx*/);
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 */
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_envrunfn 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*/);
struct tvec_timeoutenv {
struct tvec_env _env;
- unsigned timer;
- double t;
- const struct tvec_env *env;
+ unsigned 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;
- unsigned timer;
- double t;
+ const struct tvec_timeoutenv *te; /* saved environment description */
+ unsigned timer; /* timer code (as overridden) */
+ double t; /* time to wait (as overridden) */
unsigned f; /* flags */
#define TVTF_SETTMO 1u /* set `@timeout' */
#define TVTF_SETMASK (TVTF_SETTMO) /* mask of @TVTF_SET...@ */
/*----- 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.
* 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).
*/
* 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;
/* 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.
*
* * `%|!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
* 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
* 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
* 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@ --- *
*
(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
* 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 -------------------------------------------------------*/
* 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.
+ *
+ * No @claimeq@ functions or macros are provided for buffers because they
+ * don't seem very useful.
*/
extern const struct tvec_regty tvty_buffer;
~mdw / mLib / blobdiff