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)

Lintian v2.117.0ubuntu1.3                          2025-05-02                                   Lintian::Util(3)