summaryrefslogtreecommitdiff
path: root/libguile/scmsigs.c
diff options
context:
space:
mode:
Diffstat (limited to 'libguile/scmsigs.c')
-rw-r--r--libguile/scmsigs.c52
1 files changed, 46 insertions, 6 deletions
diff --git a/libguile/scmsigs.c b/libguile/scmsigs.c
index c46835578..6a2c3ace6 100644
--- a/libguile/scmsigs.c
+++ b/libguile/scmsigs.c
@@ -181,7 +181,32 @@ sys_deliver_signals (void)
/* user interface for installation of signal handlers. */
GUILE_PROC(scm_sigaction, "sigaction", 1, 2, 0,
(SCM signum, SCM handler, SCM flags),
-"")
+"Install or report the signal hander for a specified signal.
+
+@var{signum} is the signal number, which can be specified using the value
+of variables such as @code{SIGINT}.
+
+If @var{action} is omitted, @code{sigaction} returns a pair: the
+CAR is the current
+signal hander, which will be either an integer with the value @code{SIG_DFL}
+(default action) or @code{SIG_IGN} (ignore), or the Scheme procedure which
+handles the signal, or @code{#f} if a non-Scheme procedure handles the
+signal. The CDR contains the current @code{sigaction} flags for the handler.
+
+If @var{action} is provided, it is installed as the new handler for
+@var{signum}. @var{action} can be a Scheme procedure taking one
+argument, or the value of @code{SIG_DFL} (default action) or
+@code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
+was installed before @code{sigaction} was first used. Flags can
+optionally be specified for the new handler (@code{SA_RESTART} will
+always be added if it's available and the system is using rstartable
+system calls.) 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.")
#define FUNC_NAME s_scm_sigaction
{
int csig;
@@ -312,7 +337,8 @@ GUILE_PROC(scm_sigaction, "sigaction", 1, 2, 0,
GUILE_PROC (scm_restore_signals, "restore-signals", 0, 0, 0,
(void),
-"")
+"Return all signal handlers to the values they had before any call to
+@code{sigaction} was made. The return value is unspecified.")
#define FUNC_NAME s_scm_restore_signals
{
int i;
@@ -344,7 +370,15 @@ GUILE_PROC (scm_restore_signals, "restore-signals", 0, 0, 0,
GUILE_PROC(scm_alarm, "alarm", 1, 0, 0,
(SCM i),
-"")
+"Set a timer to raise a @code{SIGALRM} signal after the specified
+number of seconds (an integer). It's advisable to install a signal
+handler for
+@code{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.")
#define FUNC_NAME s_scm_alarm
{
unsigned int j;
@@ -357,7 +391,9 @@ GUILE_PROC(scm_alarm, "alarm", 1, 0, 0,
#ifdef HAVE_PAUSE
GUILE_PROC(scm_pause, "pause", 0, 0, 0,
(),
-"")
+"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.")
#define FUNC_NAME s_scm_pause
{
pause ();
@@ -368,7 +404,9 @@ GUILE_PROC(scm_pause, "pause", 0, 0, 0,
GUILE_PROC(scm_sleep, "sleep", 1, 0, 0,
(SCM i),
-"")
+"Wait for the given number of seconds (an integer) or until a signal
+arrives. The return value is zero if the time elapses or the number
+of seconds remaining otherwise.")
#define FUNC_NAME s_scm_sleep
{
unsigned long j;
@@ -413,7 +451,9 @@ GUILE_PROC(scm_usleep, "usleep", 1, 0, 0,
GUILE_PROC(scm_raise, "raise", 1, 0, 0,
(SCM sig),
-"")
+"
+Sends a specified signal @var{sig} to the current process, where
+@var{sig} is as described for the kill procedure.")
#define FUNC_NAME s_scm_raise
{
SCM_VALIDATE_INT(1,sig);