.\"
.\" $Id: tst_sig.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.,
.\" 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_SIG 3 07/25/2000 "Linux Test Project"
.SH NAME
tst_sig \- set up for unexpected signals
.SH SYNOPSIS
.nf
\fB
#include "test.h"

void tst_sig(fork_flag, handler, cleanup)
char *fork_flag;
int (*handler)();
void (*cleanup)();
\fR
.fi
.SH DESCRIPTION
.P
\fItst_sig\fR is used by UNICOS test case programs
to set up signal handling functions for unexpected
signals.  This provides test cases with a graceful means
of exiting following an unexpected interruption by a signal.
\fItst_sig\fR should be called only once by a test
program.
.P
The \fIfork_flag\fR parameter is used to tell \fItst_sig\fR
whether or not to ignore the SIGCHLD signal caused by the death of a
child process that had previously been created by the
\fIfork\fR(2) system call (see \fIsignal\fR(2) for more
information on the SIGCHLD signal).
.P
Setting \fIfork_flag\fR to FORK will cause \fItst_sig\fR to
ignore the SIGCHLD signal.  This option should be set if the
test program directly (eg. call \fIfork\fR(2)) or indirectly
(eg. call \fIsystem\fR(3S)) creates a child process.
.P
Setting \fIfork_flag\fR to NOFORK will cause \fItst_sig\fR to
treat the SIGCHLD signal just as any other unexpected
signal (ie. the \fIhandler\fR will be called).
This option should be set by any test program which does not
directly or indirectly create any child processes.
.P
The \fIhandler\fR parameter is
a pointer to a function returning type int which is
executed upon the receipt of an unexpected signal.
The test program may pass a pointer to a signal handling
function or it may elect to use a \fIdefault handler\fR
supplied by \fItst_sig\fR.

The \fIdefault handler\fR is specified by passing DEF_HANDLER
as the \fIhandler\fR argument.  Upon receipt of an unexpected
signal, the \fIdefault handler\fR will generate
\fItst_res\fR(3) messages for all test results that had
not been completed at the time of the signal, execute the
\fIcleanup\fR routine, if provided, and call \fItst_exit\fR.
Note: if the \fIdefault handler\fR is used, the variables
\fBTCID\fR and \fBtst_count\fR must be defined and available to
\fItst_sig\fR (see \fItst_res\fR(3)).
.P
The \fIcleanup\fR parameter is a pointer to a user-defined
function returning type void which is executed
by the \fIdefault handler\fR.  The \fIcleanup\fR function
should remove any files, directories, processes, etc. created
by the test program.
If no cleanup is required, this parameter should be set to NULL.

.SH EXAMPLES

.nf
#include "test.h"

/*
 * the TCID and TST_TOTAL variables must be available to tst_sig
 * if the \fIdefault handler\fR is used.  The \fIdefault handler\fR will call
 * \fItst_res\fR(3) and will need this information.
 */
int TCID = "tsttcs01";  /* set test case identifier */
int TST_TOTAL = 5;        /* set total number of test results */


	void tst_sig();

	/*
	 * set up for unexpected signals:
	 *		no \fIfork\fR() system calls will be executed during the test run
	 *		use the default signal handler provided by \fItst_sig\fR
	 *		no cleanup is necessary
	 */
	tst_sig(NOFORK, DEF_HANDLER, NULL);


	void tst_sig(), cleanup();
	int handler();

	/*
	 * set up for unexpected signals:
	 *		\fIfork\fR() system calls will be executed during the test run
	 *		use user-defined signal handler
	 *		use cleanup
	 */
	tst_sig(FORK, handler, cleanup);

.fi
.SH "SEE ALSO"
signal(2),
tst_setup(1).
.SH DIAGNOSTICS
.P
\fItst_sig\fR will output warnings in standard \fItst_res\fR
format if it cannot set up the signal handlers.