.\" 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::Path 3"
.TH Lintian::Path 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::Path \- Lintian representation of a path entry in a package
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&    my ($name, $type, $dir) = (\*(Aqlintian\*(Aq, \*(Aqsource\*(Aq, \*(Aq/path/to/entry\*(Aq);
\&    my $info = Lintian::Collect\->new ($name, $type, $dir);
\&    my $path = $info\->index(\*(Aqbin/ls\*(Aq);
\&    if ($path\->is_file) {
\&       # is file (or hardlink)
\&       if ($path\->is_hardlink) { }
\&       if ($path\->is_regular_file) { }
\&    } elsif ($path\->is_dir) {
\&       # is dir
\&       if ($path\->owner eq \*(Aqroot\*(Aq) { }
\&       if ($path\->group eq \*(Aqroot\*(Aq) { }
\&    } elsif ($path\->is_symlink) {
\&       my $normalized = $path\->link_normalized;
\&       if (defined($normalized)) {
\&           my $more_info = $info\->index($normalized);
\&           if (defined($more_info)) {
\&               # target exists in the package...
\&           }
\&       }
\&    }
.Ve
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
.IP "Lintian::Path\->new ($data)" 4
.IX Item "Lintian::Path->new ($data)"
Internal constructor (used by Lintian::Collect::Package).
.Sp
Argument is a hash containing the data read from the index file.
.IP "name" 4
.IX Item "name"
Returns the name of the file (relative to the package root).
.Sp
\&\s-1NB:\s0 It will never have any leading \*(L"./\*(R" (or \*(L"/\*(R") in it.
.IP "owner" 4
.IX Item "owner"
Returns the owner of the path entry as a username.
.Sp
\&\s-1NB:\s0 If only numerical owner information is available in the package,
this may return a numerical owner (except uid 0 is always mapped to
\&\*(L"root\*(R")
.IP "group" 4
.IX Item "group"
Returns the group of the path entry as a username.
.Sp
\&\s-1NB:\s0 If only numerical owner information is available in the package,
this may return a numerical group (except gid 0 is always mapped to
\&\*(L"root\*(R")
.IP "uid" 4
.IX Item "uid"
Returns the uid of the owner of the path entry.
.Sp
\&\s-1NB:\s0 If the uid is not available, 0 will be returned.
This usually happens if the numerical data is not collected (e.g. in
source packages)
.IP "gid" 4
.IX Item "gid"
Returns the gid of the owner of the path entry.
.Sp
\&\s-1NB:\s0 If the gid is not available, 0 will be returned.
This usually happens if the numerical data is not collected (e.g. in
source packages)
.IP "link" 4
.IX Item "link"
If this is a link (i.e. is_symlink or is_hardlink returns a truth
value), this method returns the target of the link.
.Sp
If this is not a link, then this returns undef.
.Sp
If the path is a symlink this method can be used to determine if the
symlink is relative or absolute.  This is \fInot\fR true for hardlinks,
where the link target is always relative to the root.
.Sp
\&\s-1NB:\s0 Even for symlinks, a leading \*(L"./\*(R" will be stripped.
.IP "size" 4
.IX Item "size"
Returns the size of the path in bytes.
.Sp
\&\s-1NB:\s0 Only regular files can have a non-zero file size.
.IP "date" 4
.IX Item "date"
Return the modification date as YYYY-MM-DD.
.IP "parent_dir" 4
.IX Item "parent_dir"
Returns the parent directory entry of this entry as a
Lintian::Path.
.Sp
\&\s-1NB:\s0 Returns \f(CW\*(C`undef\*(C'\fR for the \*(L"root\*(R" dir.
.IP "dirname" 4
.IX Item "dirname"
Returns the \*(L"directory\*(R" part of the name, similar to \fBdirname\fR\|(1) or
File::Basename::dirname.  The dirname will end with a trailing slash
(except the \*(L"root\*(R" dir \- see below).
.Sp
\&\s-1NB:\s0 Returns the empty string for the \*(L"root\*(R" dir.
.IP "basename" 4
.IX Item "basename"
Returns the \*(L"filename\*(R" part of the name, similar \fBbasename\fR\|(1) or
File::Basename::basename (without passing a suffix to strip in either
case).  For dirs, the basename will end with a trailing slash (except
for the \*(L"root\*(R" dir \- see below).
.Sp
\&\s-1NB:\s0 Returns the empty string for the \*(L"root\*(R" dir.
.IP "faux" 4
.IX Item "faux"
Returns a truth value if this entry absent in the package.  This can
happen if a package does not include all intermediate directories.
.IP "operm" 4
.IX Item "operm"
Returns the file permissions of this object in octal (e.g. 0644).
.Sp
\&\s-1NB:\s0 This is only well defined for file entries that are subject to
permissions (e.g. files).  Particularly, the value is not well defined
for symlinks.
.IP "children([\s-1RECURSIVE_MODE\s0])" 4
.IX Item "children([RECURSIVE_MODE])"
Returns a list of children (as Lintian::Path objects) of this entry.
The list and its contents should not be modified.
.Sp
The optional \s-1RECURSIVE_MODE\s0 parameter can be used to control if and
how descendants of this directory is selected.  The following values
are supported:
.RS 4
.IP "direct" 4
.IX Item "direct"
This is the default and only returns direct children of this
directory.  The entries are sorted by name.
.IP "breadth-first" 4
.IX Item "breadth-first"
Recursive into subdirectories and return the descendants in
breadth-first order.  Children of a given directory will be sorted by
name.
.RE
.RS 4
.Sp
\&\s-1NB:\s0 Returns the empty list for non-dir entries.
.RE
.IP "timestamp" 4
.IX Item "timestamp"
Returns a Unix timestamp for the given path. This is a number of
seconds since the start of Unix epoch in \s-1UTC.\s0
.IP "child(\s-1BASENAME\s0)" 4
.IX Item "child(BASENAME)"
Returns the child named \s-1BASENAME\s0 if it is a child of this directory.
Otherwise, this method returns \f(CW\*(C`undef\*(C'\fR.  Note if \s-1BASENAME\s0 has a
trailing slash, the child entry must be a directory.  If the child
exist, but is not a directory, \f(CW\*(C`undef\*(C'\fR will be returned instead.
.Sp
For non-dirs, this method always returns \f(CW\*(C`undef\*(C'\fR.
.Sp
Example:
.Sp
.Vb 1
\&  $dir_entry\->child(\*(Aqfoo\*(Aq) => $entry OR undef
\&
\&  $dir_entry\->child(\*(Aqfoo/\*(Aq) => $dir_entry OR undef
.Ve
.IP "is_symlink" 4
.IX Item "is_symlink"
Returns a truth value if this entry is a symlink.
.IP "is_hardlink" 4
.IX Item "is_hardlink"
Returns a truth value if this entry is a hardlink to a regular file.
.Sp
\&\s-1NB:\s0 The target of a hardlink is always a regular file (and not a dir etc.).
.IP "is_dir" 4
.IX Item "is_dir"
Returns a truth value if this entry is a dir.
.Sp
\&\s-1NB:\s0 Unlike the \*(L"\-d \f(CW$dir\fR\*(R" operator this will never return true for
symlinks, even if the symlink points to a dir.
.IP "is_file" 4
.IX Item "is_file"
Returns a truth value if this entry is a regular file (or a hardlink to one).
.Sp
\&\s-1NB:\s0 Unlike the \*(L"\-f \f(CW$file\fR\*(R" operator this will never return true for
symlinks, even if the symlink points to a file (or hardlink).
.IP "is_regular_file" 4
.IX Item "is_regular_file"
Returns a truth value if this entry is a regular file.
.Sp
This is eqv. to \f(CW$path\fR\->is_file and not \f(CW$path\fR\->is_hardlink.
.Sp
\&\s-1NB:\s0 Unlike the \*(L"\-f \f(CW$file\fR\*(R" operator this will never return true for
symlinks, even if the symlink points to a file.
.IP "link_normalized" 4
.IX Item "link_normalized"
Returns the target of the link normalized against it's directory name.
If the link cannot be normalized or normalized path might escape the
package root, this method returns \f(CW\*(C`undef\*(C'\fR.
.Sp
\&\s-1NB:\s0 This method will return the empty string for links pointing to the
root dir of the package.
.Sp
Only available on \*(L"links\*(R" (i.e. symlinks or hardlinks).  On non-links
this will croak.
.Sp
\&\fISymlinks only\fR: If you want the symlink target as a Lintian::Path
object, use the resolve_path method with no
arguments instead.
.IP "is_readable" 4
.IX Item "is_readable"
Returns a truth value if the permission bits of this entry have
at least one bit denoting readability set (bitmask 0444).
.IP "is_writable" 4
.IX Item "is_writable"
Returns a truth value if the permission bits of this entry have
at least one bit denoting writability set (bitmask 0222).
.IP "is_executable" 4
.IX Item "is_executable"
Returns a truth value if the permission bits of this entry have
at least one bit denoting executability set (bitmask 0111).
.IP "file_info" 4
.IX Item "file_info"
Return the data from \fBfile\fR\|(1) if it has been collected.
.Sp
Note this is only defined for files as Lintian only runs \fBfile\fR\|(1) on
files.
.IP "fs_path" 4
.IX Item "fs_path"
Returns the path to this object on the file system, which must be a
regular file, a hardlink or a directory.
.Sp
This method may fail if:
.RS 4
.IP "\(bu" 4
The object is neither a directory or a file-like object (e.g. a
named pipe).
.IP "\(bu" 4
If the object is dangling symlink or the path traverses a symlink
outside the package root.
.RE
.RS 4
.Sp
To test if this is safe to call, if the target is (supposed) to be a:
.IP "\(bu" 4
file or hardlink then test with \*(L"is_open_ok\*(R".
.IP "\(bu" 4
dir then assert resolve_path returns a
defined entry, for which \*(L"is_dir\*(R" returns a truth value.
.RE
.RS 4
.RE
.IP "is_open_ok" 4
.IX Item "is_open_ok"
Returns a truth value if it is safe to attempt open a read handle to
the underlying file object.
.Sp
Returns a truth value if the path may be opened.
.IP "open([\s-1LAYER\s0])" 4
.IX Item "open([LAYER])"
Open and return a read handle to the file.  It optionally accepts the
\&\s-1LAYER\s0 argument.  If given it should specify the layer/discipline to
use when opening the file including the initial colon (e.g. ':raw').
.Sp
Beyond regular issues with opening a file, this method may fail if:
.RS 4
.IP "\(bu" 4
The object is not a file-like object (e.g. a directory or a named pipe).
.IP "\(bu" 4
If the object is dangling symlink or the path traverses a symlink
outside the package root.
.RE
.RS 4
.Sp
It is possible to test for these by using \*(L"is_open_ok\*(R".
.RE
.IP "open_gz" 4
.IX Item "open_gz"
Open a read handle to the file and decompress it as a GZip compressed
file.  This method may fail for the same reasons as \*(L"open([\s-1LAYER\s0])\*(R".
.Sp
The returned handle may be a pipe from an external process.
.IP "file_contents" 4
.IX Item "file_contents"
Return the file contents as a scalar.
.Sp
This method may fail for the same reasons as \*(L"open([\s-1LAYER\s0])\*(R".
.IP "root_dir" 4
.IX Item "root_dir"
Return the root dir entry of this the path entry.
.IP "resolve_path([\s-1PATH\s0])" 4
.IX Item "resolve_path([PATH])"
Resolve \s-1PATH\s0 relative to this path entry.
.Sp
If \s-1PATH\s0 starts with a slash and the file hierarchy has a well-defined
root directory, then \s-1PATH\s0 will instead be resolved relatively to the
root dir.  If the file hierarchy does not have a well-defined root dir
(e.g. for source packages), this method will return \f(CW\*(C`undef\*(C'\fR.
.Sp
If \s-1PATH\s0 is omitted, then the entry is resolved and the target is
returned if it is valid.  Except for symlinks, all entries always
resolve to themselves.  \s-1NB:\s0 hardlinks also resolve as themselves.
.Sp
It is an error to attempt to resolve a \s-1PATH\s0 against a non-directory
and non-symlink entry \- as such resolution would always fail
(i.e. foo/../bar is an invalid path unless foo is a directory or a
symlink to a dir).
.Sp
The resolution takes symlinks into account and following them provided
that the target path is valid (and can be followed safely).  If the
path is invalid or circular (symlinks), escapes the root directory or
follows an unsafe symlink, the method returns \f(CW\*(C`undef\*(C'\fR.  Otherwise, it
returns the path entry that denotes the target path.
.Sp
If \s-1PATH\s0 contains at least one path segment and ends with a slash, then
the resolved path will end in a directory (or fail).  Otherwise, the
resolved \s-1PATH\s0 can end in any entry \fIexcept\fR a symlink.
.Sp
Examples:
.Sp
.Vb 1
\&  $symlink_entry\->resolve_path => $nonsymlink_entry OR undef
\&
\&  $x\->resolve_path => $x
\&
\&  For directory or symlink entries (dol), you can also resolve a path:
\&
\&  $dol_entry\->resolve_path(\*(Aqsome/../where\*(Aq) => $nonsymlink_entry OR undef
\&
\&  # Note the trailing slash
\&  $dol_entry\->resolve_path(\*(Aqsome/../where/\*(Aq) => $dir_entry OR undef
.Ve
.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), \fBLintian::Collect\fR\|(3), \fBLintian::Collect::Binary\fR\|(3),
\&\fBLintian::Collect::Source\fR\|(3)