unix-signals
1 Introduction
2 What to require
2.1 Waiting for a signal
capture-signal!
ignore-signal!
release-signal!
next-signal-evt
read-signal
2.2 Sending a signal
send-signal!
2.3 Mapping between signal names and signal numbers
lookup-signal-number
lookup-signal-name
6.12

unix-signals

Tony Garnock-Jones <[email protected]>

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!

1 Introduction

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 dangerous, as the code here will conflict with the code in Racket itself.

2 What to require

All the functionality below can be accessed with a single require:

 (require unix-signals) package: unix-signals

This library represents signal names as symbols all in upper-case; for example, 'SIGUSR1 and 'SIGKILL.

2.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.

procedure

(ignore-signal! sig)  boolean?

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

procedure

(release-signal! sig)  boolean?

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

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.2 Sending a signal

This library provides getpid from racket/os for convenience.

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.

2.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.