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 RPM).

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

RPM, perl, rpm

AUTHOR

Randy J. Ray <rjray@blackperl.com>