Lintian::Util

NAME

Lintian::Util - Lintian utility functions

SYNOPSIS

use Lintian::Util;

DESCRIPTION

This module contains a number of utility subs that are nice to have, but on their own did not warrant their own module.

Most subs are imported only on request.

VARIABLES

$PKGNAME_REGEX

Regular expression that matches valid package names. The expression is not anchored and does not enforce any "boundary" characters.

$PKGREPACK_REGEX

Regular expression that matches "repacked" package names. The expression is not anchored and does not enforce any "boundary" characters. It should only be applied to the upstream portion (see #931846).

$PKGVERSION_REGEX

Regular expression that matches valid package versions. The expression is not anchored and does not enforce any "boundary" characters.

FUNCTIONS

drain_pipe( FD )

Reads and discards any remaining contents from FD, which is assumed to be a pipe. This is mostly done to avoid having the "write"-end die with a SIGPIPE due to a "broken pipe" (which can happen if you just close the pipe).

May cause an exception if there are issues reading from the pipe.

Caveat: This will block until the pipe is closed from the "write"-end, so only use it with pipes where the "write"-end will eventually close their end by themselves (or something else will make them close it).

get_file_digest( ALGO, FILE )

Creates an ALGO digest object that is seeded with the contents of FILE. If you just want the hex digest, please use "get_file_checksum( ALGO, FILE )" instead.

ALGO can be ’md5’ or shaX, where X is any number supported by Digest::SHA (e.g. ’sha256’).

This sub is a convenience wrapper around Digest::{ MD5,SHA }.

get_file_checksum( ALGO, FILE )

Returns a hexadecimal string of the message digest checksum generated by the algorithm ALGO on FILE.

ALGO can be ’md5’ or shaX, where X is any number supported by Digest::SHA (e.g. ’sha256’).

This sub is a convenience wrapper around Digest::{ MD5,SHA }.

perm2oct( PERM )

Translates PERM to an octal permission. PERM should be a string describing the permissions as done by tar t or ls -l. That is, it should be a string like "-rw-r--r--".

If the string does not appear to be a valid permission, it will cause a trappable error.

Examples:

# Good
perm2oct('-rw-r--r--') == oct(644)
perm2oct('-rwxr-xr-x') == oct(755)
# Bad
perm2oct('broken') # too short to be recognised
perm2oct('-resurunet') # contains unknown permissions

human_bytes( SIZE )
locate_executable ( CMD )
drop_relative_prefix( STRING )

Remove an initial ./ from STRING, if present

version_from_changelog
match_glob( $glob, @things_to_test )

Resembles the same semantic as Text::Glob’s match_glob(), but with the proper escaping of Regexp::Wildcards and pre-configured for Lintian’s purpose. No more directly having to access module variables either.

normalize_pkg_path( PATH )

Normalize PATH by removing superfluous path segments. PATH is assumed to be relative the package root. Note that the result will never start nor end with a slash, even if PATH does.

As the name suggests, this is a path "normalization" rather than a true path resolution (for that use Cwd::realpath). Particularly, it assumes none of the path segments are symlinks.

normalize_pkg_path will return "q{}" (i.e. the empty string) if PATH is normalized to the root dir and "undef" if the path cannot be normalized without escaping the package root.

normalize_link_target( CURDIR, LINK_TARGET )

Normalize the path obtained by following a link with LINK_TARGET as its target from CURDIR as the current directory. CURDIR is assumed to be relative to the package root. Note that the result will never start nor end with a slash, even if CURDIR or DEST does.

normalize_pkg_path will return "q{}" (i.e. the empty string) if the target is the root dir and "undef" if the path cannot be normalized without escaping the package root.

CAVEAT : This function is not always sufficient to test if it is safe to open a given symlink. Use "is_ancestor_of(PARENTDIR, PATH)" for that. If you must use this function, remember to check that the target is not a symlink (or if it is, that it can be resolved safely).

is_ancestor_of( PARENTDIR, PATH )

Returns true if and only if PATH is PARENTDIR or a path stored somewhere within PARENTDIR (or its subdirs).

This function will resolve the paths; any failure to resolve the path will cause a trappable error.

read_md5sums
unescape_md5sum_filename
utf8_clean_log
utf8_clean_bytes

SEE ALSO

lintian(1)