NAME
tst_sig - set up for unexpected signals
SYNOPSIS
#include "test.h"
void tst_sig(fork_flag, handler, cleanup)
char *fork_flag;
int (*handler)();
void (*cleanup)();
DESCRIPTION
Tst_sig 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. Tst_sig should be called only once by a test program.
The fork_flag parameter is used to tell tst_sig whether or not to
ignore the SIGCLD signal caused by the death of a child process that
had previously been created by the fork(2) system call (see signal(2)
for more information on the SIGCLD signal).
Setting fork_flag to FORK will cause tst_sig to ignore the SIGCLD
signal. This option should be set if the test program directly (eg.
call fork(2)) or indirectly (eg. call system(3S)) creates a child
process.
Setting fork_flag to NOFORK will cause tst_sig to treat the SIGCLD
signal just as any other unexpected signal (ie. the handler will be
called). This option should be set by any test program which does not
directly or indirectly create any child processes.
The handler 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 default handler supplied by tst_sig.
The default handler is specified by passing DEF_HANDLER as the handler
argument. Upon receipt of an unexpected signal, the default handler
will generate tst_res(3) messages for all test results that had not
been completed at the time of the signal, execute the cleanup routine,
if provided, and call tst_exit. Note: if the default handler is used,
the variables TCID and Tst_count must be defined and available to
tst_sig (see tst_res(3)).
The cleanup parameter is a pointer to a user-defined function returning
type void which is executed by the default handler. The cleanup
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.
EXAMPLES
#include "test.h"
/*
* the TCID and TST_TOTAL variables must be available to tst_sig
* if the default handler is used. The default handler will call
* tst_res(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 fork() system calls will be executed during the test run
* use the default signal handler provided by tst_sig
* no cleanup is necessary
*/
tst_sig(NOFORK, DEF_HANDLER, NULL);
void tst_sig(), cleanup();
int handler();
/*
* set up for unexpected signals:
* fork() system calls will be executed during the test run
* use user-defined signal handler
* use cleanup
*/
tst_sig(FORK, handler, cleanup);
SEE ALSO
signal(2), tst_res(3), tst_setup(1).
DIAGNOSTICS
Tst_sig will output warnings in standard tst_res format if it cannot
set up the signal handlers.