Error handling
==============

This section describes error handling in the code.

The most common serious error is memory exhaustion. If malloc(), strdup(), etc.
fails, clean up and free any partially complete structures leaving data in a
consistent state, and return a value which indicates failure, eg. 0 for
functions which return a pointer (document the value in the function
documentation). The caller should then propagate the failure up in the same way.
At some point, the error should stop being passed up and be reported to the user
using

  warn_user("NoMemory", 0);

The other common error is one returned by a RISC OS SWI. Always use "X" SWIs,
something like this:

  os_error *error;
  error = xwimp_get_pointer_info(&pointer);
  if (error) {
	LOG(("xwimp_get_pointer_info: 0x%x: %s\n",
			error->errnum, error->errmess));
	warn_user("WimpError", error->errmess);
	return false;
  }

If an error occurs during initialisation, in most cases exit immediately using
die(), since this indicates that there is already insufficient memory, or a
resource file is corrupted, etc.
