[7ce3a7]: / doc / man3 / tst_sig.3  Maximize  Restore  History

Download this file

143 lines (130 with data), 4.9 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
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.