--- a
+++ b/doc/man3/tst_res.3
@@ -0,0 +1,377 @@
+.\" $Id: tst_res.3,v 1.1 2000/07/27 16:59:03 alaffin Exp $
+.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like.  Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file.  Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA  94043, or:
+.\" http://www.sgi.com 
+.\" For further information regarding this notice, see: 
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.TH TST_RES 3 07/25/2000 "Linux Test Project"
+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 and break remaining test cases in loop
+tst_brkloopm \- Print result message, including file contents, 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
+\fB#include "test.h"\fR
+\fBvoid tst_res(int \fIttype\fB, char *\fIfname\fB, char *\fItmesg,
+[arg ...]\fR)
+\fBvoid tst_resm(int \fIttype\fB, char *\fItmesg, [arg ...]\fR)
+\fBvoid tst_brk(int \fIttype\fB, char *\fIfname\fB, void (*\fIfunc\fB)(),
+char *\fItmesg, [arg ...]\fR)
+\fBvoid tst_brkm(int \fIttype\fB, void (*\fIfunc\fB)(), char *\fItmesg,
+[arg ...]\fR)
+\fBvoid tst_brkloop(int \fIttype\fB, char *\fIfname\fB, void (*\fIfunc\fB)(),
+char *\fItmesg, [arg ...]\fR)
+\fBvoid tst_brkloopm(int \fIttype\fB, void (*\fIfunc\fB)(), char *\fItmesg,
+[arg ...]\fR)
+\fBvoid tst_flush()
+\fBvoid tst_exit()
+\fBint  tst_environ()
+\fBextern int Tst_count;
+extern int Tst_range;
+extern int Tst_lpstart;
+extern int Tst_lptotal;
+.SS 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 (\fBTCID, TST_TOTAL,
+Tst_count, Tst_range, Tst_lpstart\fR, \fBTst_lptotal\fR), 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 \fBTCID\fR and \fBTST_TOTAL\fR global variables are externed in the
+library, and MUST be defined/initialized by tests using the library.
+\fBTCID\fR must be set to the \fBT\fRest \fBC\fRase \fBID\fRentifier, and
+\fBTST_TOTAL\fR must be set to the total number of test cases that will be
+The other global variables are available as externs to tests linked with
+tst_res.o.  \fBTst_count\fR 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.  \fBTst_range\fR, \fBTst_lpstart\fR,
+and \fBTst_lptotal\fR 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.
+.SS Arguments
+.RS 5
+.TP 10
+.I ttype
+test result type; one of \fBTPASS, TFAIL, TBROK, TCONF, TRETR, TWARN\fR, or
+\fBTINFO\fR (explained below).
+.TP 10
+.I fname
+pointer to a character string holding the name of a file whose contents will
+be printed on a new line following \fItmesg\fR.  If this pointer is NULL, it
+is ignored.
+.TP 10
+.I 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 \fBprintf\fR(3C) with corresponding \fIarg\fR arguments
+following the \fItmesg\fR argument.
+\fBNOTE:\fR These routines use static space internally to hold the
+expanded message.  The maximum size allowed for an expanded message is
+2048 bytes.
+.TP 10   
+.I 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
+.SS Result Types
+The possible test result types defined in \fBtest.h\fR are as follows:
+.RS 5
+.TP 10
+The test case produced expected results.
+.TP 10
+The test case produced unexpected results.
+.TP 10
+A resource needed to execute the test case was not available (e.g. a
+temporary file could not be opened).
+.TP 10
+The test case was not appropriate for the current hardware or software
+configuration (e.g. MLS was not enabled).
+.TP 10
+The test case was no longer valid and has been "retired."
+.TP 10
+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).
+.TP 10
+An informative message about the execution of the test that does not
+correspond to a test case result and does not indicate a problem.
+.SS Function Descriptions
+\fBtst_res()\fR and \fBtst_resm()\fR are the basic result reporting
+functions.  They report 1 or more test case results of the specified
+\fIttype\fR.  All result types are valid for these functions.  The
+\fBTst_range\fR 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 \fBTst_range\fR test case results being
+reported, each with an identical message (\fItmesg\fR).  \fBTst_range\fR is
+always reset to 1 by the library before returning to the caller.  If
+\fBtst_res()\fR is called with a \fIfname\fR argument, the contents of the
+file will only be printed for the first reported result.  \fBtst_res()\fR
+takes the \fIfname\fR argument whereas \fBtst_resm()\fR does not.
+NOTE: All calls to \fBtst_res()\fR specifying a \fIttype\fR of \fBTWARN\fR or
+\fBTINFO\fR will be printed with a test case number of zero.  Because of
+this, a \fBTst_range\fR value > 1 is not valid for these types.
+\fBtst_brk()\fR and \fBtst_brkm()\fR 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: \fBTFAIL, TBROK,
+TCONF\fR, and \fBTRETR\fR.  When called with a \fIttype\fR of \fBTFAIL\fR or
+\fBTBROK\fR, one result of the specified \fIttype\fR will be printed,
+followed by results of type \fBTBROK\fR for the remaining test cases.  When
+called with a \fIttype\fR of \fBTCONF\fR or \fBTRETR\fR, the specified
+\fIttype\fR will be printed for all remaining test cases.  If \fIfunc\fR is
+not NULL, \fBtst_brk()\fR and \fBtst_brkm()\fR will call \fIfunc\fR after all
+results have been printed.  If the call to \fIfunc\fR returns,
+\fBtst_brk()\fR and \fBtst_brkm()\fR will then call \fBtst_exit()\fR.  If
+\fIfunc\fR is NULL, \fBtst_brk()\fR and \fBtst_brkm()\fR return to the caller
+after all results have been printed.  If \fBtst_brk()\fR is called with a
+\fIfname\fR argument, the contents of the file will only be printed for the
+first reported result.  \fBtst_brk()\fR takes the \fIfname\fR argument
+whereas \fBtst_brkm()\fR does not.
+\fBtst_brkloop()\fR and \fBtst_brkloopm()\fR work just like \fBtst_brk()\fR
+and \fBtst_brkm()\fR, except they only report results for a the test cases
+remaining in the current loop.  The \fBTst_lpstart\fR and \fBTst_lptotal\fR
+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 \fBTst_lpstart\fR to
+\fBTst_count\fR, and \fBTst_lptotal\fR to the number of test cases in the
+loop.  If a test calls \fBtst_brkloop()\fR or \fBtst_brkloopm()\fR without
+first setting \fBTst_lpstart\fR and \fBTst_lptotal\fR 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 \fBtst_brk()\fR functions, \fBtst_brkloop()\fR and
+\fBtst_brkloopm()\fR will not call \fBtst_exit()\fR if the \fIfunc\fR
+argument is not NULL and returns.  \fBtst_brkloop()\fR takes the \fIfname\fR
+argument whereas \fBtst_brkloopm()\fR does not.
+\fBtst_flush()\fR is used to print any results pending because of
+\fBCONDENSE\fR or \fBNOPASS\fR modes (described below), and flushes the
+output stream.
+\fBtst_exit()\fR 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:
+.RS 5
+.TP 10
+0000	/* .... .... */
+.TP 10
+0001	/* .... ...1 */
+.TP 10
+0002	/* .... ..1. */
+.TP 10
+0004	/* .... .1.. */
+.TP 10
+0010	/* .... 1... */
+.TP 10
+0020	/* ...1 .... */
+.TP 10
+0040	/* ..1. .... */
+NOTE: \fBTPASS, TRETR, TINFO\fR, and \fBTCONF\fR do not have an effect
+on the test program exit status.
+\fBtst_environ()\fR 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.  \fBtst_environ()\fR returns 0 upon successful completion, and -1 if it
+encountered any problems.
+.SS Output Modes
+Four output display modes are supported by the \fBtst_res()\fR family of
+functions to enhance output readability.  The active mode is controlled via
+the environment variable \fBTOUTPUT\fR, which must be set prior to the start
+of the test in order to have any effect (see \fBksh\fR(1) for information on
+environment variables).  The supported modes are as follows:
+.RS 5
+.TP 15
+A test result output line is generated for each test result.  This is the
+default mode.
+.TP 15
+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.
+.TP 15
+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
+\fBCONDENSE\fR mode.  WARN output lines are printed as usual.
+.TP 15
+All output lines are discarded.
+#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 */
+		.
+		.
+	/* a successful test result */
+	tst_resm(TPASS, "\fIwhat was tested\fR");
+		/* or */
+	tst_res(TPASS, file, "\fIwhat was tested\fR");
+		.
+		.
+   /* break all remaining test results */
+	tst_brkm(TBROK, cleanup, "\fIwhat didn't work\fR");
+		/* or */
+	tst_brk(TBROK, file, cleanup, "\fIwhat didn't work\fR");
+		.
+		.
+	/* Break all remaining tests in loop */
+	Tst_lpstart = Tst_count;
+	Tst_lptotal = 5;
+	tst_brkloopm(TBROK, loop_setup, "\fIsetup did not work.\fR");
+		/* or */
+	tst_brkloop(TBROK, file, loop_setup, "\fIsetup did not work.\fR");
+		.
+		.
+   /* exit after all test results have been passed to tst_res */
+	tst_exit();
+Sample output:
+.RS 5
+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:
+.RS 5
+If an invalid test type is specified.
+If \fBTst_count\fR is negative.
+If \fBTst_range\fR is non-positive.
+If \fBTst_range\fR is > 1, and the test type is \fBTINFO\fR or \fBTWARN\fR.
+If one of the \fBtst_brk[loop][m]()\fR routines is called with a test type
+other than \fBTFAIL, TBROK, TCONF\fR, or \fBTRETR\fR.
+If \fBTst_lpstart\fR is negative.
+If \fBTst_lptotal\fR is non-positive.
+If there are any problems opening/reading/writing the contents of \fIfname\fR.
+If \fIfname\fR is NULL and \fItmesg\fR 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.
+The programmer is free to alter the value of \fBTst_count\fR causing possible
+test result order problems.