(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