6.11.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:

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:

6.11.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, const char *subr, const char *message, SCM args, SCM rest)

Throw an error, as per scm-error (see Procedures for Signaling Errors).

C Function: void scm_syserror (const char *subr)
C Function: void scm_syserror_msg (const char *subr, const 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 (const char *subr)
C Function: void scm_out_of_range (const char *subr, SCM bad_value)
C Function: void scm_wrong_num_args (SCM proc)
C Function: void scm_wrong_type_arg (const char *subr, int argnum, SCM bad_value)
C Function: void scm_wrong_type_arg_msg (const 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 Textual Output), and the corresponding arguments in the args list.

6.11.13.2 Signaling 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.