Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.

Close

[7ce3a7]: doc / man3 / tst_res.3 Maximize Restore History

Download this file

tst_res.3    378 lines (370 with data), 14.3 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
.\"
.\" $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
.\" 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., 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"
.SH NAME
tst_res \- Print result message, including file contents
.sp
tst_resm \- Print result message
.sp
tst_brk \- Print result message and break remaining test cases
.sp
tst_brkm \- Print result message, including file contents, and break remaining test cases
.sp
tst_brkloop \- Print result message and break remaining test cases in loop
.sp
tst_brkloopm \- Print result message, including file contents, and break remaining test cases in loop
.sp
tst_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
\fBvoid tst_res(int \fIttype\fB, char *\fIfname\fB, char *\fItmesg,
[arg ...]\fR)
.P
\fBvoid tst_resm(int \fIttype\fB, char *\fItmesg, [arg ...]\fR)
.P
\fBvoid tst_brk(int \fIttype\fB, char *\fIfname\fB, void (*\fIfunc\fB)(),
char *\fItmesg, [arg ...]\fR)
.P
\fBvoid tst_brkm(int \fIttype\fB, void (*\fIfunc\fB)(), char *\fItmesg,
[arg ...]\fR)
.P
\fBvoid tst_brkloop(int \fIttype\fB, char *\fIfname\fB, void (*\fIfunc\fB)(),
char *\fItmesg, [arg ...]\fR)
.P
\fBvoid tst_brkloopm(int \fIttype\fB, void (*\fIfunc\fB)(), char *\fItmesg,
[arg ...]\fR)
.P
\fBvoid tst_flush()
.P
\fBvoid tst_exit()
.P
\fBint tst_environ()
.P
\fBextern int Tst_count;
.br
extern int Tst_range;
.br
extern int Tst_lpstart;
.br
extern int Tst_lptotal;
\fR
.SH DESCRIPTION
.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.
.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. \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.
.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.
.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 TRETR
The test case was no longer valid and has been "retired."
.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_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.
.P
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.
.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,
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.
.P
\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.
.P
\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.
.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
TRETR
0010 /* .... 1... */
.TP 10
TINFO
0020 /* ...1 .... */
.TP 10
TCONF
0040 /* ..1. .... */
.RE
.P
NOTE: \fBTPASS, TRETR, TINFO\fR, and \fBTCONF\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_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
.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 */
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, "\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();
}
.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
tsttcs01 4-10 BROK : Remaining cases broken
tsttcs01 0 WARN : cleanup(): kill(0, SIGALRM) failed; errno = 3: No such process
.fi
.SH "SEE ALSO"
utst_res(1),
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 \fBTst_range\fR is non-positive.
.P
If \fBTst_range\fR is > 1, and the test type is \fBTINFO\fR or \fBTWARN\fR.
.P
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.
.P
If \fBTst_lpstart\fR is negative.
.P
If \fBTst_lptotal\fR is non-positive.
.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 BUGS
.P
The programmer is free to alter the value of \fBTst_count\fR causing possible
test result order problems.