/*! @page error_handling Error handling

WiredTiger operations return a value of 0 on success and a non-zero
value on error.  Error codes may be either positive or negative:
positive error codes are standard error codes as described for
POSIX-like systems (for example, \c EINVAL or \c EBUSY), negative error
codes are WiredTiger-specific (for example, \c WT_ROLLBACK).

WiredTiger-specific error codes always appear in the -31,800 to -31,999
range, inclusive.

WiredTiger returns \c EBUSY for operations requiring exclusive access, when
an object is not available for exclusive access. For example, the
WT_SESSION::drop or WT_SESSION::verify methods will fail if the object
has open cursors. Note that internal WiredTiger threads may temporarily
open cursors on objects (for example, threads performing operations like
statistics logging), and operations may temporarily fail and return \c EBUSY
when there are no application cursors open on the object.

The following is a complete list of the WiredTiger-specific return
values:

@if IGNORE_BUILT_BY_API_ERR_BEGIN
@endif

@par <code>WT_ROLLBACK</code>
This error is generated when an operation cannot be completed due to a conflict with concurrent
operations. The operation may be retried; if a transaction is in progress, it should be rolled back
and the operation retried in a new transaction.

@par <code>WT_DUPLICATE_KEY</code>
This error is generated when the application attempts to insert a record with the same key as an
existing record without the 'overwrite' configuration to WT_SESSION::open_cursor.

@par <code>WT_ERROR</code>
This error is returned when an error is not covered by a specific error return.

@par <code>WT_NOTFOUND</code>
This error indicates an operation did not find a value to return. This includes cursor search and
other operations where no record matched the cursor's search key such as WT_CURSOR::update or
WT_CURSOR::remove.

@par <code>WT_PANIC</code>
This error indicates an underlying problem that requires a database restart. The application may
exit immediately, no further WiredTiger calls are required (and further calls will themselves
immediately fail).

@par <code>WT_RUN_RECOVERY</code>
This error is generated when wiredtiger_open is configured to return an error if recovery is
required to use the database.

@par <code>WT_CACHE_FULL</code>
This error is only generated when wiredtiger_open is configured to run in-memory, and an insert or
update operation requires more than the configured cache size to complete, or when an application
thread fails to do eviction within cache_max_wait_ms. The operation may be retried; if a transaction
is in progress, it should be rolled back and the operation retried in a new transaction.

@par <code>WT_PREPARE_CONFLICT</code>
This error is generated when the application attempts to update an already updated record which is
in prepared state. An updated record will be in prepared state, when the transaction that performed
the update is in prepared state.

@par <code>WT_TRY_SALVAGE</code>
This error is generated when corruption is detected in an on-disk file. During normal operations,
this may occur in rare circumstances as a result of a system crash. The application may choose to
salvage the file or retry wiredtiger_open with the 'salvage=true' configuration setting.

@if IGNORE_BUILT_BY_API_ERR_END
@endif

@section error_translation Translating errors

The WT_SESSION::strerror and ::wiredtiger_strerror functions return the
standard text message associated with any WiredTiger, ISO C, or POSIX
standard API.

@snippet ex_all.c Display an error thread safe

@snippet ex_all.c Display an error

Note that ::wiredtiger_strerror is not thread-safe.

@section event_message_handling Message handling using the WT_EVENT_HANDLER

Specific error and other message handling can be configured by passing an
implementation of WT_EVENT_HANDLER to ::wiredtiger_open or
WT_CONNECTION::open_session.

For example, both informational and error messages might be passed to an
application-specific logging function that added a timestamp and logged
the message to a file, and error messages might additionally be output to
the \c stderr file stream.

Additionally, applications will normally handle \c WT_PANIC as a special
case.  WiredTiger will always call the error handler callback with
\c WT_PANIC in the case of a fatal error requiring database restart,
however, WiredTiger cannot guarantee applications will see an application
thread return \c WT_PANIC from a WiredTiger API call. For this reason, a
correctly-written WiredTiger application will likely specify at least an
error handler which will immediately exit or otherwise handle fatal errors.
Note that no further WiredTiger calls are required after an error handler
is called with \c WT_PANIC (and further calls will themselves immediately
fail).

@snippet ex_event_handler.c Function event_handler
@snippet ex_event_handler.c Configure event_handler

*/