Provided by: ltp-dev_20091231+dfsg-1ubuntu2_amd64 bug

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 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.

   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)
       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).

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.