diff options
author | Neil Jerram <neil@ossau.uklinux.net> | 2001-11-11 15:01:52 +0000 |
---|---|---|
committer | Neil Jerram <neil@ossau.uklinux.net> | 2001-11-11 15:01:52 +0000 |
commit | 9401323e63278a7053c54565e8d688f6cbe34f54 (patch) | |
tree | 01e0840bac67d78e974b03200f9cf16f894fea37 /doc/ref/scheme-control.texi | |
parent | a0a9b9ad4263e129e46e31a8c0c2e7775b037ee9 (diff) | |
download | guile-9401323e63278a7053c54565e8d688f6cbe34f54.tar.gz |
* Documentation work.
Diffstat (limited to 'doc/ref/scheme-control.texi')
-rw-r--r-- | doc/ref/scheme-control.texi | 138 |
1 files changed, 138 insertions, 0 deletions
diff --git a/doc/ref/scheme-control.texi b/doc/ref/scheme-control.texi index dd5f9be53..d7b95151b 100644 --- a/doc/ref/scheme-control.texi +++ b/doc/ref/scheme-control.texi @@ -12,6 +12,7 @@ * Exceptions:: Throwing and catching exceptions. * Error Reporting:: Procedures for signaling errors. * Dynamic Wind:: Guarding against non-local entrance/exit. +* Handling Errors:: How to handle errors in C code. @end menu @@ -818,6 +819,143 @@ a-cont @result{} special-binding @end lisp @end deffn + + +@node Handling Errors +@section How to Handle Errors in C Code + +Error handling is based on @code{catch} and @code{throw}. Errors are +always thrown with a @var{key} and four arguments: + +@itemize @bullet +@item +@var{key}: a symbol which indicates the type of error. The symbols used +by libguile are listed below. + +@item +@var{subr}: the name of the procedure from which the error is thrown, or +@code{#f}. + +@item +@var{message}: a string (possibly language and system dependent) +describing the error. The tokens @code{~A} and @code{~S} can be +embedded within the message: they will be replaced with members of the +@var{args} list when the message is printed. @code{~A} indicates an +argument printed using @code{display}, while @code{~S} indicates an +argument printed using @code{write}. @var{message} can also be +@code{#f}, to allow it to be derived from the @var{key} by the error +handler (may be useful if the @var{key} is to be thrown from both C and +Scheme). + +@item +@var{args}: a list of arguments to be used to expand @code{~A} and +@code{~S} tokens in @var{message}. Can also be @code{#f} if no +arguments are required. + +@item +@var{rest}: a list of any additional objects required. e.g., when the +key is @code{'system-error}, this contains the C errno value. Can also +be @code{#f} if no additional objects are required. +@end itemize + +In addition to @code{catch} and @code{throw}, the following Scheme +facilities are available: + +@deffn primitive scm-error key subr message args rest +Throw an error, with arguments +as described above. +@end deffn + +@deffn procedure error msg arg @dots{} +Throw an error using the key @code{'misc-error}. The error +message is created by displaying @var{msg} and writing the @var{args}. +@end deffn + +The following are the error keys defined by libguile and the situations +in which they are used: + +@itemize @bullet +@item +@code{error-signal}: thrown after receiving an unhandled fatal signal +such as SIGSEV, SIGBUS, SIGFPE etc. The @var{rest} argument in the throw +contains the coded signal number (at present this is not the same as the +usual Unix signal number). + +@item +@code{system-error}: thrown after the operating system indicates an +error condition. The @var{rest} argument in the throw contains the +errno value. + +@item +@code{numerical-overflow}: numerical overflow. + +@item +@code{out-of-range}: the arguments to a procedure do not fall within the +accepted domain. + +@item +@code{wrong-type-arg}: an argument to a procedure has the wrong thpe. + +@item +@code{wrong-number-of-args}: a procedure was called with the wrong number +of arguments. + +@item +@code{memory-allocation-error}: memory allocation error. + +@item +@code{stack-overflow}: stack overflow error. + +@item +@code{regex-error}: errors generated by the regular expression library. + +@item +@code{misc-error}: other errors. +@end itemize + + +@subsection 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). + +@itemize @bullet +@item +void scm_syserror (char *subr); +@item +void scm_syserror_msg (char *subr, char *message, SCM args); +@item +void scm_sysmissing (char *subr); +@item +void scm_num_overflow (char *subr); +@item +void scm_out_of_range (char *subr, SCM bad_value); +@item +void scm_wrong_num_args (SCM proc); +@item +void scm_wrong_type_arg (char *subr, int pos, SCM bad_value); +@item +void scm_memory_error (char *subr); +@item +static void scm_regex_error (char *subr, int code); (only used in rgx.c). +@end itemize + +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. + + @c Local Variables: @c TeX-master: "guile.texi" @c End: |