unix-signals
1 Waiting for a signal
capture-signal!
ignore-signal!
release-signal!
next-signal-evt
read-signal
2 Sending a signal
send-signal!
3 Mapping between signal names and signal numbers
lookup-signal-number
lookup-signal-name
8.1

unix-signals

Tony Garnock-Jones <tonyg@leastfixedpoint.com>

 (require unix-signals) package: unix-signals

If you find that this library lacks some feature you need, or you have a suggestion for improving it, please don’t hesitate to get in touch with me!

This library provides a means of sending and receiving Unix signals to Racket programs.

Be warned that attempting to receive certain signals used by the Racket runtime is unsafe, as the code here will conflict with the code in Racket itself.

1 Waiting for a signal

To receive Unix signals using this library, call capture-signal! once for each signal of interest, and then use next-signal-evt or read-signal. Use ignore-signal! and release-signal! to ignore a signal (SIG_IGN) or to install the default signal-handler (SIG_DFL), respectively.

(require unix-signals)
(capture-signal! 'SIGUSR1)
(capture-signal! 'SIGUSR2)
(printf "Try 'kill -USR1 ~a' and 'kill -USR2 ~a'\n" (getpid) (getpid))
(let loop ()
  (define signum (read-signal))
  (printf "Received signal ~v (name ~v)\n" signum (lookup-signal-name signum))
  (loop))

Calls to capture-signal! and friends have global effect within the Racket process. Likewise, use of next-signal-evt and read-signal have global side-effects on the state of the Racket process.

procedure

(capture-signal! sig)  boolean?

  sig : (or/c fixnum? symbol?)
Installs a signal handler for the given signal. When the given signal is received by the process, its signal number will be returned by uses of next-signal-evt and/or read-signal.

Note that this function is unsafe: it can corrupt or crash the Racket runtime system.

procedure

(ignore-signal! sig)  boolean?

  sig : (or/c fixnum? symbol?)
Causes the given signal to be ignored (SIG_IGN) by the process.

Note that this function is unsafe: it can corrupt or crash the Racket runtime system.

procedure

(release-signal! sig)  boolean?

  sig : (or/c fixnum? symbol?)
Installs the default handler (SIG_DFL) for the given signal.

Note that this function is unsafe: it can corrupt or crash the Racket runtime system.

Synchronizable event which becomes ready when a signal previously registered with capture-signal! is received, at which point it returns the number of the received signal as its synchronization result by yielding the result of a call to read-signal.

procedure

(read-signal)  fixnum?

Blocks until a signal previously registered with capture-signal! is received. Returns the number of the received signal. Signals are buffered internally using the self-pipe trick, and are therefore delivered in order of receipt.

2 Sending a signal

procedure

(send-signal! pid sig)  boolean?

  pid : fixnum?
  sig : (or/c fixnum? symbol?)
Calls kill(2) to deliver the given signal to the given process ID. All special cases for pid from the kill(2) manpage apply.

Note that this function is unsafe: it can corrupt or crash the Racket runtime system.

For convenience, this library also re-exports getpid from racket/os.

3 Mapping between signal names and signal numbers

procedure

(lookup-signal-number sym)  (opt/c fixnum?)

  sym : symbol?
Returns a fixnum if the symbol name is defined, or #f if not.

procedure

(lookup-signal-name num)  (opt/c symbol?)

  num : fixnum?
Returns a symbol naming the given signal number, if one is defined, or #f if not. Note that in cases where multiple C identifiers map to a given signal number, an arbitrary choice among the possibilities is returned.