--- a
+++ b/doc/man3/tst_sig.3
@@ -0,0 +1,142 @@
+.\"
+.\" $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., 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_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 SIGCLD 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 SIGCLD signal).
+.P
+Setting \fIfork_flag\fR to FORK will cause \fItst_sig\fR to
+ignore the SIGCLD 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 SIGCLD 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_res(3),
+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.