.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Lintian::Collect::Package 3"
.TH Lintian::Collect::Package 3 "2019-05-26" "Lintian v2.15.0" "Debian Package Checker"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Lintian::Collect::Package \- Lintian base interface to binary and source package data collection
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use autodie;
\&    use Lintian::Collect;
\&    
\&    my ($name, $type, $dir) = (\*(Aqfoobar\*(Aq, \*(Aqsource\*(Aq, \*(Aq/path/to/lab\-entry\*(Aq);
\&    my $info = Lintian::Collect\->new ($name, $type, $dir);
\&    my $filename = "etc/conf.d/$name.conf";
\&    my $file = $info\->index_resolved_path($filename);
\&    if ($file and $file\->is_open_ok) {
\&        my $fd = $info\->open;
\&        # Use $fd ...
\&        close($fd);
\&    } elsif ($file) {
\&        print "$file is available, but is not a file or unsafe to open\en";
\&    } else {
\&        print "$file is missing\en";
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Lintian::Collect::Package provides part of an interface to package
data for source and binary packages.  It implements data collection
methods specific to all packages that can be unpacked (or can contain
files)
.PP
This module is in its infancy.  Most of Lintian still reads all data from
files in the laboratory whenever that data is needed and generates that
data via collect scripts.  The goal is to eventually access all data about
source packages via this module so that the module can cache data where
appropriate and possibly retire collect scripts in favor of caching that
data in memory.
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
In addition to the instance methods listed below, all instance methods
documented in the Lintian::Collect module are also available.
.IP "unpacked ([\s-1FILE\s0])" 4
.IX Item "unpacked ([FILE])"
Returns the path to the directory in which the package has been
unpacked.  \s-1FILE\s0 must be either a Lintian::Path object (>= 2.5.13~)
or a string denoting the requested path.  In the latter case, the path
must be relative to the root of the package and should be normalized.
.Sp
It is not permitted for \s-1FILE\s0 to be \f(CW\*(C`undef\*(C'\fR.  If the \*(L"root\*(R" dir is
desired either invoke this method without any arguments at all, pass
it the correct Lintian::Path or the empty string.
.Sp
If \s-1FILE\s0 is not in the package, it returns the path to a non-existent
file entry.
.Sp
The path returned is not guaranteed to be inside the Lintian Lab as
the package may have been unpacked outside the Lab (e.g. as
optimization).
.Sp
Caveat with symlinks: Package is extracted as is and the path returned
by this method points to the extracted file object.  If this is a
symlink, it may \*(L"escape the root\*(R" and point to a file outside the lab
(and a path traversal).
.Sp
The following code may be helpful in checking for path traversal:
.Sp
.Vb 1
\& use Lintian::Util qw(is_ancestor_of);
\&
\& my $collect = ... ;
\& my $file = \*(Aq../../../etc/passwd\*(Aq;
\& my $uroot = $collect\->unpacked;
\& my $ufile = $collect\->unpacked($file);
\& # $uroot will exist, but $ufile might not.
\& if ( \-e $ufile && is_ancestor_of($uroot, $ufile)) {
\&    # has not escaped $uroot
\&    do_stuff($ufile);
\& } elsif ( \-e $ufile) {
\&    # escaped $uroot
\&    die "Possibly path traversal ($file)";
\& } else {
\&    # Does not exists
\& }
.Ve
.Sp
Alternatively one can use normalize_pkg_path in Lintian::Util or
link_normalized.
.Sp
To get a list of entries in the package or the file meta data of the
entries (as path objects), see \*(L"sorted_index\*(R" and
\&\*(L"index (\s-1FILE\s0)\*(R".
.Sp
Needs-Info requirements for using \fIunpacked\fR: unpacked
.IP "file_info (\s-1FILE\s0)" 4
.IX Item "file_info (FILE)"
Returns the output of \fBfile\fR\|(1) for \s-1FILE\s0 (if it exists) or \f(CW\*(C`undef\*(C'\fR.
.Sp
\&\s-1NB:\s0 The value may have been calibrated by Lintian.  A notorious example
is gzip files, where \fBfile\fR\|(1) can be unreliable at times (see #620289)
.Sp
Needs-Info requirements for using \fIfile_info\fR: file-info
.IP "md5sums" 4
.IX Item "md5sums"
Returns a hashref mapping a \s-1FILE\s0 to its md5sum.  The md5sum is
computed by Lintian during extraction and is not guaranteed to match
the md5sum in the \*(L"md5sums\*(R" control file.
.Sp
Needs-Info requirements for using \fImd5sums\fR: md5sums
.IP "index (\s-1FILE\s0)" 4
.IX Item "index (FILE)"
Returns a path object to \s-1FILE\s0 in the package.  \s-1FILE\s0
must be relative to the root of the unpacked package and must be
without leading slash (or \*(L"./\*(R").  If \s-1FILE\s0 is not in the package, it
returns \f(CW\*(C`undef\*(C'\fR.  If \s-1FILE\s0 is supposed to be a directory, it must be
given with a trailing slash.  Example:
.Sp
.Vb 2
\&  my $file = $info\->index ("usr/bin/lintian");
\&  my $dir = $info\->index ("usr/bin/");
.Ve
.Sp
To get a list of entries in the package, see \*(L"sorted_index\*(R".  To
actually access the underlying file (e.g. the contents), use
\&\*(L"unpacked ([\s-1FILE\s0])\*(R".
.Sp
Note that the \*(L"root directory\*(R" (denoted by the empty string) will
always be present, even if the underlying tarball omits it.
.Sp
Needs-Info requirements for using \fIindex\fR: unpacked
.IP "sorted_index" 4
.IX Item "sorted_index"
Returns a sorted array of file names listed in the package.  The names
will not have a leading slash (or \*(L"./\*(R") and can be passed to
\&\*(L"unpacked ([\s-1FILE\s0])\*(R" or \*(L"index (\s-1FILE\s0)\*(R" as is.
.Sp
The array will not contain the entry for the \*(L"root\*(R" of the package.
.Sp
\&\s-1NB:\s0 For source packages, please see the
\&\*(L"index\*(R"\-caveat.
.Sp
Needs-Info requirements for using \fIsorted_index\fR: Same as index
.IP "index_resolved_path(\s-1PATH\s0)" 4
.IX Item "index_resolved_path(PATH)"
Resolve \s-1PATH\s0 (relative to the root of the package) and return the
entry denoting the resolved path.
.Sp
The resolution is done using
resolve_path.
.Sp
\&\s-1NB:\s0 For source packages, please see the
\&\*(L"index\*(R"\-caveat.
.Sp
Needs-Info requirements for using \fIindex_resolved_path\fR: Same as index
.SH "AUTHOR"
.IX Header "AUTHOR"
Originally written by Niels Thykier <niels@thykier.net> for Lintian.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBlintian\fR\|(1), Lintian::Collect, Lintian::Collect::Binary,
Lintian::Collect::Source