RPM::Header(3)

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 the RPM::Database manpage). 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
the RPM manpage, the RPM::Database manpage, the RPM::Constants manpage, the perl manpage, the rpm manpage

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