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