| .\" |
| .\" $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. |