RPM::Error(3)

NAME
RPM::Error - Functions to supplement the internal error management of RPM

SYNOPSIS
    use RPM::Error;
    use RPM::Constants ':rpmerr';
    set_error_callback(sub { ... });
    rpm_error(RPMERR_DBOPEN, "Error opening RPM DB: $!");

DESCRIPTION
The RPM::Error package provides access to some functions that work with (but do not replace) the special `$RPM::err' variable. These routines allow for reporting errors through the RPM facility, clearing the error variable, and registering a callback function to be invoked whenever a new error is raised.

None of these routines are required for normal use of the special variable `$RPM::err' (see the RPM manpage).

USAGE
The following routines are exported by RPM::Error:

rpm_error($code, $message)
    Report an error through the internal facility used by rpm. By using this function, the special error variable is set up to have a dual-nature: When evaluated in a numeric context, it returns the numerical code `$code'. When evaluated as a string, it will return `$message'. The value of `$code' should be (but is not required to be) one of the values exported from the RPM::Constants package via the :rpmerr tag. `$message' may be any string value.

clear_errors()
    Clears both the numeric and string values of `$RPM::err'.

$old_cb = set_error_callback($subr)
    Set a (new) callback to be invoked whenever a new error is flagged. Returns the old (existing) callback value if there was one, `undef' otherwise.

    The parameter to this call should be either a subroutine reference or a closure. A subroutine name may be passed; if so, it should either be given a package qualification or exist in the `main::' namespace. The routine, when invoked, will be passed the numeric code and the message string being raised as the error. Note that the callback may be invoked by internal error flagging in the core rpm library, as well as by calls to rpm_error above.

    Before any user-provided callback is invoked, the `$RPM::err' variable is set. While accessing it in a callback would be redundant, users should not be concerned about interrupting other internal processes (in theory, that is).

DIAGNOSTICS
If the value passed to set_error_callback is not valid, the current callback is set to a null value.

CAVEATS
The code value passed to rpm_error is not checked against the list of valid constants before assignment.

SEE ALSO
the RPM manpage, the perl manpage, the rpm manpage

AUTHOR
Randy J. Ray <rjray@blackperl.com>