onSignalReceived
Trap OS signals
onSignalReceived
events are triggered by OS signals.
The following quote from Wikipedia explains what signals are:
Signals are standardized messages sent to a running program to trigger specific behavior, such as quitting or error handling. They are a limited form of inter-process communication (IPC), typically used in Unix, Unix-like, and other POSIX-compliant operating systems.
A signal is an asynchronous notification sent to a process or to a specific thread within the same process to notify it of an event. Common uses of signals are to interrupt, suspend, terminate or kill a process.
This event is designed to be used in shell scripts. While this event can be used with the shell in interactive mode (ie from the REPL prompt), this might result in unexpected behaviour. Thus it is only recommended to use onSignalReceived
for shell scripts.
event onSignalReceived name=SIGNAL { code block }
!event onSignalReceived [SIGNAL]name
SIGHUP
“Signal hangup” – triggered when a controlling terminal is closed (eg the terminal emulator closed)SIGINT
“Signal interrupt” – triggered when a user interrupts a process, typically via ctrl
+c
SIGQUIT
“Signal quit” – when the user requests that the process quits and performs a core dumpSIGTERM
“Signal terminate” – triggered by a request for a processes termination. Similar to SIGINT
SIGUSR1
“Signal user 1” – user definedSIGUSR2
“Signal user 2” – user definedSIGWINCH
“Signal window change” – triggered when the TTY (eg terminal emulator) is resizedThe following payload is passed to the function via stdin:
{
"Name": "",
"Interrupt": {
"Name": "",
"Signal": ""
}
}
This is the namespaced name – ie the name and operation.
This is the name you specified when defining the event.
This is the signal you specified when defining the event.
Valid interrupt operation values are specified below. All interrupts / signals are UPPERCASE strings.
This event doesn’t have any $EVENT_RETURN
parameters.
Interrupt ‘SIGINT’
event onSignalReceived example=SIGINT {
out "SIGINT received, not quitting"
}
The interrupts listed above are a subset of what is supported on each operating system. Please consult your operating systems docs for details on each signal and what their function is.
While Windows doesn’t officially support signals, the following POSIX signals are emulated:
var interrupts = map[string]syscall.Signal{
"SIGHUP": syscall.SIGHUP,
"SIGINT": syscall.SIGINT,
"SIGQUIT": syscall.SIGQUIT,
"SIGILL": syscall.SIGILL,
"SIGTRAP": syscall.SIGTRAP,
"SIGABRT": syscall.SIGABRT,
"SIGBUS": syscall.SIGBUS,
"SIGFPE": syscall.SIGFPE,
"SIGKILL": syscall.SIGKILL,
"SIGSEGV": syscall.SIGSEGV,
"SIGPIPE": syscall.SIGPIPE,
"SIGALRM": syscall.SIGALRM,
"SIGTERM": syscall.SIGTERM,
}
Plan 9 is not supported.
Stdout and stderr are both written to the terminal.
Interrupts are run in alphabetical order. So an event named “alfa” would run before an event named “zulu”. If you are writing multiple events and the order of execution matters, then you can prefix the names with a number, eg 10_jump
The onSignalReceived
event differs a little from other events when it comes to the namespacing of interrupts. Typically you cannot have multiple interrupts with the same name for an event. However with onPrompt
their names are further namespaced by the interrupt name. In layman’s terms this means example=SIGINT
wouldn’t overwrite example=SIGQUIT
.
The reason for this namespacing is because, unlike other events, you might legitimately want the same name for different interrupts.
event
: Event driven programming for shell scriptsonCommandCompletion
: Trigger an event upon a command’s completiononPrompt
: Events triggered by changes in state of the interactive shellsignal
: Sends a signal RPCThis document was generated from builtins/events/onSignalReceived/onSignalReceived_doc.yaml.
This site's content is rebuilt automatically from murex's source code after each merge to the master
branch. Downloadable murex binaries are also built with the website.
Last built on Thu Aug 15 14:38:34 UTC 2024 against commit 50ed9d650ed9d6df391240d3c2c02e623636e508dfcdad1.
Current version is 6.2.4000 which has been verified against tests cases.