/[guile]/guile/guile-core/doc/ref/scheme-control.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/scheme-control.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.1.2.3 by ossau, Fri Mar 15 09:23:18 2002 UTC revision 1.1.2.4 by ossau, Sat Mar 16 13:35:23 2002 UTC
# Line 12  Line 12 
12  * Exceptions::                  Throwing and catching exceptions.  * Exceptions::                  Throwing and catching exceptions.
13  * Error Reporting::             Procedures for signaling errors.  * Error Reporting::             Procedures for signaling errors.
14  * Dynamic Wind::                Guarding against non-local entrance/exit.  * Dynamic Wind::                Guarding against non-local entrance/exit.
15    * Handling Errors::             How to handle errors in C code.
16  @end menu  @end menu
17    
18    
# Line 825  a-cont Line 826  a-cont
826  @result{} special-binding  @result{} special-binding
827  @end lisp  @end lisp
828  @end deffn  @end deffn
829    
830    
831    @node Handling Errors
832    @section How to Handle Errors in C Code
833    
834    Error handling is based on @code{catch} and @code{throw}.  Errors are
835    always thrown with a @var{key} and four arguments:
836    
837    @itemize @bullet
838    @item
839    @var{key}: a symbol which indicates the type of error.  The symbols used
840    by libguile are listed below.
841    
842    @item
843    @var{subr}: the name of the procedure from which the error is thrown, or
844    @code{#f}.
845    
846    @item
847    @var{message}: a string (possibly language and system dependent)
848    describing the error.  The tokens @code{~A} and @code{~S} can be
849    embedded within the message: they will be replaced with members of the
850    @var{args} list when the message is printed.  @code{~A} indicates an
851    argument printed using @code{display}, while @code{~S} indicates an
852    argument printed using @code{write}.  @var{message} can also be
853    @code{#f}, to allow it to be derived from the @var{key} by the error
854    handler (may be useful if the @var{key} is to be thrown from both C and
855    Scheme).
856    
857    @item
858    @var{args}: a list of arguments to be used to expand @code{~A} and
859    @code{~S} tokens in @var{message}.  Can also be @code{#f} if no
860    arguments are required.
861    
862    @item
863    @var{rest}: a list of any additional objects required. e.g., when the
864    key is @code{'system-error}, this contains the C errno value.  Can also
865    be @code{#f} if no additional objects are required.
866    @end itemize
867    
868    In addition to @code{catch} and @code{throw}, the following Scheme
869    facilities are available:
870    
871    @deffn {Scheme Procedure} scm-error key subr message args rest
872    Throw an error, with arguments
873    as described above.
874    @end deffn
875    
876    @deffn {Scheme Procedure} error msg arg @dots{}
877    Throw an error using the key @code{'misc-error}.  The error
878    message is created by displaying @var{msg} and writing the @var{args}.
879    @end deffn
880    
881    The following are the error keys defined by libguile and the situations
882    in which they are used:
883    
884    @itemize @bullet
885    @item
886    @code{error-signal}: thrown after receiving an unhandled fatal signal
887    such as SIGSEGV, SIGBUS, SIGFPE etc.  The @var{rest} argument in the throw
888    contains the coded signal number (at present this is not the same as the
889    usual Unix signal number).
890    
891    @item
892    @code{system-error}: thrown after the operating system indicates an
893    error condition.  The @var{rest} argument in the throw contains the
894    errno value.
895    
896    @item
897    @code{numerical-overflow}: numerical overflow.
898    
899    @item
900    @code{out-of-range}: the arguments to a procedure do not fall within the
901    accepted domain.
902    
903    @item
904    @code{wrong-type-arg}: an argument to a procedure has the wrong type.
905    
906    @item
907    @code{wrong-number-of-args}: a procedure was called with the wrong number
908    of arguments.
909    
910    @item
911    @code{memory-allocation-error}: memory allocation error.
912    
913    @item
914    @code{stack-overflow}: stack overflow error.
915    
916    @item
917    @code{regex-error}: errors generated by the regular expression library.
918    
919    @item
920    @code{misc-error}: other errors.
921    @end itemize
922    
923    
924    @subsection C Support
925    
926    SCM scm_error (SCM key, char *subr, char *message, SCM args, SCM rest)
927    
928    Throws an error, after converting the char * arguments to Scheme strings.
929    subr is the Scheme name of the procedure, NULL is converted to #f.
930    Likewise a NULL message is converted to #f.
931    
932    The following procedures invoke scm_error with various error keys and
933    arguments.  The first three call scm_error with the system-error key
934    and automatically supply errno in the "rest" argument:  scm_syserror
935    generates messages using strerror,  scm_sysmissing is used when
936    facilities are not available.  Care should be taken that the errno
937    value is not reset (e.g. due to an interrupt).
938    
939    @itemize @bullet
940    @item
941    void scm_syserror (char *subr);
942    @item
943    void scm_syserror_msg (char *subr, char *message, SCM args);
944    @item
945    void scm_sysmissing (char *subr);
946    @item
947    void scm_num_overflow (char *subr);
948    @item
949    void scm_out_of_range (char *subr, SCM bad_value);
950    @item
951    void scm_wrong_num_args (SCM proc);
952    @item
953    void scm_wrong_type_arg (char *subr, int pos, SCM bad_value);
954    @item
955    void scm_memory_error (char *subr);
956    @item
957    static void scm_regex_error (char *subr, int code); (only used in rgx.c).
958    @end itemize
959    
960    Exception handlers can also be installed from C, using
961    scm_internal_catch, scm_lazy_catch, or scm_stack_catch from
962    libguile/throw.c.  These have not yet been documented, however the
963    source contains some useful comments.
964    
965    
966  @c Local Variables:  @c Local Variables:
967  @c TeX-master: "guile.texi"  @c TeX-master: "guile.texi"
968  @c End:  @c End:

Legend:
Removed from v.1.1.2.3  
changed lines
  Added in v.1.1.2.4

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26