tst_resm - Print result message
tst_brk - Print result message and break remaining test cases
tst_brkm - Print result message, including file contents, and break remaining test cases
tst_brkloop - Print result message, include file contents, and break remaining test cases in loop
tst_brkloopm - Print result message and break remaining test cases in loop
tst_flush - Print any messages pending because of CONDENSE mode, and flush output stream
tst_exit - Exit test with a meaningful exit value
tst_environ - Keep results coming to original stdout
void tst_res(int ttype, char *fname, char *tmesg, [arg ...])
void tst_resm(int ttype, char *tmesg, [arg ...])
void tst_brk(int ttype, char *fname, void (*func)(), char *tmesg, [arg ...])
void tst_brkm(int ttype, void (*func)(), char *tmesg, [arg ...])
void tst_brkloop(int ttype, char *fname, void (*func)(), char *tmesg, [arg ...])
void tst_brkloopm(int ttype, void (*func)(), char *tmesg, [arg ...])
void tst_flush()
void tst_exit()
int tst_environ()
extern int Tst_count;
extern int Tst_range;
extern int Tst_lpstart;
extern int Tst_lptotal;
The TCID and TST_TOTAL global variables are externed in the library, and MUST be defined/initialized by tests using the library. TCID must be set to the Test Case IDentifier, and TST_TOTAL must be set to the total number of test cases that will be reported.
The other global variables are available as externs to tests linked with tst_res.o. Tst_count is the running count of the number of test results that have been reported so far. The library initializes it to 0, and it should not be modified by the test. Tst_range, Tst_lpstart, and Tst_lptotal are used by to control how many test results are reported under certain conditions, by some of the functions in this library. The details are described below under the appropriate functions.
NOTE: All calls to tst_res() specifying a ttype of TWARN or TINFO will be printed with a test case number of zero. Because of this, a Tst_range value > 1 is not valid for these types.
tst_brk() and tst_brkm() are used to report results for all test cases remaining in the test, and then call a cleanup function. The only result types that are valid for these functions are: TFAIL, TBROK, TCONF, and TRETR. When called with a ttype of TFAIL or TBROK, one result of the specified ttype will be printed, followed by results of type TBROK for the remaining test cases. When called with a ttype of TCONF or TRETR, the specified ttype will be printed for all remaining test cases. If func is not NULL, tst_brk() and tst_brkm() will call func after all results have been printed. If the call to func returns, tst_brk() and tst_brkm() will then call tst_exit(). If func is NULL, tst_brk() and tst_brkm() return to the caller after all results have been printed. If tst_brk() is called with a fname argument, the contents of the file will only be printed for the first reported result. tst_brk() takes the fname argument whereas tst_brkm() does not.
tst_brkloop() and tst_brkloopm() work just like tst_brk() and tst_brkm(), except they only report results for a the test cases remaining in the current loop. The Tst_lpstart and Tst_lptotal global variables are used to determine how many test cases to report results for. Prior to the start of the loop, the test must set Tst_lpstart to Tst_count, and Tst_lptotal to the number of test cases in the loop. If a test calls tst_brkloop() or tst_brkloopm() without first setting Tst_lpstart and Tst_lptotal to meaningful values, a WARN result will be reported and control will be immediately returned to the caller. This will most likely cause the result messages to be out of order. Unlike the tst_brk() functions, tst_brkloop() and tst_brkloopm() will not call tst_exit() if the func argument is not NULL and returns. tst_brkloop() takes the fname argument whereas tst_brkloopm() does not.
tst_flush() is used to print any results pending because of CONDENSE or NOPASS modes (described below), and flushes the output stream.
tst_exit() is used to allow tests to exit with a meaningful exit value. A bit is set in the exit value for each of the non passing test case result types (TFAIL, TBROK, and TWARN) encountered by the library. Thus any bit which is set in the exit value indicates that the corresponding result flag was used at least once in the test run.
The current bit fields for the result types are as follows:
NOTE: TPASS, TRETR, TINFO, and TCONF do not have an effect on the test program exit status.
tst_environ() is used to ensure that results reported by this library will go to the original stdout, even if the test changes the original stdout to another file, or closes it. A test may want to do this in order to redirect output that normally goes to stdout (e.g. printf() output) to a file. tst_environ() returns 0 upon successful completion, and -1 if it encountered any problems.
#include "test.h"
char *TCID = "tsttcs01"; /* set test case identifier */
int TST_TOTAL = 15; /* set total number of test results */
extern int Tst_count; /* access count of results completed */
extern int Tst_lpstart; /* holds value for start of loop */
extern int Tst_lptotal; /* holds the number of test cases in loop */
main()
{
.
.
/* a successful test result */
tst_resm(TPASS, "what was tested");
/* or */
tst_res(TPASS, file, "what was tested");
.
.
/* break all remaining test results */
tst_brkm(TBROK, cleanup, "what didn't work");
/* or */
tst_brk(TBROK, file, cleanup, "what didn't work");
.
.
/* Break all remaining tests in loop */
Tst_lpstart = Tst_count;
Tst_lptotal = 5;
tst_brkloopm(TBROK, loop_setup, "setup did not work.");
/* or */
tst_brkloop(TBROK, file, loop_setup, "setup did not work.");
.
.
/* exit after all test results have been passed to tst_res */
tst_exit();
}
Sample output:
tsttcs01 1 PASS : Able to create MAXUP processes tsttcs01 2 FAIL : Too many processes (MAXUP+1) created tsttcs01 3 BROK : tabinfo(PROCTAB, &tbs) failed; errno = 13: Permission denied tsttcs01 4-10 BROK : Remaining cases broken tsttcs01 0 WARN : cleanup(): kill(0, SIGALRM) failed; errno = 3: No such process
A WARN result message will be printed if any of the following occur:
If an invalid test type is specified.
If Tst_count is negative.
If Tst_range is non-positive.
If Tst_range is > 1, and the test type is TINFO or TWARN.
If one of the tst_brk[loop][m]() routines is called with a test type other than TFAIL, TBROK, TCONF, or TRETR.
If Tst_lpstart is negative.
If Tst_lptotal is non-positive.
If there are any problems opening/reading/writing the contents of fname.
The programmer is free to alter the value of Tst_count causing possible test result order problems.