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

     1  # `signal`
     2  
     3  > Sends a signal RPC
     4  
     5  ## Description
     6  
     7  `signal` sends an operating system RPC (known as "signal") to a specified
     8  process, identified via it's process ID ("pid").
     9  
    10  The following quote from [Wikipedia explains what signals](https://en.wikipedia.org/wiki/Signal_(IPC))
    11  are:
    12  
    13  > Signals are standardized messages sent to a running program to trigger
    14  > specific behavior, such as quitting or error handling. They are a limited
    15  > form of inter-process communication (IPC), typically used in Unix, Unix-like,
    16  > and other POSIX-compliant operating systems.
    17  >
    18  > A signal is an asynchronous notification sent to a process or to a specific
    19  > thread within the same process to notify it of an event. Common uses of
    20  > signals are to interrupt, suspend, terminate or kill a process.
    21  
    22  ### Listing supported signals
    23  
    24  Signals will differ from one operating system to another. You can retrieve a
    25  JSON map with supported signals by running `signal` without any parameters.
    26  
    27  ## Usage
    28  
    29  **Send a signal:**
    30  
    31  1. The first parameter is the process ID (int)
    32  2. The second parameter is the signal name (str). This will be all in
    33     UPPERCASE and prefixed "SIG"
    34  
    35  ```
    36  signal pid SIGNAL
    37  ```
    38  
    39  **List supported signals:**
    40  
    41  ```
    42  signal -> <stdout>
    43  ```
    44  
    45  ## Examples
    46  
    47  **Send a signal:**
    48  
    49  ```
    50  function signal.SIGUSR1.trap {
    51      bg {
    52          exec <pid:MOD.SIGNAL_TRAP_PID> $MUREX_EXE -c %(
    53              event onSignalReceived example=SIGUSR1 {
    54                  out "SIGUSR1 received..."
    55              }
    56  
    57              out "waiting for signal..."
    58              sleep 5
    59          )
    60      }
    61      sleep 2 # just in case `exec` hasn't started yet
    62      signal $MOD.SIGNAL_TRAP_PID SIGUSR1
    63  }
    64  
    65  test unit function signal.SIGUSR1.trap %{
    66      StdoutMatch: "waiting for signal...\nSIGUSR1 received...\n"
    67      DataType:    str
    68      ExitNum:     0
    69  }
    70  ```
    71  
    72  **List supported signals:**
    73  
    74  ```
    75  ยป signal
    76  {
    77      "SIGABRT": "aborted",
    78      "SIGALRM": "alarm clock",
    79      "SIGBUS": "bus error",
    80      "SIGCHLD": "child exited",
    81      "SIGCONT": "continued",
    82      "SIGFPE": "floating point exception",
    83      "SIGHUP": "hangup",
    84      "SIGILL": "illegal instruction",
    85      "SIGINT": "interrupt",
    86      "SIGIO": "I/O possible",
    87      "SIGKILL": "killed",
    88      "SIGPIPE": "broken pipe",
    89      "SIGPROF": "profiling timer expired",
    90      "SIGPWR": "power failure",
    91      "SIGQUIT": "quit",
    92      "SIGSEGV": "segmentation fault",
    93      "SIGSTKFLT": "stack fault",
    94      "SIGSTOP": "stopped (signal)",
    95      "SIGSYS": "bad system call",
    96      "SIGTRAP": "trace/breakpoint trap",
    97      "SIGTSTP": "stopped",
    98      "SIGTTIN": "stopped (tty input)",
    99      "SIGTTOU": "stopped (tty output)",
   100      "SIGURG": "urgent I/O condition",
   101      "SIGUSR1": "user defined signal 1",
   102      "SIGUSR2": "user defined signal 2",
   103      "SIGVTALRM": "virtual timer expired",
   104      "SIGWINCH": "window changed",
   105      "SIGXCPU": "CPU time limit exceeded",
   106      "SIGXFSZ": "file size limit exceeded"
   107  }
   108  ```
   109  
   110  ## Flags
   111  
   112  * `SIGINT`
   113      **"Signal interrupt"** -- equivalent to pressing `ctrl`+`c`
   114  * `SIGQUIT`
   115      **"Signal quit"** -- requests the process quits and performs a core dump
   116  * `SIGTERM`
   117      **"Signal terminate"** -- request for a processes termination. Similar to `SIGINT`
   118  * `SIGUSR1`
   119      **"Signal user 1"** -- user defined
   120  * `SIGUSR2`
   121      **"Signal user 2"** -- user defined
   122  
   123  ## Detail
   124  
   125  The interrupts listed above are a subset of what is supported on each operating
   126  system. Please consult your operating systems docs for details on each signal
   127  and what their function is.
   128  
   129  ### Windows Support
   130  
   131  While Windows doesn't officially support signals, the following POSIX signals
   132  are emulated:
   133  
   134  ```go
   135  var interrupts = map[string]syscall.Signal{
   136  	"SIGHUP":  syscall.SIGHUP,
   137  	"SIGINT":  syscall.SIGINT,
   138  	"SIGQUIT": syscall.SIGQUIT,
   139  	"SIGILL":  syscall.SIGILL,
   140  	"SIGTRAP": syscall.SIGTRAP,
   141  	"SIGABRT": syscall.SIGABRT,
   142  	"SIGBUS":  syscall.SIGBUS,
   143  	"SIGFPE":  syscall.SIGFPE,
   144  	"SIGKILL": syscall.SIGKILL,
   145  	"SIGSEGV": syscall.SIGSEGV,
   146  	"SIGPIPE": syscall.SIGPIPE,
   147  	"SIGALRM": syscall.SIGALRM,
   148  	"SIGTERM": syscall.SIGTERM,
   149  }
   150  ```
   151  
   152  ### Plan 9 Support
   153  
   154  Plan 9 is not supported.
   155  
   156  ### Catching incoming signals
   157  
   158  Signals can be caught (often referred to as "trapped") in Murex with an event:
   159  `signalTrap`. Read below for details.
   160  
   161  ## See Also
   162  
   163  * [Interactive Shell](../user-guide/interactive-shell.md):
   164    What's different about Murex's interactive shell?
   165  * [MUREX_EXE](../variables/murex_exe.md):
   166    Absolute path to running shell
   167  * [Terminal Hotkeys](../user-guide/terminal-keys.md):
   168    A list of all the terminal hotkeys and their uses
   169  * [`bg`](../commands/bg.md):
   170    Run processes in the background
   171  * [`event`](../commands/event.md):
   172    Event driven programming for shell scripts
   173  * [`out`](../commands/out.md):
   174    Print a string to the STDOUT with a trailing new line character
   175  * [onSignalReceived](../events/onsignalreceived.md):
   176    Trap OS signals
   177  
   178  <hr/>
   179  
   180  This document was generated from [builtins/events/onSignalReceived/signal_doc.yaml](https://github.com/lmorg/murex/blob/master/builtins/events/onSignalReceived/signal_doc.yaml).