1  /* Emergency actions in case of a fatal signal.
       2     Copyright (C) 2003-2004, 2009-2023 Free Software Foundation, Inc.
       3     Written by Bruno Haible <bruno@clisp.org>, 2003.
       4  
       5     This file is free software: you can redistribute it and/or modify
       6     it under the terms of the GNU Lesser General Public License as
       7     published by the Free Software Foundation; either version 2.1 of the
       8     License, or (at your option) any later version.
       9  
      10     This file is distributed in the hope that it will be useful,
      11     but WITHOUT ANY WARRANTY; without even the implied warranty of
      12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      13     GNU Lesser General Public License for more details.
      14  
      15     You should have received a copy of the GNU Lesser General Public License
      16     along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
      17  
      18  
      19  #ifndef _FATAL_SIGNAL_H
      20  #define _FATAL_SIGNAL_H
      21  
      22  /* This file uses _GL_ASYNC_SAFE.  */
      23  #if !_GL_CONFIG_H_INCLUDED
      24   #error "Please include config.h first."
      25  #endif
      26  
      27  #include <signal.h>
      28  
      29  #ifdef __cplusplus
      30  extern "C" {
      31  #endif
      32  
      33  
      34  /* It is often useful to do some cleanup action when a usually fatal signal
      35     terminates the process, like removing a temporary file or killing a
      36     subprocess that may be stuck waiting for a device, pipe or network input.
      37     Such signals are SIGHUP, SIGINT, SIGPIPE, SIGTERM, and possibly others.
      38     The limitation of this facility is that it cannot work for SIGKILL.
      39  
      40     Signals with a SIG_IGN handler are considered to be non-fatal.  The
      41     functions in this file assume that when a SIG_IGN handler is installed
      42     for a signal, it was installed before any functions in this file were
      43     called and it stays so for the whole lifetime of the process.  */
      44  
      45  /* Register a cleanup function to be executed when a catchable fatal signal
      46     occurs.
      47  
      48     Restrictions for the cleanup function:
      49       - The cleanup function can do all kinds of system calls.  It may also
      50         modify (clobber) errno.
      51       - It can also access application dependent memory locations and data
      52         structures provided they are in a consistent state. One way to ensure
      53         this is through block_fatal_signals()/unblock_fatal_signals(), see
      54         below.  Another - more tricky - way to ensure this is the careful use
      55         of 'volatile'.
      56     However,
      57       - malloc() and similarly complex facilities are not safe to be called
      58         because they are not guaranteed to be in a consistent state.
      59       - Also, the cleanup function must not block the catchable fatal signals
      60         and leave them blocked upon return.
      61  
      62     The cleanup function is executed asynchronously.  It is unspecified
      63     whether during its execution the catchable fatal signals are blocked
      64     or not.
      65  
      66     Return 0 upon success, or -1 if there was a memory allocation problem.  */
      67  extern int at_fatal_signal (_GL_ASYNC_SAFE void (*function) (int sig));
      68  
      69  
      70  /* Sometimes it is necessary to block the usually fatal signals while the
      71     data structures being accessed by the cleanup action are being built or
      72     reorganized.  This is the case, for example, when a temporary file or
      73     directory is created through mkstemp() or mkdtemp(), because these
      74     functions create the temporary file or directory _before_ returning its
      75     name to the application.  */
      76  
      77  /* Temporarily delay the catchable fatal signals.
      78     The signals will be blocked (= delayed) until the next call to
      79     unblock_fatal_signals().  If the signals are already blocked, a further
      80     call to block_fatal_signals() has no effect.  */
      81  extern void block_fatal_signals (void);
      82  
      83  /* Stop delaying the catchable fatal signals.  */
      84  extern void unblock_fatal_signals (void);
      85  
      86  
      87  /* Return the list of signals that block_fatal_signals/unblock_fatal_signals
      88     would block or unblock.
      89     Fills signals[0..count-1] and returns count.  */
      90  extern unsigned int get_fatal_signals (int signals[64]);
      91  
      92  /* Return the list of signals that block_fatal_signals/unblock_fatal_signals
      93     would block or unblock.  */
      94  extern const sigset_t * get_fatal_signal_set (void);
      95  
      96  
      97  #ifdef __cplusplus
      98  }
      99  #endif
     100  
     101  #endif /* _FATAL_SIGNAL_H */