| .\" $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., 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 USCTEST 3 07/25/2000 "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. A complete |
| template may be found in the CUTS/sun/skel directory, in the file \fBusctest.c\fR. |
| |
| .nf |
| void |
| setup() |
| { |
| TEST_PAUSE; /* Pause if option specified */ |
| } |
| |
| void |
| cleanup() |
| { |
| TEST_CLEANUP; |
| } |
| |
| int main(ac, av) |
| { |
| int lc; /* loop counter */ |
| char *msg; /* return from parse_opts */ |
| |
| int exp_enos[]={EACCESS, 0}; /* expected errnos */ |
| |
| |
| TEST_EXP_ENOS(exp_enos); /* set expected errnos */ |
| |
| setup(); /* execute setup */ |
| |
| /* parse options */ |
| msg=parse_opts(ac, av, (option_t *)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(); |
| |
| return 0; |
| } |
| .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. |