sigwatch(3) sigwatch(3) NNAAMMEE libsigwatch.a ‐ simple signal watching for Fortran programs SSYYNNOOPPSSIISS iinntteeggeerr ffuunnccttiioonn wwaattcchhssiiggnnaall ((ssiiggnnuumm)) iinntteeggeerr ssiiggnnuumm iinntteeggeerr ffuunnccttiioonn wwaattcchhssiiggnnaallnnaammee ((ssiiggnnaammee,, rreessppoonnssee)) cchhaarraacctteerr((**))** ssiiggnnaammee iinntteeggeerr rreessppoonnssee iinntteeggeerr ffuunnccttiioonn ggeettllaassttssiiggnnaall iinntteeggeerr ffuunnccttiioonn ssiiggwwaattcchhvveerrssiioonn DDEESSCCRRIIPPTTIIOONN lliibbssiiggwwaattcchh..aa is a library of routines to provide simple signal watch‐ ing for Fortran programs. This allows a minimal level of control of a running program from outside it, for example to tell it to checkpoint itself on receipt of a signal. Signal handling is rather tricky in Fortran (because the function that is registered as a signal handler is later called by value rather than by reference), so this library pro‐ vides functions to make it easier. On Unix, there is a smallish set of signals which may be sent to a run‐ ning process, which the process can either _c_a_t_c_h or _i_g_n_o_r_e_. For exam‐ ple, the INT signal is sent to a process by pressing the interrupt character (usually _^_C ), HUP is sent when a controlling terminal logs out, and KILL can be sent either by hand or by the system when it is forcing processes to die. The default action of the INT signal is to terminate a process, and by default the HUP signal is ignored. The KILL signal is one of those which cannot be caught or ignored, but always has its effect. There are also two signals, called USR1 and USR2 which are ignored by default, have no default meaning, and are provided for user convenience. Each signal has a numeric value ‐‐ for example HUP is 1 and KILL is 9 ‐‐ and after finding a process’s PID with the ps(1) command, you can send signals to it with the kill(1) command: kill ‐HUP _<_p_i_d_> or kill ‐1 _<_p_i_d_> Signals thus provide a limited mechanism for communicating with a run‐ ning program. A useful way to use this is to have the program watch for signal USR1, say, and examine this by calling function ggeettllaassttssiigg‐‐ nnaall at the end of a loop. If this returns a non‐zero response, you might make your program checkpoint itself ‐‐ save its state for later restart ‐‐ in case the program crashes or has to be stopped for some reason. For more details about signals, see the man pages for signal(3) or sig‐ nal(7), depending on your platform. A program prepares to receive signals by calling one of the wwaattcchhssiigg‐‐ nnaallnnaammee or wwaattcchhssiiggnnaall functions, and calls ggeettllaassttssiiggnnaall at any point to retrieve the last signal which was sent to the process. The arguments to wwaattcchhssiiggnnaallnnaammee are _s_i_g_n_a_m_e , a character string con‐ taining the name of the signal to watch for, and _r_e_s_p_o_n_s_e , an integer which will be returned by ggeettllaassttssiiggnnaall after the specified signal has been caught. The signal names which the function recognises are those most likely to be useful, namely HUP, INT, USR1 and USR2. The integer _r_e_s_p_o_n_s_e is the number which will subsequently be returned by ggeettllaassttssiiggnnaall , after this signal is caught. If this response is passed as ‐1, the signal number associated with this name is what will be returned. Note that, although both HUP and INT have generally fixed numbers, the numbers associated with signals USR1 and USR2 are differ‐ ent on different unix variants. If you need to catch another signal for some reason (make sure you understand the default behavour of the given signal first, however) you can give that signal as a number to the wwaattcchhssiiggnnaall function; when that signal is later caught, the corresponding number is what will be returned by ggeettllaassttssiiggnnaall.. The ggeettllaassttssiiggnnaall function returns the response associated with the last signal which was caught, or zero if no signal has been caught so far, or since the last call to ggeettllaassttssiiggnnaall.. That is, any caught sig‐ nal is returned only once. The installed signal handler does _n_o_t re‐throw the signal after it has caught it; this would defeat the purpose of this library for those sig‐ nals, such as HUP and INT, for which the default action is to kill the process. Also, there is no way to tell if the signal was received by being re‐thrown by another handler, installed after this one. If all of this matters to you, then this library cannot reasonably help you, and you have no hope but to learn to love the sigaction(2) manpage. When installing the handler, these functions _r_e_p_l_a_c_e any previous sig‐ nal handler. If that was a non‐default one (for example, one put there by an MPI environment) this could potentially change the behaviour of your program in an unhelpful fashion. To warn you of this, these func‐ tions return +1 in this case; this is a success return value, but also a warning that you should understand what that previous signal handler was doing there. The ssiiggwwaattcchhvveerrssiioonn function returns the version number of the library, as an integer formed from the version number by: major_version * 1000 + minor_version So that the version number 1.2, for example, would be returned as inte‐ ger 1002. EEXXAAMMPPLLEE The following Fortran program shows the library in use. program sigs implicit none integer i integer status integer watchsignal integer watchsignalname integer getlastsignal status = watchsignal(10) write(*,’("watchsignal 10:",i2)’) status status = watchsignalname("HUP", 99) write(*,’("watchsignal HUP:",i2)’) status do i=1,10 call sleep(1) write (*,’("lastsig=", i2)’) getlastsignal() enddo end SSIIGGNNAALLSS IINN CC PPRROOGGRRAAMMSS The library is intended to be callable from Fortran; there is little need for it in C programs, since the ssiiggnnaall function, and its function argument, are straightforwardly usable from C. RREETTUURRNN VVAALLUUEESS Both wwaattcchhssiiggnnaallnnaammee and wwaattcchhssiiggnnaall return 0 if the signal watching was installed successfully, and ‐1 if there was an error. If there was a non‐default signal handler already installed, it is replaced, but the routine returns 1 to warn you of this. The function ggeettllaassttssiiggnnaall returns the response associated with the last signal caught, or zero if there has been no signal caught since the last time this function was invoked. BBUUGGSS None known SSEEEE AALLSSOO sigaction(2), kill(2), signal(3), signal(7) AAUUTTHHOORR Norman Gray http://www.astro.gla.ac.uk/users/norman/ norman@astro.gla.ac.uk July 2003 sigwatch(3)