6.13.11 How to Handle Errors

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: display-error frame port subr message args rest

C Function: scm_display_error (frame, port, subr, message, args, rest)

Display an error message to the output port port. frame is the frame in which the error occurred, 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.

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