(guile.info.gz) Handling Errors
Info Catalog
(guile.info.gz) Dynamic Wind
(guile.info.gz) Control Mechanisms
26.10 How to Handle Errors in C Code
====================================
Error handling is based on `catch' and `throw'. Errors are always
thrown with a KEY and four arguments:
* KEY: a symbol which indicates the type of error. The symbols used
by libguile are listed below.
* SUBR: the name of the procedure from which the error is thrown, or
`#f'.
* MESSAGE: a string (possibly language and system dependent)
describing the error. The tokens `~A' and `~S' can be embedded
within the message: they will be replaced with members of the ARGS
list when the message is printed. `~A' indicates an argument
printed using `display', while `~S' indicates an argument printed
using `write'. MESSAGE can also be `#f', to allow it to be
derived from the KEY by the error handler (may be useful if the
KEY is to be thrown from both C and Scheme).
* ARGS: a list of arguments to be used to expand `~A' and `~S'
tokens in MESSAGE. Can also be `#f' if no arguments are required.
* REST: a list of any additional objects required. e.g., when the
key is `'system-error', this contains the C errno value. Can also
be `#f' if no additional objects are required.
In addition to `catch' and `throw', the following Scheme facilities
are available:
-- Scheme Procedure: scm-error key subr message args rest
Throw an error, with arguments as described above.
-- Scheme Procedure: error msg arg ...
Throw an error using the key `'misc-error'. The error message is
created by displaying MSG and writing the ARGS.
-- Scheme Procedure: display-error stack port subr message args rest
-- C Function: scm_display_error (stack, port, subr, message, args,
rest)
Display an error message to the output port PORT. STACK is the
saved stack for the error, SUBR is the name of the procedure in
which the error occurred and MESSAGE is the actual error message,
which may contain formatting instructions. These will format the
arguments in the list ARGS accordingly. REST is currently ignored.
The following are the error keys defined by libguile and the
situations in which they are used:
* `error-signal': thrown after receiving an unhandled fatal signal
such as SIGSEGV, SIGBUS, SIGFPE etc. The REST argument in the
throw contains the coded signal number (at present this is not the
same as the usual Unix signal number).
* `system-error': thrown after the operating system indicates an
error condition. The REST argument in the throw contains the
errno value.
* `numerical-overflow': numerical overflow.
* `out-of-range': the arguments to a procedure do not fall within the
accepted domain.
* `wrong-type-arg': an argument to a procedure has the wrong type.
* `wrong-number-of-args': a procedure was called with the wrong
number of arguments.
* `memory-allocation-error': memory allocation error.
* `stack-overflow': stack overflow error.
* `regular-expression-syntax': errors generated by the regular
expression library.
* `misc-error': other errors.
26.10.1 C Support
-----------------
SCM scm_error (SCM key, char *subr, char *message, SCM args, SCM rest)
Throws an error, after converting the char * arguments to Scheme
strings. subr is the Scheme name of the procedure, NULL is converted
to #f. Likewise a NULL message is converted to #f.
The following procedures invoke scm_error with various error keys and
arguments. The first three call scm_error with the system-error key
and automatically supply errno in the "rest" argument: scm_syserror
generates messages using strerror, scm_sysmissing is used when
facilities are not available. Care should be taken that the errno
value is not reset (e.g. due to an interrupt).
* void scm_syserror (char *subr);
* void scm_syserror_msg (char *subr, char *message, SCM args);
* void scm_sysmissing (char *subr);
* void scm_num_overflow (char *subr);
* void scm_out_of_range (char *subr, SCM bad_value);
* void scm_wrong_num_args (SCM proc);
* void scm_wrong_type_arg (char *subr, int pos, SCM bad_value);
* void scm_memory_error (char *subr);
* static void scm_regex_error (char *subr, int code); (only used in
rgx.c).
Exception handlers can also be installed from C, using
scm_internal_catch, scm_lazy_catch, or scm_stack_catch from
libguile/throw.c. These have not yet been documented, however the
source contains some useful comments.
Info Catalog
(guile.info.gz) Dynamic Wind
(guile.info.gz) Control Mechanisms
automatically generated byinfo2html