m4_comment([$Id: runtime.so,v 10.21 2007/07/10 17:37:22 bostic Exp $])

m4_ref_title(Debugging Applications,
    Run-time error information,, debug/compile, debug/printlog)

m4_p([dnl
Normally, when an error occurs in the m4_db library, an integer value
(either a m4_db specific value or a system m4_envvar(errno) value) is
returned by m4_db.  In some cases, however, this value may be
insufficient to completely describe the cause of the error, especially
during initial application debugging.])

m4_p([dnl
Most m4_db errors will result in additional information being written
to a standard file descriptor or output stream.  Additionally, m4_db can
be configured to pass these verbose error messages to an application
function.  There are four methods intended to provide applications with
additional error information:
m4_ref(dbenv_set_errcall), m4_ref(dbenv_set_errfile),
m4_ref(dbenv_set_errpfx), and m4_ref(dbenv_set_verbose).])

m4_p([dnl
The m4_db error-reporting facilities do not slow performance or
significantly increase application size, and may be run during normal
operation as well as during debugging.  Where possible, we recommend
these options always be configured and the output saved in the
filesystem.  We have found that this often saves time when debugging
installation or other system-integration problems.])

m4_p([dnl
In addition, there are three methods to assist applications in
displaying their own error messages: m4_ref(dbenv_strerror),
m4_ref(dbenv_err), and m4_ref(dbenv_errx).  The first is a superset of
the ANSI C strerror function, and returns a descriptive string for any
error return from the m4_db library.  The m4_ref(dbenv_err) and
m4_refT(dbenv_errx)s use the error message configuration options
described previously to format and display error messages to appropriate
output devices.])

m4_page_footer