7.2.8 Signals

The following procedures raise, handle and wait for signals.

Scheme code signal handlers are run via a system async (see section System asyncs), so they’re called in the handler’s thread at the next safe opportunity. Generally this is after any currently executing primitive procedure finishes (which could be a long time for primitives that wait for an external event).

Scheme Procedure: kill pid sig

C Function: scm_kill (pid, sig)

Sends a signal to the specified process or group of processes.

pid specifies the processes to which the signal is sent:

pid greater than 0

The process whose identifier is pid.

pid equal to 0

All processes in the current process group.

pid less than -1

The process group whose identifier is -pid

pid equal to -1

If the process is privileged, all processes except for some special system processes. Otherwise, all processes with the current effective user ID.

sig should be specified using a variable corresponding to the Unix symbolic name, e.g.,

Variable: SIGHUP

Hang-up signal.

Variable: SIGINT

Interrupt signal.

A full list of signals on the GNU system may be found in Standard Signals in The GNU C Library Reference Manual.

Scheme Procedure: raise sig

C Function: scm_raise (sig)

Sends a specified signal sig to the current process, where sig is as described for the kill procedure.

Scheme Procedure: sigaction signum [handler [flags [thread]]]

C Function: scm_sigaction (signum, handler, flags)

C Function: scm_sigaction_for_thread (signum, handler, flags, thread)

Install or report the signal handler for a specified signal.

signum is the signal number, which can be specified using the value of variables such as SIGINT.

If handler is omitted, sigaction returns a pair: the CAR is the current signal hander, which will be either an integer with the value SIG_DFL (default action) or SIG_IGN (ignore), or the Scheme procedure which handles the signal, or #f if a non-Scheme procedure handles the signal. The CDR contains the current sigaction flags for the handler.

If handler is provided, it is installed as the new handler for signum. handler can be a Scheme procedure taking one argument, or the value of SIG_DFL (default action) or SIG_IGN (ignore), or #f to restore whatever signal handler was installed before sigaction was first used. When a scheme procedure has been specified, that procedure will run in the given thread. When no thread has been given, the thread that made this call to sigaction is used.

flags is a logior (see section Bitwise Operations) of the following (where provided by the system), or 0 for none.

Variable: SA_NOCLDSTOP

By default, SIGCHLD is signalled when a child process stops (ie. receives SIGSTOP), and when a child process terminates. With the SA_NOCLDSTOP flag, SIGCHLD is only signalled for termination, not stopping.

SA_NOCLDSTOP has no effect on signals other than SIGCHLD.

Variable: SA_RESTART

If a signal occurs while in a system call, deliver the signal then restart the system call (as opposed to returning an EINTR error from that call).

The return value is a pair with information about the old handler as described above.

This interface does not provide access to the “signal blocking” facility. Maybe this is not needed, since the thread support may provide solutions to the problem of consistent access to data structures.

Scheme Procedure: restore-signals

C Function: scm_restore_signals ()

Return all signal handlers to the values they had before any call to sigaction was made. The return value is unspecified.

Scheme Procedure: alarm i

C Function: scm_alarm (i)

Set a timer to raise a SIGALRM signal after the specified number of seconds (an integer). It’s advisable to install a signal handler for SIGALRM beforehand, since the default action is to terminate the process.

The return value indicates the time remaining for the previous alarm, if any. The new value replaces the previous alarm. If there was no previous alarm, the return value is zero.

Scheme Procedure: pause

C Function: scm_pause ()

Pause the current process (thread?) until a signal arrives whose action is to either terminate the current process or invoke a handler procedure. The return value is unspecified.

Scheme Procedure: sleep secs

Scheme Procedure: usleep usecs

C Function: scm_sleep (secs)

C Function: scm_usleep (usecs)

Wait the given period secs seconds or usecs microseconds (both integers). If a signal arrives the wait stops and the return value is the time remaining, in seconds or microseconds respectively. If the period elapses with no signal the return is zero.

On most systems the process scheduler is not microsecond accurate and the actual period slept by usleep might be rounded to a system clock tick boundary, which might be 10 milliseconds for instance.

See scm_std_sleep and scm_std_usleep for equivalents at the C level (see section Blocking in Guile Mode).

Scheme Procedure: getitimer which_timer

Scheme Procedure: setitimer which_timer interval_seconds interval_microseconds periodic_seconds periodic_microseconds

C Function: scm_getitimer (which_timer)

C Function: scm_setitimer (which_timer, interval_seconds, interval_microseconds, periodic_seconds, periodic_microseconds)

Get or set the periods programmed in certain system timers. These timers have a current interval value which counts down and on reaching zero raises a signal. An optional periodic value can be set to restart from there each time, for periodic operation. which_timer is one of the following values

Variable: ITIMER_REAL

A real-time timer, counting down elapsed real time. At zero it raises SIGALRM. This is like alarm above, but with a higher resolution period.

Variable: ITIMER_VIRTUAL

A virtual-time timer, counting down while the current process is actually using CPU. At zero it raises SIGVTALRM.

Variable: ITIMER_PROF

A profiling timer, counting down while the process is running (like ITIMER_VIRTUAL) and also while system calls are running on the process’s behalf. At zero it raises a SIGPROF.

This timer is intended for profiling where a program is spending its time (by looking where it is when the timer goes off).

getitimer returns the current timer value and its programmed restart value, as a list containing two pairs. Each pair is a time in seconds and microseconds: ((interval_secs . interval_usecs) (periodic_secs . periodic_usecs)).

setitimer sets the timer values similarly, in seconds and microseconds (which must be integers). The periodic value can be zero to have the timer run down just once. The return value is the timer’s previous setting, in the same form as getitimer returns.

(setitimer ITIMER_REAL
           5 500000     ;; first SIGALRM in 5.5 seconds time
           2 0)         ;; then repeat every 2 seconds

Although the timers are programmed in microseconds, the actual accuracy might not be that high.

This document was generated on April 20, 2013 using texi2html 5.0.