Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

Diff of /doc/man3/usctest.3 [000000] .. [7ce3a7] Maximize Restore

  Switch to side-by-side view

--- a
+++ b/doc/man3/usctest.3
@@ -0,0 +1,171 @@
+.\" $Id: usctest.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 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
+}
+
+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();
+}
+.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.