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);

DIAGNOSTICS

Tst_sig will output warnings in standard tst_res format if it cannot set up the signal handlers.