github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/docs/events/onsignalreceived.md (about)

     1  # `onSignalReceived`
     2  
     3  > Trap OS signals
     4  
     5  ## Description
     6  
     7  `onSignalReceived` events are triggered by OS signals.
     8  
     9  The following quote from [Wikipedia explains what signals](https://en.wikipedia.org/wiki/Signal_(IPC))
    10  are:
    11  
    12  > Signals are standardized messages sent to a running program to trigger
    13  > specific behavior, such as quitting or error handling. They are a limited
    14  > form of inter-process communication (IPC), typically used in Unix, Unix-like,
    15  > and other POSIX-compliant operating systems.
    16  >
    17  > A signal is an asynchronous notification sent to a process or to a specific
    18  > thread within the same process to notify it of an event. Common uses of
    19  > signals are to interrupt, suspend, terminate or kill a process.
    20  
    21  This event is designed to be used in shell scripts. While this event can be
    22  used with the shell in interactive mode (ie from the REPL prompt), this might
    23  result in unexpected behaviour. Thus it is only recommended to use
    24  `onSignalReceived` for shell scripts.
    25  
    26  ## Usage
    27  
    28  ```
    29  event onSignalReceived name=SIGNAL { code block }
    30  
    31  !event onSignalReceived [SIGNAL]name
    32  ```
    33  
    34  ## Valid Interrupts
    35  
    36  * `SIGHUP`
    37      **"Signal hangup"** -- triggered when a controlling terminal is closed (eg the terminal emulator closed)
    38  * `SIGINT`
    39      **"Signal interrupt"** -- triggered when a user interrupts a process, typically via `ctrl`+`c`
    40  * `SIGQUIT`
    41      **"Signal quit"** -- when the user requests that the process quits and performs a core dump
    42  * `SIGTERM`
    43      **"Signal terminate"** -- triggered by a request for a processes termination. Similar to `SIGINT`
    44  * `SIGUSR1`
    45      **"Signal user 1"** -- user defined
    46  * `SIGUSR2`
    47      **"Signal user 2"** -- user defined
    48  * `SIGWINCH`
    49      **"Signal window change"** -- triggered when the TTY (eg terminal emulator) is resized
    50  
    51  ## Payload
    52  
    53  The following payload is passed to the function via STDIN:
    54  
    55  ```
    56  {
    57      "Name": "",
    58      "Interrupt": {
    59          "Name": "",
    60          "Signal": ""
    61      }
    62  }
    63  ```
    64  
    65  ### Name
    66  
    67  This is the **namespaced** name -- ie the name and operation.
    68  
    69  ### Interrupt/Name
    70  
    71  This is the name you specified when defining the event.
    72  
    73  ### Signal
    74  
    75  This is the signal you specified when defining the event.
    76  
    77  Valid interrupt operation values are specified below. All interrupts / signals
    78  are UPPERCASE strings.
    79  
    80  ## Examples
    81  
    82  **Interrupt 'SIGINT':**
    83  
    84  ```
    85  event onSignalReceived example=SIGINT {
    86      out "SIGINT received, not quitting"
    87  }
    88  ```
    89  
    90  ## Detail
    91  
    92  The interrupts listed above are a subset of what is supported on each operating
    93  system. Please consult your operating systems docs for details on each signal
    94  and what their function is.
    95  
    96  ### Windows Support
    97  
    98  While Windows doesn't officially support signals, the following POSIX signals
    99  are emulated:
   100  
   101  ```go
   102  var interrupts = map[string]syscall.Signal{
   103  	"SIGHUP":  syscall.SIGHUP,
   104  	"SIGINT":  syscall.SIGINT,
   105  	"SIGQUIT": syscall.SIGQUIT,
   106  	"SIGILL":  syscall.SIGILL,
   107  	"SIGTRAP": syscall.SIGTRAP,
   108  	"SIGABRT": syscall.SIGABRT,
   109  	"SIGBUS":  syscall.SIGBUS,
   110  	"SIGFPE":  syscall.SIGFPE,
   111  	"SIGKILL": syscall.SIGKILL,
   112  	"SIGSEGV": syscall.SIGSEGV,
   113  	"SIGPIPE": syscall.SIGPIPE,
   114  	"SIGALRM": syscall.SIGALRM,
   115  	"SIGTERM": syscall.SIGTERM,
   116  }
   117  ```
   118  
   119  ### Plan 9 Support
   120  
   121  Plan 9 is not supported.
   122  
   123  ### Stdout
   124  
   125  Stdout is written to the terminal. So this can be used to provide multiple
   126  additional lines to the prompt since readline only supports one line for the
   127  prompt itself and three extra lines for the hint text.
   128  
   129  ### Order of execution
   130  
   131  Interrupts are run in alphabetical order. So an event named "alfa" would run
   132  before an event named "zulu". If you are writing multiple events and the order
   133  of execution matters, then you can prefix the names with a number, eg `10_jump`
   134  
   135  ### Namespacing
   136  
   137  The `onSignalReceived` event differs a little from other events when it comes
   138  to the namespacing of interrupts. Typically you cannot have multiple interrupts
   139  with the same name for an event. However with `onPrompt` their names are
   140  further namespaced by the interrupt name. In layman's terms this means
   141  `example=SIGINT` wouldn't overwrite `example=SIGQUIT`.
   142  
   143  The reason for this namespacing is because, unlike other events, you might
   144  legitimately want the same name for different interrupts.
   145  
   146  ## See Also
   147  
   148  * [Interactive Shell](../user-guide/interactive-shell.md):
   149    What's different about Murex's interactive shell?
   150  * [Terminal Hotkeys](../user-guide/terminal-keys.md):
   151    A list of all the terminal hotkeys and their uses
   152  * [`event`](../commands/event.md):
   153    Event driven programming for shell scripts
   154  * [`onCommandCompletion`](../events/oncommandcompletion.md):
   155    Trigger an event upon a command's completion
   156  * [`onPrompt`](../events/onprompt.md):
   157    Events triggered by changes in state of the interactive shell
   158  * [`signal`](../commands/signal.md):
   159    Sends a signal RPC
   160  
   161  <hr/>
   162  
   163  This document was generated from [builtins/events/onSignalReceived/signaltrap_doc.yaml](https://github.com/lmorg/murex/blob/master/builtins/events/onSignalReceived/signaltrap_doc.yaml).