You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
314 lines
11 KiB
314 lines
11 KiB
.\"
|
|
.\" $Id: tst_res.3,v 1.2 2008/06/10 05:52:02 subrata_modak 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
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
|
.\"
|
|
.\" 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.,
|
|
.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 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 01/21/2011 "Linux Test Project"
|
|
.SH NAME
|
|
tst_resm \- Print result message
|
|
.sp
|
|
tst_resm_hexd \- Print result message, including specified buffer in hexadecimal format
|
|
.sp
|
|
tst_brkm \- Print result message and break remaining test cases
|
|
.sp
|
|
tst_old_flush \- Print any messages pending because of CONDENSE mode, and flush output stream
|
|
.sp
|
|
tst_exit \- Exit test with a meaningful exit value
|
|
.sp
|
|
tst_environ \- Keep results coming to original stdout
|
|
.SH SYNOPSIS
|
|
\fB#include "test.h"\fR
|
|
.P
|
|
.P
|
|
\fBvoid tst_resm(int \fIttype\fB, char *\fItmesg, [arg ...]\fR)
|
|
.P
|
|
\fBvoid tst_resm_hexd(int \fIttype\fB, const void *\fIbuf\fB, size_t \fIsize\fB,
|
|
char *\fItmesg, [arg ...]\fR)
|
|
.P
|
|
\fBvoid tst_brkm(int \fIttype\fB, void (*\fIfunc\fB)(), char *\fItmesg,
|
|
[arg ...]\fR)
|
|
.P
|
|
\fBvoid tst_old_flush()
|
|
.P
|
|
\fBvoid tst_exit()
|
|
.P
|
|
\fBint tst_environ()
|
|
.P
|
|
\fBextern int tst_count;
|
|
.br
|
|
extern int tst_range;
|
|
.br
|
|
\fR
|
|
.SH DESCRIPTION
|
|
.SS Introduction
|
|
This library of functions are used by UNICOS tests to report results to
|
|
standard output 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\fR, \fBTST_TOTAL\fR,
|
|
\fBtst_count\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.
|
|
.P
|
|
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
|
|
reported.
|
|
.P
|
|
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.
|
|
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, 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.
|
|
.br
|
|
\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
|
|
loop.
|
|
.TP 10
|
|
.I buf
|
|
pointer to a buffer whose contents will be printed in hexadecimal format.
|
|
.TP 10
|
|
.I size
|
|
size of the buffer.
|
|
.RE
|
|
.SS Result Types
|
|
The possible test result types defined in \fBtest.h\fR are as follows:
|
|
.RS 5
|
|
.TP 10
|
|
.B TPASS
|
|
The test case produced expected results.
|
|
.TP 10
|
|
.B TFAIL
|
|
The test case produced unexpected results.
|
|
.TP 10
|
|
.B TBROK
|
|
A resource needed to execute the test case was not available (e.g. a
|
|
temporary file could not be opened).
|
|
.TP 10
|
|
.B TCONF
|
|
The test case was not appropriate for the current hardware or software
|
|
configuration (e.g. MLS was not enabled).
|
|
.TP 10
|
|
.B 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).
|
|
.TP 10
|
|
.B 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.
|
|
.RE
|
|
.SS Function Descriptions
|
|
|
|
\fBtst_resm()\fR and \fBtst_resm_hexd()\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.
|
|
.P
|
|
\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,
|
|
and TCONF\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, 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.
|
|
.P
|
|
\fBtst_old_flush()\fR is used to print any results pending because of
|
|
\fBCONDENSE\fR or \fBNOPASS\fR modes (described below), and flushes the
|
|
output stream.
|
|
.P
|
|
\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.
|
|
.P
|
|
The current bit fields for the result types are as follows:
|
|
.RS 5
|
|
.TP 10
|
|
TPASS
|
|
0000 /* .... .... */
|
|
.TP 10
|
|
TFAIL
|
|
0001 /* .... ...1 */
|
|
.TP 10
|
|
TBROK
|
|
0002 /* .... ..1. */
|
|
.TP 10
|
|
TWARN
|
|
0004 /* .... .1.. */
|
|
.TP 10
|
|
TINFO
|
|
0020 /* ...1 .... */
|
|
.TP 10
|
|
TCONF
|
|
0040 /* ..1. .... */
|
|
.RE
|
|
.P
|
|
NOTE: \fBTPASS and TINFO\fR do not have an effect
|
|
on the test program exit status.
|
|
.P
|
|
\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_resm()\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
|
|
.B VERBOSE
|
|
A test result output line is generated for each test result. This is the
|
|
default mode.
|
|
.TP 15
|
|
.B 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.
|
|
.TP 15
|
|
.B 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
|
|
\fBCONDENSE\fR mode. WARN output lines are printed as usual.
|
|
.TP 15
|
|
.B DISCARD
|
|
All output lines are discarded.
|
|
.RE
|
|
.SH EXAMPLES
|
|
.nf
|
|
#include "test.h"
|
|
|
|
char *TCID = "tsttcs01"; /* set test case identifier */
|
|
int TST_TOTAL = 15; /* set total number of test results */
|
|
|
|
main()
|
|
{
|
|
.
|
|
.
|
|
/* a successful test result */
|
|
tst_resm(TPASS, "\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");
|
|
.
|
|
.
|
|
|
|
/* exit after all test results have been passed to tst_res */
|
|
tst_exit();
|
|
}
|
|
.fi
|
|
.P
|
|
Sample output:
|
|
.RS 5
|
|
.nf
|
|
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
|
|
.fi
|
|
.SH "SEE ALSO"
|
|
tst_setup(1),
|
|
printf(3C),
|
|
ksh(1).
|
|
.SH DIAGNOSTICS
|
|
.P
|
|
A WARN result message will be printed if any of the following occur:
|
|
.RS 5
|
|
.P
|
|
If an invalid test type is specified.
|
|
.P
|
|
If \fBtst_count\fR is negative.
|
|
.P
|
|
If one of the \fBtst_brk[m]()\fR routines is called with a test type
|
|
other than \fBTFAIL, TBROK, TCONF\fR.
|
|
.P
|
|
If there are any problems opening/reading/writing the contents of \fIfname\fR.
|
|
.RE
|
|
.SH LIMITATIONS
|
|
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.
|
|
.SH NOTES
|
|
In multithreaded environment, output of \fBtst_resm_hexd()\fR may be interleaved
|
|
with messages produced by other threads.
|
|
.SH BUGS
|
|
.P
|
|
The programmer is free to alter the value of \fBtst_count\fR causing possible
|
|
test result order problems.
|