more Changes updates

[imager.git] / error.c

diff --git a/error.c b/error.c
index 4b3faf2c9918d2fafdba2bd5e09b0027efc924d0..03a271ca8c61a5ec1e30bf366a8c7cfcc23cf7c0 100644 (file)
--- a/error.c
+++ b/error.c
@@ -65,106 +65,22 @@ C).  The Perl level won't use all of this.
 #include <stdio.h>
 #include <stdlib.h>
 
-#if 0
-static i_error_cb error_cb;
-static i_failed_cb failed_cb;
-static int failures_fatal;
-static char *argv0;
 /*
-=item i_set_argv0(char const *program)
-
-Sets the name of the program to be displayed in fatal error messages.
-
-The simplest way to use this is just:
-
-  i_set_argv0(argv[0]);
-
-when your program starts.
-*/
-void i_set_argv0(char const *name) {
-  char *dupl;
-  if (!name)
-    return;
-  /* if the user has an existing string of MAXINT length then
-     the system is broken anyway */
-  dupl = mymalloc(strlen(name)+1); /* check 17jul05 tonyc */
-  strcpy(dupl, name);
-  if (argv0)
-    myfree(argv0);
-  argv0 = dupl;
-}
-
-/*
-=item i_set_failure_fatal(int failure_fatal)
-
-If failure_fatal is non-zero then any future failures will result in
-Imager exiting your program with a message describing the failure.
-
-Returns the previous setting.
-
-=cut
-*/
-int i_set_failures_fatal(int fatal) {
-  int old = failures_fatal;
-  failures_fatal = fatal;
-
-  return old;
-}
-
-/*
-=item i_set_error_cb(i_error_cb)
-
-Sets a callback function that is called each time an error is pushed
-onto the error stack.
-
-Returns the previous callback.
-
-i_set_failed_cb() is probably more useful.
-
-=cut
-*/
-i_error_cb i_set_error_cb(i_error_cb cb) {
-  i_error_cb old = error_cb;
-  error_cb = cb;
-
-  return old;
-}
-
-/*
-=item i_set_failed_cb(i_failed_cb cb)
-
-Sets a callback function that is called each time an Imager function
-fails.
-
-Returns the previous callback.
-
-=cut
-*/
-i_failed_cb i_set_failed_cb(i_failed_cb cb) {
-  i_failed_cb old = failed_cb;
-  failed_cb = cb;
-
-  return old;
-}
-
-#endif
-
-/*
-=item i_errors()
+=item im_errors(ctx)
+=synopsis i_errmsg *errors = im_errors(aIMCTX);
+=synopsis i_errmsg *errors = i_errors();
 
 Returns a pointer to the first element of an array of error messages,
 terminated by a NULL pointer.  The highest level message is first.
 
+Also callable as C<i_errors()>.
+
 =cut
 */
 i_errmsg *im_errors(im_context_t ctx) {
   return ctx->error_stack + ctx->error_sp;
 }
 
-i_errmsg *i_errors(void) {
-  return im_errors(im_get_context());
-}
-
 /*
 =back
 
@@ -178,7 +94,9 @@ the mark.
 
 =over
 
-=item i_clear_error()
+=item im_clear_error(ctx)
+X<im_clear_error API>X<i_clear_error API>
+=synopsis im_clear_error(aIMCTX);
 =synopsis i_clear_error();
 =category Error handling
 
@@ -186,6 +104,8 @@ Clears the error stack.
 
 Called by any Imager function before doing any other processing.
 
+Also callable as C<i_clear_error()>.
+
 =cut
 */
 
@@ -206,9 +126,11 @@ im_clear_error(im_context_t ctx) {
 }
 
 /*
-=item i_push_error(int code, char const *msg)
+=item im_push_error(ctx, code, message)
+X<im_push_error API>X<i_push_error API>
 =synopsis i_push_error(0, "Yep, it's broken");
 =synopsis i_push_error(errno, "Error writing");
+=synopsis im_push_error(aIMCTX, 0, "Something is wrong");
 =category Error handling
 
 Called by an Imager function to push an error message onto the stack.
@@ -242,18 +164,12 @@ im_push_error(im_context_t ctx, int code, char const *msg) {
   ctx->error_stack[ctx->error_sp].code = code;
 }
 
-#if 0
-
-void
-i_push_error(int code, char const *msg) {
-  im_push_error(im_get_context(), code, msg);
-}
-
-#endif
-
 /*
-=item i_push_errorvf(int C<code>, char const *C<fmt>, va_list C<ap>)
-
+=item im_push_errorvf(ctx, code, format, args)
+X<im_push_error_vf API>X<i_push_errorvf API>
+=synopsis va_args args;
+=synopsis va_start(args, lastarg);
+=synopsis im_push_errorvf(ctx, code, format, args);
 =category Error handling
 
 Intended for use by higher level functions, takes a varargs pointer
@@ -261,6 +177,8 @@ and a format to produce the finally pushed error message.
 
 Does not support perl specific format codes.
 
+Also callable as C<i_push_errorvf(code, format, args)>
+
 =cut
 */
 void 
@@ -280,11 +198,6 @@ im_push_errorvf(im_context_t ctx, int code, char const *fmt, va_list ap) {
   im_push_error(ctx, code, buf);
 }
 
-void
-(i_push_errorvf)(int code, char const *fmt, va_list ap) {
-  im_push_errorvf(im_get_context(), code, fmt, ap);
-}
-
 /*
 =item i_push_errorf(int code, char const *fmt, ...)
 =synopsis i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
@@ -304,6 +217,17 @@ i_push_errorf(int code, char const *fmt, ...) {
   va_end(ap);
 }
 
+/*
+=item im_push_errorf(ctx, code, char const *fmt, ...)
+=synopsis im_push_errorf(aIMCTX, errno, "Cannot open file %s: %d", filename, errno);
+=category Error handling
+
+A version of im_push_error() that does printf() like formatting.
+
+Does not support perl specific format codes.
+
+=cut
+*/
 void
 im_push_errorf(im_context_t ctx, int code, char const *fmt, ...) {
   va_list ap;
@@ -377,11 +301,15 @@ int i_failed(int code, char const *msg) {
 
 #endif
 
+#ifdef IM_ASSERT
+
 /*
 =item im_assert_fail(file, line, message)
 
 Called when an im_assert() assertion fails.
 
+Only available when Imager is built with assertions.
+
 =cut
 */
 
@@ -392,6 +320,8 @@ im_assert_fail(char const *file, int line, char const *message) {
   abort();
 }
 
+#endif
+
 /*
 =back