doco C error handling

[Kevin Ryde <user42@zip.com.au>]

[-- Attachment #1: Type: text/plain, Size: 1834 bytes --]


	* scheme-control.texi (Handling Errors): Revise C support section to
	get index entries and clarify parameters.  Remove scm_regex_error, no
	longer exists and wasn't available to applications.

I hope I'm right that scm_regex_error is gone, it doesn't show up in a
grep.

Incidentally, is the regex-error error key described in the scheme
section of this node be regular-expression-syntax, as per the
`make-regexp' doco?


Revised text:

C Support
---------

In the following C functions, SUBR and MESSAGE parameters can be `NULL'
to give the `#f' described above.

 - Function: SCM scm_error (SCM key, char *subr, char *message, SCM
          args, SCM rest)
     Throw an error, as per `scm-error' above.

 - Function: void scm_syserror (char *subr)
 - Function: void scm_syserror_msg (char *subr, 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'.

     Of course care should be taken that any code in between the failing
     operation and the call to these routines doesn't change `errno'.

 - Function: void scm_num_overflow (char *subr)
 - Function: void scm_out_of_range (char *subr, SCM bad_value)
 - Function: void scm_wrong_num_args (SCM proc)
 - Function: void scm_wrong_type_arg (char *subr, int pos, SCM
          bad_value)
 - Function: void scm_memory_error (char *subr)
     Throw an error with the various keys described above.

     For `scm_wrong_num_args', PROC should be a Scheme symbol which is
     the name of the procedure incorrectly invoked.

   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, but the source
contains some useful comments.



[-- Attachment #2: scheme-control.texi.c-errors.diff --]
[-- Type: text/plain, Size: 2918 bytes --]

--- scheme-control.texi.~1.6.~	2003-05-04 11:02:44.000000000 +1000
+++ scheme-control.texi	2003-05-04 11:24:15.000000000 +1000
@@ -934,41 +934,38 @@
 
 @subsection C Support
 
-SCM scm_error (SCM key, char *subr, char *message, SCM args, SCM rest)
+In the following C functions, @var{SUBR} and @var{MESSAGE} parameters
+can be @code{NULL} to give the @code{#f} described above.
 
-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.  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_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
+@deftypefun SCM scm_error (SCM key, char *subr, char *message, SCM args, SCM rest)
+Throw an error, as per @code{scm-error} above.
+@end deftypefun
+
+@deftypefun void scm_syserror (char *subr)
+@deftypefunx void scm_syserror_msg (char *subr, char *message, SCM args)
+Throw an error with key @code{system-error} and supply @code{errno} in
+the @var{rest} argument.  For @code{scm_syserror} the message is
+generated using @code{strerror}.
+
+Of course care should be taken that any code in between the failing
+operation and the call to these routines doesn't change @code{errno}.
+@end deftypefun
+
+@deftypefun void scm_num_overflow (char *subr)
+@deftypefunx void scm_out_of_range (char *subr, SCM bad_value)
+@deftypefunx void scm_wrong_num_args (SCM proc)
+@deftypefunx void scm_wrong_type_arg (char *subr, int pos, SCM bad_value)
+@deftypefunx void scm_memory_error (char *subr)
+Throw an error with the various keys described above.
+
+For @code{scm_wrong_num_args}, @var{proc} should be a Scheme symbol
+which is the name of the procedure incorrectly invoked.
+@end deftypefun
 
 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.
+@code{scm_internal_catch}, @code{scm_lazy_catch}, or
+@code{scm_stack_catch} from @file{libguile/throw.c}.  These have not
+yet been documented, but the source contains some useful comments.
 
 
 @c Local Variables:

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel