6.13.13 How to Handle Errors

Guile is currently in a transition from its historical catch and throw error handling and signaling operators to the new structured exception facility; See Exceptions. However in the meantime, here is some documentation on errors and the older catch and throw interface.

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.

6.13.13.1 C Support

In the following C functions, SUBR and MESSAGE parameters can be NULL to give the effect of #f described above.

C Function: SCM scm_error (SCM key, char *subr, char *message, SCM args, SCM rest)

Throw an error, as per scm-error (see Error Reporting).

C Function: void scm_syserror (char *subr)

C Function: void scm_syserror_msg (char *subr, char *message, SCM args)

Throw an error with key system-error and supply errno in the rest argument. For scm_syserror the message is generated using strerror.

Care should be taken that any code in between the failing operation and the call to these routines doesn’t change errno.

C Function: void scm_num_overflow (char *subr)

C Function: void scm_out_of_range (char *subr, SCM bad_value)

C Function: void scm_wrong_num_args (SCM proc)

C Function: void scm_wrong_type_arg (char *subr, int argnum, SCM bad_value)

C Function: void scm_wrong_type_arg_msg (char *subr, int argnum, SCM bad_value, const char *expected)

C Function: void scm_misc_error (const char *subr, const char *message, SCM args)

Throw an error with the various keys described above.

In scm_wrong_num_args, proc should be a Scheme symbol which is the name of the procedure incorrectly invoked. The other routines take the name of the invoked procedure as a C string.

In scm_wrong_type_arg_msg, expected is a C string describing the type of argument that was expected.

In scm_misc_error, message is the error message string, possibly containing simple-format escapes (see Simple Output), and the corresponding arguments in the args list.

6.13.13.2 Signalling Type Errors

Every function visible at the Scheme level should aggressively check the types of its arguments, to avoid misinterpreting a value, and perhaps causing a segmentation fault. Guile provides some macros to make this easier.

Macro: void SCM_ASSERT (int test, SCM obj, unsigned int position, const char *subr)

Macro: void SCM_ASSERT_TYPE (int test, SCM obj, unsigned int position, const char *subr, const char *expected)

If test is zero, signal a “wrong type argument” error, attributed to the subroutine named subr, operating on the value obj, which is the position’th argument of subr.

In SCM_ASSERT_TYPE, expected is a C string describing the type of argument that was expected.

Macro: int SCM_ARG1

Macro: int SCM_ARG2

Macro: int SCM_ARG3

Macro: int SCM_ARG4

Macro: int SCM_ARG5

Macro: int SCM_ARG6

Macro: int SCM_ARG7

One of the above values can be used for position to indicate the number of the argument of subr which is being checked. Alternatively, a positive integer number can be used, which allows to check arguments after the seventh. However, for parameter numbers up to seven it is preferable to use SCM_ARGN instead of the corresponding raw number, since it will make the code easier to understand.

Macro: int SCM_ARGn

Passing a value of zero or SCM_ARGn for position allows to leave it unspecified which argument’s type is incorrect. Again, SCM_ARGn should be preferred over a raw zero constant.