#include "worgen.h" #include "util.h"
int c_install_cleanup_handler ( void (*sig_hand)(int) /* I: signal handler function */ )
Pointer to the signal handler function, which includes an integer parameter.
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.
c_install_cleanup_handler() returns
E_SUCC (0) --> successful completion E_FAIL (-1) --> operation failed
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().