[imager.git] / error.c

/*
=head1 NAME

error.c - error reporting code for Imager

=head1 SYNOPSIS

  // user code:
  int new_fatal; // non-zero if errors are fatal
  int old_fatal = i_set_failure_fatal(new_fatal);
  i_set_argv0("name of your program");
  extern void error_cb(char const *);
  i_error_cb old_ecb;
  old_ecb = i_set_error_cb(error_cb);
  i_failed_cb old_fcb;
  extern void failed_cb(char **errors);
  old_fcb = i_set_failed_cb(failed_cb);
  if (!i_something(...)) {
    char **errors = i_errors();
  }

  // imager code:
  undef_int i_something(...) {
    i_clear_error();
    if (!some_lower_func(...)) {
      return i_failed("could not something");
    }
    return 1;
  }
  undef_int some_lower_func(...) {
    if (somethingelse_failed()) {
      i_push_error("could not somethingelse");
      return 0;
    }
    return 1;
  }

=head1 DESCRIPTION

This module provides the C level error handling functionality for
Imager.

A few functions return or pass in an i_errmsg *, this is list of error
structures, terminated by an entry with a NULL msg value, each of
which contains a msg and an error code. Even though these aren't
passed as i_errmsg const * pointers, don't modify the strings
or the pointers.

The interface as currently defined isn't thread safe, unfortunately.

This code uses Imager's mymalloc() for memory allocation, so out of
memory errors are I<always> fatal.

=head1 INTERFACE

These functions form the interface that a user of Imager sees (from
C).  The Perl level won't use all of this.

=over

=cut
*/

#include "imager.h"
#include <stdio.h>
#include <stdlib.h>

/* we never actually use the last item - it's the NULL terminator */
#define ERRSTK 20
static i_errmsg error_stack[ERRSTK];
static int error_sp = ERRSTK - 1;
/* we track the amount of space used each string, so we don't reallocate 
   space unless we need to.
   This also means that a memory tracking library may see the memory 
   allocated for this as a leak. */
static int error_space[ERRSTK];

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;
}

/*
=item 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.

=cut
*/
i_errmsg *i_errors() {
  return error_stack + error_sp;
}

/*
=back

=head1 INTERNAL FUNCTIONS

These functions are called by Imager to report errors through the
above interface.

It may be desirable to have functions to mark the stack and reset to
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
*/
void i_clear_error() {
#ifdef IMAGER_DEBUG_MALLOC
  int i;

  for (i = 0; i < ERRSTK; ++i) {
    if (error_space[i]) {
      myfree(error_stack[i].msg);
      error_stack[i].msg = NULL;
      error_space[i] = 0;
    }
  }
#endif
  error_sp = ERRSTK-1;
}

/*
=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.

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
error handling is calling function that does.).

=cut
*/
void i_push_error(int code, char const *msg) {
  size_t size = strlen(msg)+1;

  if (error_sp <= 0)
    /* bad, bad programmer */
    return;

  --error_sp;
  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 released when 
       we need a bigger string */
    /* 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);
  error_stack[error_sp].code = code;

  if (error_cb)
    error_cb(code, msg);
}

/*
=item i_push_errorvf(int C<code>, char const *C<fmt>, va_list C<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) {
  char buf[1024];
#if defined(_MSC_VER)
  _vsnprintf(buf, sizeof(buf), fmt, ap);
#else
  /* is there a way to detect vsnprintf()? 
     for this and other functions we need some mechanism to handle 
     detection (like perl's Configure, or autoconf)
   */
  vsprintf(buf, fmt, ap);
#endif
  i_push_error(code, buf);
}

/*
=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 formatting.

Does not support perl specific format codes.

=cut
*/
void i_push_errorf(int code, char const *fmt, ...) {
  va_list ap;
  va_start(ap, fmt);
  i_push_errorvf(code, fmt, ap);
  va_end(ap);
}

#ifdef IMAGER_I_FAILED
#error "This isn't used and is untested"

/*
=item i_failed(char const *msg)

Called by Imager code to indicate that a top-level has failed.

msg can be NULL, in which case no error is pushed.

Calls the current failed callback, if any.

Aborts the program with an error, if failures have been set to be fatal.

Returns zero if it does not abort.

=cut
*/
int i_failed(int code, char const *msg) {
  if (msg)
    i_push_error(code, msg);
  if (failed_cb)
    failed_cb(error_stack + error_sp);
  if (failures_fatal) {
    int sp;
    size_t total; /* total length of error messages */
    char *full; /* full message for logging */
    if (argv0)
      fprintf(stderr, "%s: ", argv0);
    fputs("error:\n", stderr);
    sp = error_sp;
    while (error_stack[sp].msg) {
      fprintf(stderr, " %s\n", error_stack[sp].msg);
      ++sp;
    }
    /* we want to log the error too, build an error message to hand to
       i_fatal() */
    total = 1; /* remember the NUL */
    for (sp = error_sp; error_stack[sp].msg; ++sp) {
      size_t new_total += strlen(error_stack[sp].msg) + 2;
      if (new_total < total) {
	/* overflow, somehow */
	break;
      }
    }
    full = mymalloc(total);
    if (!full) {
      /* just quit, at least it's on stderr */
      exit(EXIT_FAILURE);
    }
    *full = 0;
    for (sp = error_sp; error_stack[sp].msg; ++sp) {
      strcat(full, error_stack[sp].msg);
      strcat(full, ": ");
    }
    /* lose the extra ": " */
    full[strlen(full)-2] = '\0';
    i_fatal(EXIT_FAILURE, "%s", full);
  }

  return 0;
}

#endif

/*
=item im_assert_fail(file, line, message)

Called when an im_assert() assertion fails.

=cut
*/

void
im_assert_fail(char const *file, int line, char const *message) {
  fprintf(stderr, "Assertion failed line %d file %s: %s\n", 
	  line, file, message);
  exit(EXIT_FAILURE);
}

/*
=back

=head1 BUGS

This interface isn't thread safe.

=head1 AUTHOR

Tony Cook <tony@develop-help.com>

Stack concept by Arnar Mar Hrafnkelsson <addi@umich.edu>

=cut
*/
Commit	Line	Data
606237f9 TC	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
c5cf7614 TC	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.
606237f9 TC	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
92bda632	64	#include "imager.h"
606237f9 TC	65	#include <stdio.h>
	66	#include <stdlib.h>
	67
	68	/* we never actually use the last item - it's the NULL terminator */
	69	#define ERRSTK 20
b33c08f8 TC	70	static i_errmsg error_stack[ERRSTK];
b33c08f8 TC	71	static int error_sp = ERRSTK - 1;
606237f9 TC	72	/* we track the amount of space used each string, so we don't reallocate
	73	space unless we need to.
	74	This also means that a memory tracking library may see the memory
	75	allocated for this as a leak. */
b33c08f8	76	static int error_space[ERRSTK];
606237f9 TC	77
	78	static i_error_cb error_cb;
	79	static i_failed_cb failed_cb;
	80	static int failures_fatal;
	81	static char *argv0;
	82
	83	/*
	84	=item i_set_argv0(char const *program)
	85
	86	Sets the name of the program to be displayed in fatal error messages.
	87
	88	The simplest way to use this is just:
	89
	90	i_set_argv0(argv[0]);
	91
	92	when your program starts.
	93	*/
	94	void i_set_argv0(char const *name) {
c5cf7614	95	char *dupl;
606237f9 TC	96	if (!name)
606237f9 TC	97	return;
f0960b14 TC	98	/* if the user has an existing string of MAXINT length then
	99	the system is broken anyway */
	100	dupl = mymalloc(strlen(name)+1); /* check 17jul05 tonyc */
606237f9 TC	101	strcpy(dupl, name);
	102	if (argv0)
	103	myfree(argv0);
	104	argv0 = dupl;
	105	}
	106
	107	/*
	108	=item i_set_failure_fatal(int failure_fatal)
	109
	110	If failure_fatal is non-zero then any future failures will result in
	111	Imager exiting your program with a message describing the failure.
	112
	113	Returns the previous setting.
	114
	115	=cut
	116	*/
	117	int i_set_failures_fatal(int fatal) {
	118	int old = failures_fatal;
	119	failures_fatal = fatal;
	120
	121	return old;
	122	}
	123
	124	/*
	125	=item i_set_error_cb(i_error_cb)
	126
	127	Sets a callback function that is called each time an error is pushed
	128	onto the error stack.
	129
	130	Returns the previous callback.
	131
	132	i_set_failed_cb() is probably more useful.
	133
	134	=cut
	135	*/
	136	i_error_cb i_set_error_cb(i_error_cb cb) {
	137	i_error_cb old = error_cb;
	138	error_cb = cb;
	139
	140	return old;
	141	}
	142
	143	/*
	144	=item i_set_failed_cb(i_failed_cb cb)
	145
	146	Sets a callback function that is called each time an Imager function
	147	fails.
	148
	149	Returns the previous callback.
	150
	151	=cut
	152	*/
	153	i_failed_cb i_set_failed_cb(i_failed_cb cb) {
	154	i_failed_cb old = failed_cb;
	155	failed_cb = cb;
	156
	157	return old;
	158	}
	159
	160	/*
	161	=item i_errors()
	162
	163	Returns a pointer to the first element of an array of error messages,
	164	terminated by a NULL pointer. The highest level message is first.
165
166	=cut
167	*/
c5cf7614	168	i_errmsg *i_errors() {
606237f9 TC	169	return error_stack + error_sp;
	170	}
	171
	172	/*
	173	=back
	174
	175	=head1 INTERNAL FUNCTIONS
	176
	177	These functions are called by Imager to report errors through the
	178	above interface.
	179
	180	It may be desirable to have functions to mark the stack and reset to
	181	the mark.
	182
	183	=over
	184
	185	=item i_clear_error()
6cfee9d1	186	=synopsis i_clear_error();
92bda632 TC	187	=category Error handling
	188
	189	Clears the error stack.
	190
5715f7c3	191	Called by any Imager function before doing any other processing.
606237f9	192
92bda632 TC	193	=cut
92bda632 TC	194	*/
606237f9	195	void i_clear_error() {
cd4b0b20 TC	196	#ifdef IMAGER_DEBUG_MALLOC
	197	int i;
	198
	199	for (i = 0; i < ERRSTK; ++i) {
	200	if (error_space[i]) {
	201	myfree(error_stack[i].msg);
	202	error_stack[i].msg = NULL;
	203	error_space[i] = 0;
	204	}
	205	}
	206	#endif
606237f9 TC	207	error_sp = ERRSTK-1;
	208	}
	209
	210	/*
faa9b3e7	211	=item i_push_error(int code, char const *msg)
6cfee9d1 TC	212	=synopsis i_push_error(0, "Yep, it's broken");
6cfee9d1 TC	213	=synopsis i_push_error(errno, "Error writing");
92bda632 TC	214	=category Error handling
92bda632 TC	215
6cfee9d1	216	Called by an Imager function to push an error message onto the stack.
606237f9 TC	217
	218	No message is pushed if the stack is full (since this means someone
	219	forgot to call i_clear_error(), or that a function that doesn't do
	220	error handling is calling function that does.).
	221
	222	=cut
	223	*/
c5cf7614	224	void i_push_error(int code, char const *msg) {
8d14daab	225	size_t size = strlen(msg)+1;
606237f9 TC	226
	227	if (error_sp <= 0)
	228	/* bad, bad programmer */
	229	return;
	230
	231	--error_sp;
	232	if (error_space[error_sp] < size) {
c5cf7614 TC	233	if (error_stack[error_sp].msg)
c5cf7614 TC	234	myfree(error_stack[error_sp].msg);
f0960b14	235	/* memory allocated on the following line is only ever released when
606237f9	236	we need a bigger string */
f0960b14 TC	237	/* size is size (len+1) of an existing string, overflow would mean
	238	the system is broken anyway */
	239	error_stack[error_sp].msg = mymalloc(size); /* checked 17jul05 tonyc */
606237f9 TC	240	error_space[error_sp] = size;
606237f9 TC	241	}
c5cf7614 TC	242	strcpy(error_stack[error_sp].msg, msg);
c5cf7614 TC	243	error_stack[error_sp].code = code;
606237f9 TC	244
606237f9 TC	245	if (error_cb)
c5cf7614 TC	246	error_cb(code, msg);
	247	}
	248
	249	/*
5715f7c3	250	=item i_push_errorvf(int C<code>, char const *C<fmt>, va_list C<ap>)
c5cf7614	251
92bda632 TC	252	=category Error handling
92bda632 TC	253
c5cf7614 TC	254	Intended for use by higher level functions, takes a varargs pointer
	255	and a format to produce the finally pushed error message.
	256
6cfee9d1 TC	257	Does not support perl specific format codes.
6cfee9d1 TC	258
c5cf7614 TC	259	=cut
	260	*/
	261	void i_push_errorvf(int code, char const *fmt, va_list ap) {
	262	char buf[1024];
	263	#if defined(_MSC_VER)
	264	_vsnprintf(buf, sizeof(buf), fmt, ap);
	265	#else
	266	/* is there a way to detect vsnprintf()?
	267	for this and other functions we need some mechanism to handle
	268	detection (like perl's Configure, or autoconf)
	269	*/
	270	vsprintf(buf, fmt, ap);
	271	#endif
	272	i_push_error(code, buf);
	273	}
	274
	275	/*
	276	=item i_push_errorf(int code, char const *fmt, ...)
6cfee9d1	277	=synopsis i_push_errorf(errno, "Cannot open file %s: %d", filename, errno);
92bda632 TC	278	=category Error handling
92bda632 TC	279
5715f7c3	280	A version of i_push_error() that does printf() like formatting.
c5cf7614	281
6cfee9d1 TC	282	Does not support perl specific format codes.
6cfee9d1 TC	283
c5cf7614 TC	284	=cut
	285	*/
	286	void i_push_errorf(int code, char const *fmt, ...) {
	287	va_list ap;
	288	va_start(ap, fmt);
	289	i_push_errorvf(code, fmt, ap);
	290	va_end(ap);
606237f9 TC	291	}
606237f9 TC	292
f0960b14 TC	293	#ifdef IMAGER_I_FAILED
	294	#error "This isn't used and is untested"
	295
606237f9 TC	296	/*
	297	=item i_failed(char const *msg)
	298
	299	Called by Imager code to indicate that a top-level has failed.
	300
c5cf7614	301	msg can be NULL, in which case no error is pushed.
606237f9 TC	302
	303	Calls the current failed callback, if any.
	304
	305	Aborts the program with an error, if failures have been set to be fatal.
	306
	307	Returns zero if it does not abort.
	308
	309	=cut
	310	*/
c5cf7614	311	int i_failed(int code, char const *msg) {
606237f9	312	if (msg)
c5cf7614	313	i_push_error(code, msg);
606237f9 TC	314	if (failed_cb)
	315	failed_cb(error_stack + error_sp);
	316	if (failures_fatal) {
c5cf7614	317	int sp;
8d14daab	318	size_t total; /* total length of error messages */
c5cf7614	319	char full; / full message for logging */
606237f9 TC	320	if (argv0)
	321	fprintf(stderr, "%s: ", argv0);
	322	fputs("error:\n", stderr);
c5cf7614 TC	323	sp = error_sp;
c5cf7614 TC	324	while (error_stack[sp].msg) {
a743c0a6	325	fprintf(stderr, " %s\n", error_stack[sp].msg);
c5cf7614 TC	326	++sp;
	327	}
	328	/* we want to log the error too, build an error message to hand to
b1e96952	329	i_fatal() */
c5cf7614 TC	330	total = 1; /* remember the NUL */
c5cf7614 TC	331	for (sp = error_sp; error_stack[sp].msg; ++sp) {
8d14daab TC	332	size_t new_total += strlen(error_stack[sp].msg) + 2;
	333	if (new_total < total) {
	334	/* overflow, somehow */
	335	break;
	336	}
c5cf7614	337	}
a6c47345	338	full = mymalloc(total);
c5cf7614 TC	339	if (!full) {
	340	/* just quit, at least it's on stderr */
	341	exit(EXIT_FAILURE);
	342	}
	343	*full = 0;
	344	for (sp = error_sp; error_stack[sp].msg; ++sp) {
	345	strcat(full, error_stack[sp].msg);
	346	strcat(full, ": ");
606237f9	347	}
c5cf7614 TC	348	/* lose the extra ": " */
c5cf7614 TC	349	full[strlen(full)-2] = '\0';
b1e96952	350	i_fatal(EXIT_FAILURE, "%s", full);
606237f9 TC	351	}
	352
	353	return 0;
	354	}
	355
f0960b14 TC	356	#endif
f0960b14 TC	357
b3afeed5 TC	358	/*
	359	=item im_assert_fail(file, line, message)
	360
	361	Called when an im_assert() assertion fails.
	362
	363	=cut
	364	*/
	365
	366	void
	367	im_assert_fail(char const file, int line, char const message) {
	368	fprintf(stderr, "Assertion failed line %d file %s: %s\n",
	369	line, file, message);
	370	exit(EXIT_FAILURE);
	371	}
	372
606237f9 TC	373	/*
	374	=back
	375
	376	=head1 BUGS
	377
	378	This interface isn't thread safe.
	379
	380	=head1 AUTHOR
	381
	382	Tony Cook <tony@develop-help.com>
	383
	384	Stack concept by Arnar Mar Hrafnkelsson <addi@umich.edu>
	385
	386	=cut
	387	*/