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)