NAME

RPM::Header - Access to RPM package headers

SYNOPSIS

use RPM::Header;

tie %hdr, "RPM::Header", "rpm-3.0.4-0.48.i386.rpm" or die "$RPM::err";

for (sort keys %hdr)
{
    ...
}

DESCRIPTION

The RPM::Header package permits access to the header of a package (external file or currently installed) as either a tied hash or a blessed hash reference. The tags that are present in the header are expressed as keys. Retrieving them via keys or each returns the tags in the order in which they appear in the header. Keys may be requested without regard for letter case, but they are always returned as all upper-case.

The return value corresponding to each key is a list reference or scalar (or undef if the key is not valid), depending on the data-type of the key. Each of the header tags are noted with one of $ or @ in the RPM::Constants documentation. The defined keyword should be used for testing success versus failure, as empty tags are possible. See the scalar_tag test, below.

This is a significant change from versions prior to 0.27, in which the return value was always a list reference. This new approach brings RPM::Header more in line with other interfaces to rpm header information.

RPM::Header objects are also the native return value from keys retrieved in the RPM::Database class (see RPM::Database). In these cases, the header data is marked read-only, and attempts to alter any of the keys will generate an error.

There are also a number of class methods implemented, which are described in the next section.

USAGE

Creating an Object

An object may be created one of two ways:

tie %h, "RPM::Header", "filename";

$href = new RPM::Header "filename";

The latter approach offers more direct access to the class methods, while also permitting the usual tied-hash operations such as fetching:

$href->{tag}    # Such as "name" or "version"

Class Methods

The following methods are available to objects of this class, in addition to the tied-hash suite of operations. If the object is a hash instead of a hash reference, it can be used to call these methods via:

(tied %hash)->method_name(...)

filenames

The RPM system attempts to save space by splitting up the file paths into the leafs (stored by the tag BASENAMES), the directories (stored under DIRNAMES) and indexes into the list of directories (stored under DIRINDEXES). As a convenience, this method re-assembles the list of filenames and returns it as a list reference. If an error occurs, undef will be returned after rpm_error has been called.

is_source

Returns true (1) or false (0), depending on whether the package the header object is derived from is a source RPM.

size

Return the size of the header, in bytes, within the disk file containing the associated package. The value is also returned for those headers within the database.

scalar_tag(TAG)

Returns a true/false value (1 or 0) based on whether the value returned by the specified tag is a scalar or an array reference. Useful in place of using ref to test the fetched values. TAG may be either a string (name) or a number (imported from the RPM::Constants tag :rpmtag). This method may be called as a class (static) method.

tagtype(TAG)

Given a tag TAG, return the type as a numerical value. The valid types can be imported from the RPM::Constants package via the import-tag ":rpmtype", and are:

RPM_NULL_TYPE

Used internally by rpm.

RPM_BIN_TYPE

The data returned is a single chunk of binary data. It has been converted to a single "string" in Perl terms, but may contain nulls within it. The length() keyword should return the correct size for the chunk.

RPM_CHAR_TYPE

All items are single-character in nature. Note that since Perl does not distinguish single characters versus strings in the way that C does, these are stored as single-character strings. It is a tradeoff of efficiency over memory.

RPM_INT8_TYPE

All items are integers no larger than 8 bits wide.

RPM_INT16_TYPE

All items are integers no larger than 16 bits wide.

RPM_INT32_TYPE

All items are integers no larger than 32 bits wide.

RPM_STRING_TYPE

RPM_I18NSTRING_TYPE

RPM_STRING_ARRAY_TYPE

These three are functionally similar from the Perl perspective. Currently, RPM does not export data in an I18N format, it will have been converted to an ordinary string before being handed to the caller (in this case, before the internal Perl/XS code receives it). The distinction between STRING and STRING_ARRAY types is only relevant internally. All of these are sequences of one or more text strings, returned in the same internal order as they are stored within the header.

NVR

The commonly-needed data triple of (name, version, release) may be accessed more directly by means of this method. It returns the three values on the stack, saving the need for three separate fetches.

cmpver(OTHER)

Compare the version of the current header against that in the header referenced by $other. The argument should be an object reference, not a tied-hash representation of a header. Returns -1, 0 or 1, based on the established behavior of other comparison operators (cmp and <=>); -1 indicates that the calling object is considered less, or older, than the passed argument. A value of 1 indicates that the calling object is greater, or newer, than the argument. A value of 0 indicates that they are equal.

source_name

If the RPM::Header object is created directly from a file, FTP source or HTTP source, then that source is kept for future reference and may be retrieved using this accessor. This will be an empty string if the header was retrieved from the RPM database, or was built in-memory from data.

DIAGNOSTICS

Direct binding to the internal error-management of rpm is still under development. At present, most operations generate their diagnostics to STDERR.

CAVEATS

This is currently regarded as alpha-quality software. The interface is subject to change in future releases.

SEE ALSO

RPM, RPM::Database, RPM::Constants, perl, rpm

AUTHORS

Randy J. Ray <rjray@blackperl.com>, Alexey Tourbin <at@altlinux.org>.