c_install_cleanup_handler - Changes the signal handler to call the specified sig_hand function for a standard set of signals thrown by TAE

SYNTAX

#include "worgen.h"
#include "util.h"
int c_install_cleanup_handler
(
   void (*sig_hand)(int)   /* I: signal handler function */
)

PARAMETERS

sig_hand (input, void * function (int))

Pointer to the signal handler function, which includes an integer parameter.

DESCRIPTION

The c_install_cleanup_handler() routine is used to change the way signals are handled. This function resets the signal handler to call the specified function when the signal is thrown by the application. E_SUCC is returned if signal handler was successfully reset. E_FAIL is returned if an error occurred resetting the signal handler.

RETURN VALUE

c_install_cleanup_handler() returns

     E_SUCC (0)  --> successful completion
     E_FAIL (-1) --> operation failed

NOTES

1) At this time this library handles the SIGTERM and SIGABRT signals.
2) c_install_cleanup_handler() should be called from your main function as soon as you desire to start catching the SIGTERM and SIGABRT signals.
3) If the SIGTERM or SIGABRT signals get thrown for any reason, this routine will set your program up to catch these signals and call the function that is passed in as sig_hand. Instead of stopping execution when these signals are thrown, which is the default, your sig_hand function can unmount tapes and CDs and clean up any files that may need to be deleted. Your sig_hand function should then exit with the following call 'exit (EXIT_FAILURE);'
4) signal_cleanup.c in L7HDF2LAS is an example of a cleanup function that was written for the L7HDF2LAS application. Use it as an example for other signal handler functions if needed.
5) It is important to prevent race conditions when using a signal handler. Your application should know the exact status of anything that needs to be cleaned up, and should be prepared to handle a signal that is thrown while cleaning up your files or unmounting your tape/CD. When deleting an array of files, delete them from the end of the list and decrement the file counter. If a signal is thrown while deleting the files, the status of the file counter should be correct.
6) The signal handlers set by this routine should be reset to their original status by using the c_remove_signal_handler() routine, once they are no longer needed. c_remove_signal_handler() will reset the status of the install_initialized variable to specify that the cleanup has taken place.
7) This routine should not be called more than once without first resetting the signal handlers using c_remove_signal_handler().