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 undef if the key is not valid). This is due to the fact that any of the tags may have more than one piece of data associated, and the FETCH interface to hashes presumes scalar calling context and return value. Thus, rather than require developers to frequently test the return value as a reference or not, the value is simple always returned as a list ref, even if there is only one element.

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

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.

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 ":rpmtypes", 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.

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, perl, rpm

AUTHOR

Randy J. Ray <rjray@blackperl.com>