1
###############################################################################
3
# (c) Copyright @ 2000, Randy J. Ray <rjray@blackperl.com>
6
###############################################################################
8
# $Id: Header.pm,v 1.20 2001/04/27 09:05:21 rjray Exp $
10
# Description: The RPM::Header class provides access to the RPM Header
11
# structure as a tied hash, allowing direct access to the
12
# tags in a header as keys, and the content of said tags
21
# Global Consts: None.
23
# Environment: Just stuff from the RPM config.
25
###############################################################################
32
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $AUTOLOAD);
33
use subs qw(new AUTOLOAD filenames);
39
use RPM::Constants ':rpmerr';
41
$VERSION = do { my @r=(q$Revision: 1.20 $=~/\d+/g); sprintf "%d."."%02d"x$#r,@r };
45
@EXPORT_OK = qw(RPM_HEADER_MASK RPM_HEADER_READONLY);
46
%EXPORT_TAGS = (all => \@EXPORT_OK);
53
($constname = $AUTOLOAD) =~ s/.*:://;
54
die "& not defined" if $constname eq 'constant';
55
my $val = constant($constname);
58
die "Your vendor has not defined RPM macro $constname";
61
*$AUTOLOAD = sub { $val };
70
tie %hash, $class, @_;
73
###############################################################################
77
# Description: Glue together the contents of BASENAMES, DIRNAMES and
78
# DIRINDEXES to create a single list of fully-qualified
81
# Arguments: NAME IN/OUT TYPE DESCRIPTION
82
# $self in ref Object of this class
88
# Returns: Success: listref
91
###############################################################################
96
# Each of these three fetches will have already triggered rpm_error, were
98
my $base = $self->{BASENAMES} || return undef;
99
my $dirs = $self->{DIRNAMES} || return undef;
100
my $idxs = $self->{DIRINDEXES} || return undef;
102
unless (@$base == @$idxs)
104
rpm_error(RPMERR_INTERNAL,
105
"Mis-matched elements lists for BASENAMES and DIRINDEXES");
109
# The value from DIRNAMES already has the trailing separator
110
[ map { "$dirs->[$idxs->[$_]]$base->[$_]" } (0 .. $#$base) ];
118
RPM::Header - Access to RPM package headers
124
tie %hdr, "RPM::Header", "rpm-3.0.4-0.48.i386.rpm" or die "$RPM::err";
133
The B<RPM::Header> package permits access to the header of a package (external
134
file or currently installed) as either a tied hash or a blessed hash reference.
135
The tags that are present in the header are expressed as keys. Retrieving
136
them via C<keys> or C<each> returns the tags in the order in which they
137
appear in the header. Keys may be requested without regard for letter case,
138
but they are always returned as all upper-case.
140
The return value corresponding to each key is a list reference or scalar
141
(or C<undef> if the key is not valid), depending on the data-type of the
142
key. Each of the header tags are noted with one of C<$> or C<@> in the
143
B<RPM::Constants> documentation. The C<defined> keyword should be used
144
for testing success versus failure, as empty tags are possible. See the
145
C<scalar_tag> test, below.
147
This is a significant change from versions prior to 0.27, in which the
148
return value was always a list reference. This new approach brings
149
B<RPM::Header> more in line with other interfaces to B<rpm> header information.
151
B<RPM::Header> objects are also the native return value from keys retrieved
152
in the B<RPM::Database> class (see L<RPM::Database>). In these cases, the
153
header data is marked read-only, and attempts to alter any of the keys will
156
There are also a number of class methods implemented, which are described in
161
=head2 Creating an Object
163
An object may be created one of two ways:
165
tie %h, "RPM::Header", "filename";
167
$href = new RPM::Header "filename";
169
The latter approach offers more direct access to the class methods, while
170
also permitting the usual tied-hash operations such as fetching:
172
$href->{tag} # Such as "name" or "version"
176
The following methods are available to objects of this class, in addition to
177
the tied-hash suite of operations. If the object is a hash instead of a
178
hash reference, it can be used to call these methods via:
180
(tied %hash)->method_name(...)
186
The B<RPM> system attempts to save space by splitting up the file paths into
187
the leafs (stored by the tag C<BASENAMES>), the directories (stored under
188
C<DIRNAMES>) and indexes into the list of directories (stored under
189
C<DIRINDEXES>). As a convenience, this method re-assembles the list of
190
filenames and returns it as a list reference. If an error occurs, C<undef>
191
will be returned after C<rpm_error> has been called.
195
Returns true (1) or false (0), depending on whether the package the header
196
object is derived from is a source RPM.
200
Return the size of the header, in bytes, within the disk file containing the
201
associated package. The value is also returned for those headers within the
204
=item scalar_tag(TAG)
206
Returns a true/false value (1 or 0) based on whether the value returned by
207
the specified tag is a scalar or an array reference. Useful in place of
208
using C<ref> to test the fetched values. B<TAG> may be either a string (name)
209
or a number (imported from the B<RPM::Constants> tag C<:rpmtag>). This
210
method may be called as a class (static) method.
214
Given a tag I<TAG>, return the type as a numerical value. The valid types
215
can be imported from the B<RPM::Constants> package via the import-tag
222
Used internally by B<rpm>.
226
The data returned is a single chunk of binary data. It has been converted to
227
a single "string" in Perl terms, but may contain nulls within it. The
228
B<length()> keyword should return the correct size for the chunk.
232
All items are single-character in nature. Note that since Perl does not
233
distinguish single characters versus strings in the way that C does, these
234
are stored as single-character strings. It is a tradeoff of efficiency over
239
All items are integers no larger than 8 bits wide.
243
All items are integers no larger than 16 bits wide.
247
All items are integers no larger than 32 bits wide.
249
=item RPM_STRING_TYPE
251
=item RPM_I18NSTRING_TYPE
253
=item RPM_STRING_ARRAY_TYPE
255
These three are functionally similar from the Perl perspective. Currently,
256
B<RPM> does not export data in an I18N format, it will have been converted to
257
an ordinary string before being handed to the caller (in this case, before
258
the internal Perl/XS code receives it). The distinction between STRING and
259
STRING_ARRAY types is only relevant internally. All of these are sequences of
260
one or more text strings, returned in the same internal order as they are
261
stored within the header.
267
The commonly-needed data triple of (B<name>, B<version>, B<release>) may be
268
accessed more directly by means of this method. It returns the three values
269
on the stack, saving the need for three separate fetches.
273
Compare the version of the current header against that in the header
274
referenced by C<$other>. The argument should be an object reference, not
275
a tied-hash representation of a header. Returns -1, 0 or 1, based on the
276
established behavior of other comparison operators (C<cmp> and C<E<lt>=E<gt>>);
277
-1 indicates that the calling object is considered less, or older, than the
278
passed argument. A value of 1 indicates that the calling object is greater,
279
or newer, than the argument. A value of 0 indicates that they are equal.
283
If the B<RPM::Header> object is created directly from a file, FTP source
284
or HTTP source, then that source is kept for future reference and may be
285
retrieved using this accessor. This will be an empty string if the header
286
was retrieved from the RPM database, or was built in-memory from data.
292
Direct binding to the internal error-management of B<rpm> is still under
293
development. At present, most operations generate their diagnostics to
298
This is currently regarded as alpha-quality software. The interface is
299
subject to change in future releases.
303
L<RPM>, L<RPM::Database>, L<RPM::Constants>, L<perl>, L<rpm>
307
Randy J. Ray <rjray@blackperl.com>