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
|
.\" $Id: usctest.3,v 1.2 2000/08/31 18:40:28 nstraz 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 USCTEST 3 01/21/2011 "Linux Test Project"
.SH NAME
usctest \- macros and libraries for common functions in system call tests
.SH SYNOPSIS
\fBRoutines:\fR
.br
.in +1
char *\fBparse_opts(\fI...\fB)\fR
.in -1
.sp
\fBMacros\fR
.in +1
.br
\fBTEST_PAUSE\fR
.br
\fBTEST_PAUSEF(\fIhand\fB)\fR
.br
\fBTEST(\fIsyscall\fB)\fR
.br
.\"\fBTEST_CALLER(\fIsyscall\fB, \fIpid\fB)\fR
.\".br
\fBTEST_VOID(\fIsyscall\fB)\fR
.br
\fBTEST_CLEANUP\fR
.br
\fBTEST_LOOPING(\fIcounter\fB)\fR
.br
\fBTEST_ERROR_LOG(\fIerrno\fB)\fR
.br
\fBTEST_EXP_ENOS(\fIarray\fB)\fR
.in -1
.sp
\fBGlobal Variable(s)\fR (see \fBparse_opts(3)\fR for complete list):
.br
.in +1
int \fBTEST_RETURN\fR; /* set by the \fBTEST\fR macro to the return code from \fIsyscall\fR */
.br
int \fBTEST_ERRNO\fR; /* set by the \fBTEST\fR macro to the value of \fBerrno\fR after \fIsyscall\fR returns */
.br
/* All STD_* variables referenced below are set by the \fBparse_opts(3)\fR routine. */
.in -1
.SH DESCRIPTION
The \fBTEST_PAUSE\fR macro checks if the global variable STD_PAUSE is set. If so, it
pauses for a SIGUSR1 before continuing execution. The signal handler used does nothing.
After the signal is processed, the previous action is replaced for SIGUSR1.
.sp
The \fBTEST_PAUSEF(\fIhand\fB)\fR macro checks if the global variable STD_PAUSE is set. If so, it
pauses for a SIGUSR1 before continuing execution. The \fIhand\fR argument is a function to be used
to handle the SIGUSR1 signal when it is received.
After the signal is processed, the previous action is replaced for SIGUSR1.
.sp
The \fBTEST(\fIsyscall\fB)\fR macro executes (\fIsyscall\fR) and times its execution.
It saves the max time, min time, accumulated time, and
execution count, if STD_TIMING_ON is set.
.sp
.\"The\fBTEST_CALLER(\fIsyscall\fB, \fIpid\fB)\fR macro executes (\fIsyscall\fR) and times its execution.
.\"It saves the max time, min time, accumulated time, and
.\"execution count, if STD_TIMING_ON is set and if \fIpid\fR is equal to the current pid.
.\".sp
The \fBTEST_VOID(\fIsyscall\fB)\fR macro works exactly the same as the \fBTEST()\fR
macro except that it does NOT set the global \fBTEST_RETURN\fR. It is intended
to be used with system calls that do not have a return value.
.sp
The \fBTEST_CLEANUP\fR macro prints timing statistics,
accumulated through the TEST macro, if STD_TIMING_ON is set. Also, prints the \fBerrno\fR return
counts as logged by the \fBTEST_ERROR_LOG\fR macro, if STD_ERR_LOG is set. \fBTEST_CLEANUP\fR uses
\fBtst_resm(3)\fR to output this information.
.sp
The \fBTEST_LOOPING(\fIcounter\fB)\fR macro checks \fIcounter\fR against
the global variable STD_LOOP_COUNTER. If \fIcounter\fR is less than STD_LOOP_COUNTER or STD_INFINITE
is set, it returns TRUE.
.sp
The \fBTEST_ERROR_LOG\fR macro records the return of \fIerrno\fR as unexpected, unless the option to
turn it off is specified on the command line.
.sp
The \fBTEST_EXP_ENOS(\fIarray\fB)\fR macro sets an internal flag for each errno in \fIarray\fR, indicating
that the errno is expected at some point in the test. This is used by the TEST_CLEANUP macro to determine
which errnos are expected when printing the log. The \fIarray\fR must be zero terminated.
.sp
The \fBparse_opts\fR routine parses the command line (see \fBparse_opts(3)\fR). All STD_* global
variables used are set by the \fBparse_opts(3)\fR routine.
.SH EXAMPLES
Below is a partial template of a system call test using these routines, macros, and global variables.
.nf
void setup(void)
{
TEST_PAUSE; /* Pause if option specified */
}
void cleanup(void)
{
TEST_CLEANUP;
}
int main(int argc, char *argv[])
{
int lc;
char *msg;
int exp_enos[]={EACCESS, 0};
TEST_EXP_ENOS(exp_enos); /* set expected errnos */
setup(); /* execute setup */
/* parse options */
msg = parse_opts(ac, av, NULL, NULL);
/* Check parse_opts return */
for (lc=0; TEST_LOOPING(lc); lc++) {
TEST(open("file", O_RDWR))
if (TEST_RETURN == -1) {
TEST_ERROR_LOG(TEST_ERRNO)
/* BREAK test case, or whatever... */
}
}
cleanup();
tst_exit();
}
.fi
.SH "SEE ALSO"
parse_opts(3).
.SH "RETURN VALUES"
The TEST_LOOPING macro evaluates to TRUE (1) or FALSE (0), and is intended for use in while or
for loops. The TEST macro places the return value from \fIsyscall\fR in the global variable TEST_RETURN
and the errno in the global variable TEST_ERRNO. The \fBTEST_PAUSE\fR, \fBTEST_PAUSEF\fR,
\fBTEST_CLEANUP\fR, \fBTEST_ERROR_LOG\fR, and \fBTEST_EXP_ENOS\fR macros do not have any return values.
|
