# Errors

MuPDF uses a `setjmp` based exception handling system. This is encapsulated by
the use of three macros: `fz_try`, `fz_always`, and `fz_catch`. When an error
is raised by `fz_throw`, or re-raised by `fz_rethrow`, execution will jump to
the enclosing always/catch block.

All functions you call should be guarded by a `fz_try` block to catch the
errors, or the program will call `exit()` on errors. You don't want that.

The `fz_always` block is optional. It is typically used to free memory or
release resources unconditionally, in both the case when the execution of the
try block succeeds, and when an error occurs.

	fz_try(ctx) {
		// Do stuff that may throw an exception.
	}
	fz_always(ctx) {
		// This (optional) block is always executed.
	}
	fz_catch(ctx) {
		// This block is only executed when recovering from an exception.
	}


Since the `fz_try` macro is based on `setjmp`, the same conditions that apply
to local variables in the presence of `setjmp` apply. Any locals written to
inside the try block may be restored to their pre-try state when an error
occurs. We provide a `fz_var()` macro to guard against this.

In the following example, if we don't guard `buf` with `fz_var`, then when an
error occurs the `buf` local variable might have be reset to its pre-try value
(`NULL`) and we would leak the memory.

	char *buf = NULL;

	fz_var(buf);

	fz_try(ctx) {
		buf = fz_malloc(ctx, 100);
		// Do stuff with buf that may throw an exception.
	}
	fz_always(ctx) {
		fz_free(ctx, buf);
	}
	fz_catch(ctx) {
		fz_rethrow(ctx);
	}

Carefully note that you should **never** return from within a `fz_try` or
`fz_always block`! Doing so will unbalance the exception stack, and things will
go catastrophically wrong. Instead, it is possible to break out of the `fz_try`
and `fz_always` block by using a break statement if you want to exit the block
early without throwing an exception.

Throwing a new exception can be done with `fz_throw`. Passing an exception
along after having cleaned up in the `fz_catch` block can be done with
`fz_rethrow`. `fz_throw` takes a `printf`-like formatting string.

    enum {
        FZ_ERROR_SYSTEM, // fatal out of memory or syscall error
        FZ_ERROR_LIBRARY, // unclassified error from third-party library
        FZ_ERROR_ARGUMENT, // invalid or out-of-range arguments to functions
        FZ_ERROR_LIMIT, // failed because of resource or other hard limits
        FZ_ERROR_UNSUPPORTED, // tried to use an unsupported feature
        FZ_ERROR_FORMAT, // syntax or format errors that are unrecoverable
        FZ_ERROR_SYNTAX, // syntax errors that should be diagnosed and ignored
    };

    void fz_throw(fz_context *ctx, int error_code, const char *fmt, ...);
    void fz_rethrow(fz_context *ctx);