Lintian::Index::Item(3)

💖 Lintian::Index::Item — the manual page, but make it cute ✨

okay so bestie, quick vibe check: this is Lintian::Index::Item(3), straight outta the Debian Package Checker manual set 🎀 she's a Perl module, she lives in section 3 (that's the "library functions" section, iykyk), and she's literally the thing that keeps track of one single path entry inside a package. one entry. that's her whole job. iconic behavior honestly 👑

---

🌸 NAME 🌸

Lintian::Index::Item — it's Lintian's own lil representation of a path entry in a package 🦋

like. every file, every directory that lives inside a package? Lintian wants a whole object for it. this is that object. she's a data girlie and she ate 💅

---

✨ SYNOPSIS ✨

okay so here's the whole entire vibe, look how tiny she is:

my ($name, $type, $dir) = ('lintian', 'source', '/path/to/entry');

that's it. that's the whole snip. $name gets 'lintian', $type gets 'source', and $dir gets '/path/to/entry' — those are placeholders bestie, you swap in your own actual values, don't copy-paste them literally and then come crying to me 😭

---

more to come, don't go anywhere 💖

✨ INSTANCE METHODS ✨

okay bestie, this is the main character section right here — every method this object gives you. let's go 💅

• init_from_tar_output
• get_quoted_filename
• unescape_c_style
• bytes_match(REGEX) — returns the matched string if REGEX matches the file's byte contents, or $EMPTY otherwise. no match, no vibes. 💀
• mentions_in_operation(REGEX) — returns the matched string if REGEX matches somewhere in a file location that's likely an actual operation (as opposed to just text), or $EMPTY otherwise. context matters, periodt.
• magic(COUNT) — returns the specified COUNT of magic bytes for the file. ✨
• "hashbang" — returns the "hashbang" for the file if it's a script. she's got a shebang and she's not afraid to show it.
• interpreter_with_options — returns the interpreter the script requested, options included, after stripping "env". lowkey thorough.
• interpreter — returns the interpreter the script requested, with "env" stripped out.
• "calls_env" — returns true if the file is a script that calls "env". iykyk.
• "is_shell_script" — returns true if the file is a script asking for a recognized shell interpreter. 🐚
• is_elf — returns true if the file is an ELF executable, false otherwise.
• is_script — true if it's a script, false if it isn't. simple as that.
• is_maintainer_script — true if it's a maintainer script, false otherwise.
• identity — returns the owner and group of the path, separated by a slash.

NB: if only numerical owner info is available in the package, this may return a numerical owner (except uid 0 is always mapped to "root"). no cap.

• 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. don't come for me, that's just how it is. 🙈

• octal_permissions
• children — returns a list of children (as Lintian::File::Path objects) of this entry. the list and its contents should not be modified, bestie, hands off 🫶

only returns direct children of this directory. the entries are sorted by name.

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

• descendants — returns a list of children (as Lintian::File::Path objects) of this entry. again: the list and its contents should not be modified.

descends recursively into subdirectories and returns the descendants in breadth-first order. children of a given directory will be sorted by name. it's giving organized. ✨

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

• timestamp — returns a Unix timestamp for the given path. that's a number of seconds since the start of the Unix epoch in UTC. ⏰
• child(BASENAME) — returns the child named BASENAME if it's a child of this directory. otherwise, this method returns "undef".

even for directories, BASENAME should not end with a slash.

when invoked on non-dirs, this method always returns "undef".

example:

$dir_entry->child('foo') => $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 its directory name. if the link can't be normalized, or the normalized path might escape the package root, this method returns "undef". no sneaking out the back door 🚪

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::File::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). 🔥
• all_bits_set
• is_setuid
• is_setgid
• unpacked_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 a 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's safe to attempt opening a read handle to the underlying file object.

returns a truth value if the path may be opened.

• follow — return the dereferenced link if applicable. 🔎
• 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's 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). yeah, don't do that. 🛑

the resolution takes symlinks into account and follows them provided 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

• name — returns the name of the file (relative to the package root).

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

• basename — returns the "filename" part of the name, similar to basename(1) or File::Basename::basename (without passing a suffix to strip in either case).

NB: returns the empty string 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.

• 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.

• normalized
• faux — returns a truth value if this entry is absent in the package. this can happen if a package doesn't include all intermediate directories. she's faux, she's not really there 💅
• 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. 📅
• time
• perm
• path_info
• 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).

• file_type — return the data from file(1) if it's been collected.

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

• java_info
• strings
• "basedir"
• index
• parent_dir
• child_table
• sorted_children — returns the parent directory entry of this entry as a Lintian::File::Path.

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

• "childnames"
• parent_dir — return the parent dir entry of this the path entry.
• dereferenced
• elf
• elf_by_member
• pointer
• bytes — returns verbatim file contents as a scalar. ✨
• is_valid_utf8 — boolean true if file contents are valid UTF-8. 🌈
• decoded_utf8 — returns a decoded, wide-character string if file contents are valid UTF-8.

---

💖 AUTHOR 💖

Originally written by Niels Thykier <niels@thykier.net> for Lintian. king behaviour, honestly 👑

---

🌈 SEE ALSO 🌈

• lintian(1)

---

and that's the whole page, bestie, you ate it up 🎀 this little masterpiece is from Lintian version v2.139.0ubuntu2, dated 2026-10-08, and it's the Lintian::Index::Item(3) man page — go forth and inspect some files, you've got this 🦋💜