API documentation (mostly)

[imager.git] / error.c

diff --git a/error.c b/error.c
index b1e87d38d77a10eff2d562b8990dbb114d057720..a3f172b03d4a2d5f0cf1f8225e9a8007d0a80cd6 100644 (file)
--- a/error.c
+++ b/error.c
@@ -61,7 +61,7 @@ C).  The Perl level won't use all of this.
 =cut
 */
 
-#include "image.h"
+#include "imager.h"
 #include <stdio.h>
 #include <stdlib.h>
 
@@ -95,7 +95,9 @@ void i_set_argv0(char const *name) {
   char *dupl;
   if (!name)
     return;
-  dupl = mymalloc(strlen(name)+1);
+  /* 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);
@@ -181,10 +183,15 @@ the mark.
 =over
 
 =item i_clear_error()
+=synopsis i_clear_error();
+=category Error handling
+
+Clears the error stack.
 
 Called by any imager function before doing any other processing.
 
-=cut */
+=cut
+*/
 void i_clear_error() {
 #ifdef IMAGER_DEBUG_MALLOC
   int i;
@@ -202,8 +209,11 @@ void i_clear_error() {
 
 /*
 =item i_push_error(int code, char const *msg)
+=synopsis i_push_error(0, "Yep, it's broken");
+=synopsis i_push_error(errno, "Error writing");
+=category Error handling
 
-Called by an imager function to push an error message onto the stack.
+Called by an Imager function to push an error message onto the stack.
 
 No message is pushed if the stack is full (since this means someone
 forgot to call i_clear_error(), or that a function that doesn't do
@@ -222,9 +232,11 @@ void i_push_error(int code, char const *msg) {
   if (error_space[error_sp] < size) {
     if (error_stack[error_sp].msg)
       myfree(error_stack[error_sp].msg);
-    /* memory allocated on the following line is only ever release when 
+    /* memory allocated on the following line is only ever released when 
        we need a bigger string */
-    error_stack[error_sp].msg = mymalloc(size);
+    /* size is size (len+1) of an existing string, overflow would mean
+       the system is broken anyway */
+    error_stack[error_sp].msg = mymalloc(size); /* checked 17jul05 tonyc */
     error_space[error_sp] = size;
   }
   strcpy(error_stack[error_sp].msg, msg);
@@ -237,9 +249,13 @@ void i_push_error(int code, char const *msg) {
 /*
 =item i_push_errorvf(int code, char const *fmt, va_list ap)
 
+=category Error handling
+
 Intended for use by higher level functions, takes a varargs pointer
 and a format to produce the finally pushed error message.
 
+Does not support perl specific format codes.
+
 =cut
 */
 void i_push_errorvf(int code, char const *fmt, va_list ap) {
@@ -258,9 +274,13 @@ void i_push_errorvf(int code, char const *fmt, va_list ap) {
 
 /*
 =item i_push_errorf(int code, char const *fmt, ...)
+=synopsis i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
+=category Error handling
 
 A version of i_push_error() that does printf() like formating.
 
+Does not support perl specific format codes.
+
 =cut
 */
 void i_push_errorf(int code, char const *fmt, ...) {
@@ -270,6 +290,9 @@ void i_push_errorf(int code, char const *fmt, ...) {
   va_end(ap);
 }
 
+#ifdef IMAGER_I_FAILED
+#error "This isn't used and is untested"
+
 /*
 =item i_failed(char const *msg)
 
@@ -303,7 +326,7 @@ int i_failed(int code, char const *msg) {
       ++sp;
     }
     /* we want to log the error too, build an error message to hand to
-       m_fatal() */
+       i_fatal() */
     total = 1; /* remember the NUL */
     for (sp = error_sp; error_stack[sp].msg; ++sp) {
       total += strlen(error_stack[sp].msg) + 2;
@@ -320,12 +343,14 @@ int i_failed(int code, char const *msg) {
     }
     /* lose the extra ": " */
     full[strlen(full)-2] = '\0';
-    m_fatal(EXIT_FAILURE, "%s", full);
+    i_fatal(EXIT_FAILURE, "%s", full);
   }
 
   return 0;
 }
 
+#endif
+
 /*
 =back