--- name: "tst_res" section: "3" platform: "linux" package: "ltp-dev" version: "20091231+dfsg-1" release: "Debian 6.0 (Squeeze)" platforms: ["linux"] url: "https://new.carta.tech/tst_res" --- # tst\_res(3) Print result message, including file contents 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 ## NAME tst\_res - Print result message, including file contents 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 ## SYNOPSIS **#include "test.h"** **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;** ## DESCRIPTION ### Introduction This library of functions are used by UNICOS tests to report results to standard out in a consistent manner. It is assumed that tests using this library have a distinct number of test cases, and that each test case is distinct and uniquely identified by the test case number. It is also assumed that test case results are printed in consecutive order, starting with 1. The library maintains a set of global variables (**TCID, TST\_TOTAL,** **Tst\_count, Tst\_range, Tst\_lpstart**, **Tst\_lptotal**), which are used by the various functions to format the results and to keep track of the current result reporting state (i.e. how many total test cases there are, and how many have been reported so far) for the calling test. 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 **T**est **C**ase **ID**entifier, 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. ### Arguments - *ttype* test result type; one of **TPASS, TFAIL, TBROK, TCONF, TRETR, TWARN**, or **TINFO** (explained below). - *fname* pointer to a character string holding the name of a file whose contents will be printed on a new line following *tmesg*. If this pointer is NULL, it is ignored. - *tmesg, \[arg ...\]* pointer to a character string containing a message explaining the test result. This character string can contain percent-sign conversion specifications as in **printf**(3C) with corresponding *arg* arguments following the *tmesg* argument.\ **NOTE:** These routines use static space internally to hold the expanded message. The maximum size allowed for an expanded message is 2048 bytes. - *func* pointer to a function which performs either the cleanup necessary prior to exiting the test or some function executed at the end of each iteration of a loop. ### Result Types The possible test result types defined in **test.h** are as follows: - **TPASS** The test case produced expected results. - **TFAIL** The test case produced unexpected results. - **TBROK** A resource needed to execute the test case was not available (e.g. a temporary file could not be opened). - **TCONF** The test case was not appropriate for the current hardware or software configuration (e.g. MLS was not enabled). - **TRETR** The test case was no longer valid and has been "retired." - **TWARN** The testing procedure caused undesirable side effects that did not affect test results (e.g. a temporary file could not be removed after all test results were recorded). - **TINFO** An informative message about the execution of the test that does not correspond to a test case result and does not indicate a problem. ### Function Descriptions **tst\_res()** and **tst\_resm()** are the basic result reporting functions. They report 1 or more test case results of the specified *ttype*. All result types are valid for these functions. The **Tst\_range** global variable indicates the number of results that will be reported for each call to one of these functions. It is initialized by the library to 1, but may be set to a value \> 1 by the test. Each call to one of these functions will result in **Tst\_range** test case results being reported, each with an identical message (*tmesg*). **Tst\_range** is always reset to 1 by the library before returning to the caller. If **tst\_res()** is called with a *fname* argument, the contents of the file will only be printed for the first reported result. **tst\_res()** takes the *fname* argument whereas **tst\_resm()** does not. 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: - TPASS 0000 /\* .... .... \*/ - TFAIL 0001 /\* .... ...1 \*/ - TBROK 0002 /\* .... ..1. \*/ - TWARN 0004 /\* .... .1.. \*/ - TRETR 0010 /\* .... 1... \*/ - TINFO 0020 /\* ...1 .... \*/ - TCONF 0040 /\* ..1. .... \*/ 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. ### Output Modes Four output display modes are supported by the **tst\_res()** family of functions to enhance output readability. The active mode is controlled via the environment variable **TOUTPUT**, which must be set prior to the start of the test in order to have any effect (see [**ksh**(1)](/ksh/1.md) for information on environment variables). The supported modes are as follows: - **VERBOSE** A test result output line is generated for each test result. This is the default mode. - **CONDENSE** Consecutive, identical PASS, FAIL, BROK, CONF, and RETR test results are condensed into one output line. The test case number field contains the range of results involved. WARN and INFO output lines are not condensed, but printed as usual. - **NOPASS** All PASS, CONF, INFO, and RETR output lines are discarded (i.e. not printed), and consecutive, identical FAIL and BROK output lines are condensed as in **CONDENSE** mode. WARN output lines are printed as usual. - **DISCARD** All output lines are discarded. ## EXAMPLES ``` #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 ``` ## SEE ALSO utst\_res(1), tst\_setup(1), printf(3C), [ksh(1)](/ksh/1.md). ## DIAGNOSTICS 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*. ## LIMITATIONS If *fname* is NULL and *tmesg* is NULL or empty, the result message will be empty. This allows a test to not print a message for a result, but it is not advised. ## BUGS The programmer is free to alter the value of **Tst\_count** causing possible test result order problems.