4b3faf2c9918d2fafdba2bd5e09b0027efc924d0
[imager.git] / error.c
1 /*
2 =head1 NAME
3
4 error.c - error reporting code for Imager
5
6 =head1 SYNOPSIS
7
8   // user code:
9   int new_fatal; // non-zero if errors are fatal
10   int old_fatal = i_set_failure_fatal(new_fatal);
11   i_set_argv0("name of your program");
12   extern void error_cb(char const *);
13   i_error_cb old_ecb;
14   old_ecb = i_set_error_cb(error_cb);
15   i_failed_cb old_fcb;
16   extern void failed_cb(char **errors);
17   old_fcb = i_set_failed_cb(failed_cb);
18   if (!i_something(...)) {
19     char **errors = i_errors();
20   }
21
22   // imager code:
23   undef_int i_something(...) {
24     i_clear_error();
25     if (!some_lower_func(...)) {
26       return i_failed("could not something");
27     }
28     return 1;
29   }
30   undef_int some_lower_func(...) {
31     if (somethingelse_failed()) {
32       i_push_error("could not somethingelse");
33       return 0;
34     }
35     return 1;
36   }
37
38 =head1 DESCRIPTION
39
40 This module provides the C level error handling functionality for
41 Imager.
42
43 A few functions return or pass in an i_errmsg *, this is list of error
44 structures, terminated by an entry with a NULL msg value, each of
45 which contains a msg and an error code. Even though these aren't
46 passed as i_errmsg const * pointers, don't modify the strings
47 or the pointers.
48
49 The interface as currently defined isn't thread safe, unfortunately.
50
51 This code uses Imager's mymalloc() for memory allocation, so out of
52 memory errors are I<always> fatal.
53
54 =head1 INTERFACE
55
56 These functions form the interface that a user of Imager sees (from
57 C).  The Perl level won't use all of this.
58
59 =over
60
61 =cut
62 */
63
64 #include "imageri.h"
65 #include <stdio.h>
66 #include <stdlib.h>
67
68 #if 0
69 static i_error_cb error_cb;
70 static i_failed_cb failed_cb;
71 static int failures_fatal;
72 static char *argv0;
73 /*
74 =item i_set_argv0(char const *program)
75
76 Sets the name of the program to be displayed in fatal error messages.
77
78 The simplest way to use this is just:
79
80   i_set_argv0(argv[0]);
81
82 when your program starts.
83 */
84 void i_set_argv0(char const *name) {
85   char *dupl;
86   if (!name)
87     return;
88   /* if the user has an existing string of MAXINT length then
89      the system is broken anyway */
90   dupl = mymalloc(strlen(name)+1); /* check 17jul05 tonyc */
91   strcpy(dupl, name);
92   if (argv0)
93     myfree(argv0);
94   argv0 = dupl;
95 }
96
97 /*
98 =item i_set_failure_fatal(int failure_fatal)
99
100 If failure_fatal is non-zero then any future failures will result in
101 Imager exiting your program with a message describing the failure.
102
103 Returns the previous setting.
104
105 =cut
106 */
107 int i_set_failures_fatal(int fatal) {
108   int old = failures_fatal;
109   failures_fatal = fatal;
110
111   return old;
112 }
113
114 /*
115 =item i_set_error_cb(i_error_cb)
116
117 Sets a callback function that is called each time an error is pushed
118 onto the error stack.
119
120 Returns the previous callback.
121
122 i_set_failed_cb() is probably more useful.
123
124 =cut
125 */
126 i_error_cb i_set_error_cb(i_error_cb cb) {
127   i_error_cb old = error_cb;
128   error_cb = cb;
129
130   return old;
131 }
132
133 /*
134 =item i_set_failed_cb(i_failed_cb cb)
135
136 Sets a callback function that is called each time an Imager function
137 fails.
138
139 Returns the previous callback.
140
141 =cut
142 */
143 i_failed_cb i_set_failed_cb(i_failed_cb cb) {
144   i_failed_cb old = failed_cb;
145   failed_cb = cb;
146
147   return old;
148 }
149
150 #endif
151
152 /*
153 =item i_errors()
154
155 Returns a pointer to the first element of an array of error messages,
156 terminated by a NULL pointer.  The highest level message is first.
157
158 =cut
159 */
160 i_errmsg *im_errors(im_context_t ctx) {
161   return ctx->error_stack + ctx->error_sp;
162 }
163
164 i_errmsg *i_errors(void) {
165   return im_errors(im_get_context());
166 }
167
168 /*
169 =back
170
171 =head1 INTERNAL FUNCTIONS
172
173 These functions are called by Imager to report errors through the
174 above interface.
175
176 It may be desirable to have functions to mark the stack and reset to
177 the mark.
178
179 =over
180
181 =item i_clear_error()
182 =synopsis i_clear_error();
183 =category Error handling
184
185 Clears the error stack.
186
187 Called by any Imager function before doing any other processing.
188
189 =cut
190 */
191
192 void
193 im_clear_error(im_context_t ctx) {
194 #ifdef IMAGER_DEBUG_MALLOC
195   int i;
196
197   for (i = 0; i < IM_ERROR_COUNT; ++i) {
198     if (ctx->error_space[i]) {
199       myfree(ctx->error_stack[i].msg);
200       ctx->error_stack[i].msg = NULL;
201       ctx->error_space[i] = 0;
202     }
203   }
204 #endif
205   ctx->error_sp = IM_ERROR_COUNT-1;
206 }
207
208 /*
209 =item i_push_error(int code, char const *msg)
210 =synopsis i_push_error(0, "Yep, it's broken");
211 =synopsis i_push_error(errno, "Error writing");
212 =category Error handling
213
214 Called by an Imager function to push an error message onto the stack.
215
216 No message is pushed if the stack is full (since this means someone
217 forgot to call i_clear_error(), or that a function that doesn't do
218 error handling is calling function that does.).
219
220 =cut
221 */
222 void
223 im_push_error(im_context_t ctx, int code, char const *msg) {
224   size_t size = strlen(msg)+1;
225
226   if (ctx->error_sp <= 0)
227     /* bad, bad programmer */
228     return;
229
230   --ctx->error_sp;
231   if (ctx->error_alloc[ctx->error_sp] < size) {
232     if (ctx->error_stack[ctx->error_sp].msg)
233       myfree(ctx->error_stack[ctx->error_sp].msg);
234     /* memory allocated on the following line is only ever released when 
235        we need a bigger string */
236     /* size is size (len+1) of an existing string, overflow would mean
237        the system is broken anyway */
238     ctx->error_stack[ctx->error_sp].msg = mymalloc(size); /* checked 17jul05 tonyc */
239     ctx->error_alloc[ctx->error_sp] = size;
240   }
241   strcpy(ctx->error_stack[ctx->error_sp].msg, msg);
242   ctx->error_stack[ctx->error_sp].code = code;
243 }
244
245 #if 0
246
247 void
248 i_push_error(int code, char const *msg) {
249   im_push_error(im_get_context(), code, msg);
250 }
251
252 #endif
253
254 /*
255 =item i_push_errorvf(int C<code>, char const *C<fmt>, va_list C<ap>)
256
257 =category Error handling
258
259 Intended for use by higher level functions, takes a varargs pointer
260 and a format to produce the finally pushed error message.
261
262 Does not support perl specific format codes.
263
264 =cut
265 */
266 void 
267 im_push_errorvf(im_context_t ctx, int code, char const *fmt, va_list ap) {
268   char buf[1024];
269 #if defined(IMAGER_VSNPRINTF)
270   vsnprintf(buf, sizeof(buf), fmt, ap);
271 #elif defined(_MSC_VER)
272   _vsnprintf(buf, sizeof(buf), fmt, ap);
273 #else
274   /* is there a way to detect vsnprintf()? 
275      for this and other functions we need some mechanism to handle 
276      detection (like perl's Configure, or autoconf)
277    */
278   vsprintf(buf, fmt, ap);
279 #endif
280   im_push_error(ctx, code, buf);
281 }
282
283 void
284 (i_push_errorvf)(int code, char const *fmt, va_list ap) {
285   im_push_errorvf(im_get_context(), code, fmt, ap);
286 }
287
288 /*
289 =item i_push_errorf(int code, char const *fmt, ...)
290 =synopsis i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
291 =category Error handling
292
293 A version of i_push_error() that does printf() like formatting.
294
295 Does not support perl specific format codes.
296
297 =cut
298 */
299 void
300 i_push_errorf(int code, char const *fmt, ...) {
301   va_list ap;
302   va_start(ap, fmt);
303   i_push_errorvf(code, fmt, ap);
304   va_end(ap);
305 }
306
307 void
308 im_push_errorf(im_context_t ctx, int code, char const *fmt, ...) {
309   va_list ap;
310   va_start(ap, fmt);
311   im_push_errorvf(ctx, code, fmt, ap);
312   va_end(ap);
313 }
314
315 #ifdef IMAGER_I_FAILED
316 #error "This isn't used and is untested"
317
318 /*
319 =item i_failed(char const *msg)
320
321 Called by Imager code to indicate that a top-level has failed.
322
323 msg can be NULL, in which case no error is pushed.
324
325 Calls the current failed callback, if any.
326
327 Aborts the program with an error, if failures have been set to be fatal.
328
329 Returns zero if it does not abort.
330
331 =cut
332 */
333 int i_failed(int code, char const *msg) {
334   if (msg)
335     i_push_error(code, msg);
336   if (failed_cb)
337     failed_cb(error_stack + error_sp);
338   if (failures_fatal) {
339     int sp;
340     size_t total; /* total length of error messages */
341     char *full; /* full message for logging */
342     if (argv0)
343       fprintf(stderr, "%s: ", argv0);
344     fputs("error:\n", stderr);
345     sp = error_sp;
346     while (error_stack[sp].msg) {
347       fprintf(stderr, " %s\n", error_stack[sp].msg);
348       ++sp;
349     }
350     /* we want to log the error too, build an error message to hand to
351        i_fatal() */
352     total = 1; /* remember the NUL */
353     for (sp = error_sp; error_stack[sp].msg; ++sp) {
354       size_t new_total += strlen(error_stack[sp].msg) + 2;
355       if (new_total < total) {
356         /* overflow, somehow */
357         break;
358       }
359     }
360     full = mymalloc(total);
361     if (!full) {
362       /* just quit, at least it's on stderr */
363       exit(EXIT_FAILURE);
364     }
365     *full = 0;
366     for (sp = error_sp; error_stack[sp].msg; ++sp) {
367       strcat(full, error_stack[sp].msg);
368       strcat(full, ": ");
369     }
370     /* lose the extra ": " */
371     full[strlen(full)-2] = '\0';
372     i_fatal(EXIT_FAILURE, "%s", full);
373   }
374
375   return 0;
376 }
377
378 #endif
379
380 /*
381 =item im_assert_fail(file, line, message)
382
383 Called when an im_assert() assertion fails.
384
385 =cut
386 */
387
388 void
389 im_assert_fail(char const *file, int line, char const *message) {
390   fprintf(stderr, "Assertion failed line %d file %s: %s\n", 
391           line, file, message);
392   abort();
393 }
394
395 /*
396 =back
397
398 =head1 BUGS
399
400 This interface isn't thread safe.
401
402 =head1 AUTHOR
403
404 Tony Cook <tony@develop-help.com>
405
406 Stack concept by Arnar Mar Hrafnkelsson <addi@umich.edu>
407
408 =cut
409 */