Provided by: lintian_2.5.81ubuntu1_all bug

NAME

       Lintian::Path - Lintian representation of a path entry in a package

SYNOPSIS

           my ($name, $type, $dir) = ('lintian', 'source', '/path/to/entry');
           my $info = Lintian::Collect->new ($name, $type, $dir);
           my $path = $info->index('bin/ls');
           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 'root') { }
              if ($path->group eq 'root') { }
           } 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...
                  }
              }
           }

INSTANCE METHODS

       Lintian::Path->new ($data)
           Internal constructor (used by Lintian::Collect::Package).

           Argument is a hash containing the data read from the index file.

       name
           Returns the name of the file (relative to the package root).

           NB: It will never have any leading "./" (or "/") in it.

       owner
           Returns the owner of the path entry as a username.

           NB: If only numerical owner information is available in the package, this may return a
           numerical owner (except uid 0 is always mapped to "root")

       group
           Returns the group of the path entry as a username.

           NB: If only numerical owner information is available in the package, this may return a
           numerical group (except gid 0 is always mapped to "root")

       uid Returns the uid of the owner of the path entry.

           NB: 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)

       gid Returns the gid of the owner of the path entry.

           NB: 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)

       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.

           If this is not a link, then this returns undef.

           If the path is a symlink this method can be used to determine if the symlink is
           relative or absolute.  This is not true for hardlinks, where the link target is always
           relative to the root.

           NB: Even for symlinks, a leading "./" will be stripped.

       size
           Returns the size of the path in bytes.

           NB: Only regular files can have a non-zero file size.

       date
           Return the modification date as YYYY-MM-DD.

       parent_dir
           Returns the parent directory entry of this entry as a Lintian::Path.

           NB: Returns "undef" for the "root" dir.

       dirname
           Returns the "directory" part of the name, similar to dirname(1) or
           File::Basename::dirname.  The dirname will end with a trailing slash (except the
           "root" dir - see below).

           NB: Returns the empty string for the "root" dir.

       basename
           Returns the "filename" part of the name, similar basename(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 "root" dir - see
           below).

           NB: Returns the empty string for the "root" dir.

       faux
           Returns a truth value if this entry absent in the package.  This can happen if a
           package does not include all intermediate directories.

       operm
           Returns the file permissions of this object in octal (e.g. 0644).

           NB: 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.

       children([RECURSIVE_MODE])
           Returns a list of children (as Lintian::Path objects) of this entry.  The list and its
           contents should not be modified.

           The optional RECURSIVE_MODE parameter can be used to control if and how descendants of
           this directory is selected.  The following values are supported:

           direct
               This is the default and only returns direct children of this directory.  The
               entries are sorted by name.

           breadth-first
               Recursive into subdirectories and return the descendants in breadth-first order.
               Children of a given directory will be sorted by name.

           NB: Returns the empty list for non-dir entries.

       timestamp
           Returns a Unix timestamp for the given path. This is a number of seconds since the
           start of Unix epoch in UTC.

       child(BASENAME)
           Returns the child named BASENAME if it is a child of this directory.  Otherwise, this
           method returns "undef".  Note if BASENAME has a trailing slash, the child entry must
           be a directory.  If the child exist, but is not a directory, "undef" will be returned
           instead.

           For non-dirs, this method always returns "undef".

           Example:

             $dir_entry->child('foo') => $entry OR undef

             $dir_entry->child('foo/') => $dir_entry OR undef

       is_symlink
           Returns a truth value if this entry is a symlink.

       is_hardlink
           Returns a truth value if this entry is a hardlink to a regular file.

           NB: The target of a hardlink is always a regular file (and not a dir etc.).

       is_dir
           Returns a truth value if this entry is a dir.

           NB: Unlike the "-d $dir" operator this will never return true for symlinks, even if
           the symlink points to a dir.

       is_file
           Returns a truth value if this entry is a regular file (or a hardlink to one).

           NB: Unlike the "-f $file" operator this will never return true for symlinks, even if
           the symlink points to a file (or hardlink).

       is_regular_file
           Returns a truth value if this entry is a regular file.

           This is eqv. to $path->is_file and not $path->is_hardlink.

           NB: Unlike the "-f $file" operator this will never return true for symlinks, even if
           the symlink points to a file.

       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 "undef".

           NB: This method will return the empty string for links pointing to the root dir of the
           package.

           Only available on "links" (i.e. symlinks or hardlinks).  On non-links this will croak.

           Symlinks only: If you want the symlink target as a Lintian::Path object, use the
           resolve_path method with no arguments instead.

       is_readable
           Returns a truth value if the permission bits of this entry have at least one bit
           denoting readability set (bitmask 0444).

       is_writable
           Returns a truth value if the permission bits of this entry have at least one bit
           denoting writability set (bitmask 0222).

       is_executable
           Returns a truth value if the permission bits of this entry have at least one bit
           denoting executability set (bitmask 0111).

       file_info
           Return the data from file(1) if it has been collected.

           Note this is only defined for files as Lintian only runs file(1) on files.

       fs_path
           Returns the path to this object on the file system, which must be a regular file, a
           hardlink or a directory.

           This method may fail if:

           •   The object is neither a directory or a file-like object (e.g. a named pipe).

           •   If the object is dangling symlink or the path traverses a symlink outside the
               package root.

           To test if this is safe to call, if the target is (supposed) to be a:

           •   file or hardlink then test with "is_open_ok".

           •   dir then assert resolve_path returns a defined entry, for which "is_dir" returns a
               truth value.

       is_open_ok
           Returns a truth value if it is safe to attempt open a read handle to the underlying
           file object.

           Returns a truth value if the path may be opened.

       open([LAYER])
           Open and return a read handle to the file.  It optionally accepts the LAYER argument.
           If given it should specify the layer/discipline to use when opening the file including
           the initial colon (e.g. ':raw').

           Beyond regular issues with opening a file, this method may fail if:

           •   The object is not a file-like object (e.g. a directory or a named pipe).

           •   If the object is dangling symlink or the path traverses a symlink outside the
               package root.

           It is possible to test for these by using "is_open_ok".

       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 "open([LAYER])".

           The returned handle may be a pipe from an external process.

       file_contents
           Return the file contents as a scalar.

           This method may fail for the same reasons as "open([LAYER])".

       root_dir
           Return the root dir entry of this the path entry.

       resolve_path([PATH])
           Resolve PATH relative to this path entry.

           If PATH starts with a slash and the file hierarchy has a well-defined root directory,
           then PATH 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 "undef".

           If PATH 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.  NB: hardlinks
           also resolve as themselves.

           It is an error to attempt to resolve a PATH 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).

           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 "undef".  Otherwise, it returns the path entry that denotes the target path.

           If PATH 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 PATH can end in any
           entry except a symlink.

           Examples:

             $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('some/../where') => $nonsymlink_entry OR undef

             # Note the trailing slash
             $dol_entry->resolve_path('some/../where/') => $dir_entry OR undef

AUTHOR

       Originally written by Niels Thykier <niels@thykier.net> for Lintian.

SEE ALSO

       lintian(1), Lintian::Collect(3), Lintian::Collect::Binary(3), Lintian::Collect::Source(3)