X-Git-Url: https://git.distorted.org.uk/~mdw/mLib/blobdiff_plain/31d0247cc58abc0b0720aa7e9972011c5a66995c..c81c35dfd10050ffef85d57dc2ad73f52f38a3f2:/test/tvec.h diff --git a/test/tvec.h b/test/tvec.h index 38c462b..5d37c3f 100644 --- a/test/tvec.h +++ b/test/tvec.h @@ -193,7 +193,7 @@ union tvec_regval { 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 @@ -351,8 +351,9 @@ typedef void tvec_envsetupfn(struct tvec_state */*tv*/, 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*/); @@ -1219,6 +1220,19 @@ 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 */ @@ -1257,6 +1271,30 @@ 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_envrunfn tvec_remoterun; @@ -1271,9 +1309,54 @@ extern tvec_envteardownfn tvec_remoteteardown; 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*/); @@ -1289,15 +1372,15 @@ extern tvec_connectfn tvec_fork, tvec_exec; 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...@ */ @@ -1742,10 +1825,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. @@ -1863,7 +1947,7 @@ extern const struct tvec_floatinfo tvflt_finite, tvflt_nonneg; * 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). */ @@ -1964,18 +2048,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; @@ -2038,8 +2123,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. * @@ -2156,6 +2242,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 @@ -2165,9 +2254,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 @@ -2185,22 +2274,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 @@ -2213,16 +2302,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@ --- * * @@ -2257,7 +2345,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 @@ -2273,12 +2361,12 @@ 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 -------------------------------------------------------*/ @@ -2291,6 +2379,9 @@ extern void tvec_allocbytes(union tvec_regval */*rv*/, size_t /*sz*/); * 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;