SBO::Lib::Util(3)

NAME
SBO::Lib::Util - Utility functions for SBO::Lib and the sbotools.

SYNOPSIS
  use SBO::Lib::Util qw/uniq/;

  # ('duplicate');
  my @uniq = uniq('duplicate', 'duplicate');

VARIABLES

  $anticipated_next
The anticipated Slackware version number to be supported by SBO, currently 15.1.

  $arch
The kernel architecture, accounting for "i?86" userlands reporting a "x86_64" kernel.

  ($color_default, $color_lesser, $color_notice, $color_warn)
These variables are ANSI colors. $color_notice is "cyan" for selected "sbotools" informative messages. $color_lesser is "bold" for warnings of lesser concern. $color_warn, "red bold", is for errors and warnings of greater concern. "sbotools" color display can be disabled by setting "NOCOLOR" to "FALSE". $color_default is currently "reset" and is not configurable.

get_colors() reads "/etc/sbotools/sbotools.colors" for custom values.

  $conf_dir
$conf_dir is "/etc/sbotools" by default, or else the contents of an environment variable "SBOTOOLS_CONF_DIR".

  $conf_file
$conf_file is "/etc/sbotools/sbotools.conf" by default.

  %config
All values default to "FALSE", but when read_config() is run, they change according to the configuration. "SBO_HOME" is changed to "/var/lib/sbotools" if still "FALSE".

The supported keys are: "NOCLEAN", "DISTCLEAN", "JOBS", "PKG_DIR", "SBO_HOME", "LOCAL_OVERRIDES", "SLACKWARE_VERSION", "REPO", "BUILD_IGNORE", "GPG_VERIFY", "RSYNC_DEFAULT", "STRICT_UPGRADES", "GIT_BRANCH", "CLASSIC", "CPAN_IGNORE", "ETC_PROFILE", "LOG_DIR", "NOWRAP", "NOCOLOR", "NO_SOCHECK", "DIALOGRC", "NONET", "FORCE_OBSOLETE", "INSTANT_STOP", "NICENESS" and "IDLE_BUILD".

  $current_cols
The number of columns in the terminal. It is always equal to 0 if the "cols" terminal capability is not available. Except for the initial call, use tput_update() to set the value; using tput(1) directly outside of the sbotool(1) context can otherwise introduce lag.

  $distfiles_dir
$distfiles_dir defaults to "/var/lib/sbotools/distfiles", and it is where all downloaded sources are kept.

  $download_time
The time spent downloading source files. Unless "CLASSIC" is "TRUE", it is displayed when all builds are complete.

  ($has_cols, $has_clear, $has_lines)
These shared variables are true if the running terminal has the "cols", "clear" and "lines" capabilities, respectively. Realistically speaking, this means every remotely modern terminal, unless $TERM has been set incorrectly.

  $hint_file
A file, "/etc/sbotools/sbotools.hints" by default, containing blacklisted scripts, optional script dependencies and automatic revese dependency rebuild requests.

  ($is_sbotest, $is_sbotool)
This shared variable indicate runs from sbotest(1) and sbotool(1), respectively.

  $sbotest_compatible
This shared variable indicates compatibility with the sbotest(1) companion package.

  $total_build_time
A running total of the time it took to build and package each script in the queue. Unless "CLASSIC" is "TRUE", it is displayed when all builds are complete.

  $total_install_time
A running total of the time it took to install each script in the queue. Unless "CLASSIC" is "TRUE", it is displayed when all builds are complete.

  ($paused_time, $resume_time, $stop_time)
These variables are used to track any time spent stopped by keyboard interrupt. Times are adjusted in the reconcile_time() subroutine before reporting.

  @listings
An array with blacklisted scripts and requests for optional dependencies, ignoring test failures and automatic reverse dependency rebuilds read in from "/etc/sbotools/sbotools.hints".

  (@on_blacklist, @auto_reverse, %optional, @ignore_tests)
These exported variables are populated by read_hints() and used to determine hint status.

  ($manual_dir, $manual_link)
The manual download directory at "SBO_HOME/distfiles/manual" and its symlink at "SBO_HOME/manual_downloads", respectively.

  $obs_file
This file contains a list of scripts that have been renamed and added to Slackware -current, or are known to be obsolete build dependencies. It is located at "/etc/sbotools/obsolete" by default.

  @obsolete
This array is based on the contents of $obs_file.

  $perl_file
This file contains build timestamps for the introduction of major perl versions into Slackware. It is used by "Solibs.pm" during the "perl" package test. It is located at "/etc/sbotools/perl_vers" by default.

  $userland_32
get_arch() defines this variable when running in a 32-bit userland on a 64-bit kernel.

  $stage_dir
$stage_dir is a temporary directory under "SBO_HOME/distiles". When a script is to be built, a new temporary directory is created, the SlackBuild directory is copied there and any downloaded sources are hardlinked in.

SUBROUTINES

  auto_reverse
  my $result = auto_reverse($sbo)

auto_reverse() checks whether automatic reverse dependency rebuilding for $sbo has been requested. Results will be the same for the "compat32" version of the script.

  build_cmp
  my $cmp = build_cmp($build1, $build2, $ver1, $ver2);

build_cmp() compares $build1 with $build2 while checking that $ver1 and $ver2 are different. If the build numbers are not the same and the version numbers are, upgrading for a script bump may be in order.

  check_distfiles_dir
  my $bool = check_distfiles_dir();

check_distfiles_dir() checks for the existence of the "distfiles" directory and the "manual downloads" directory and convenience symlink. It creates them if necessary. The script exits if "SBO_HOME/distfiles" is an existing non-directory, if "SBO_HOME/distfiles/manual" is an existing non-directory or a symlink, if "SBO_HOME/manual_downloads" is anything other than a correct symlink, or if partitions are mounted in subdirectories of "SBO_HOME/distfiles". If "SBO_HOME/distfiles" is a symlink, it must point to an existing directory.

check_distfiles_dir() returns 1 on success.

  check_multilib
  my $ml = check_multilib();

check_multilib() verifies "/etc/profile.d/32dev.sh" existence. The sbotools use this file to build 32-bit packages on x64 architecture.

Returns 1 if the file exists, and 0 otherwise.

  dangerous_directory
  my $dangerous = dangerous_directory($dirname);

dangerous_directory() takes a string and returns true if it is equal to "/", "/root", "/home" or a possible top-level directory under "/home". Paths under "SBO_HOME/distfiles" and $manual_link are also disallowed. This process accounts for symlinks.

  display_times
  display_times();

display_times() shows the time spent downloading, packaging and installing the scripts in the build queue. It takes no arguments and has no useful return value.

  error_code
  error_code($message, $code);

error_code() takes a message and an error code. The message is displayed wrapped at 72 characters and the script exits with the specified error code. There is no useful return value.

dialog(1) displays the message when running "sbotool".

For "_ERR_USAGE" and "_ERR_SCRIPT", use usage_error() and script_error(), respectively.

  get_arch
  my $arch = get_arch();

get_arch() returns the machine architechture as reported by "uname -m". For the "x86_64" architecture, additionally check whether "/bin/bash" is 64- or 32-bit to account for 32-bit userlands running on a 64-bit kernel.

"get_arch" is not exported; use the exported variable $arch if it is necessary to check for architecture.

  get_colors
  my ($color_notice, $color_lesser, $color_warn) = get_colors();

get_colors() reads the contents of "/etc/sbotools/sbotools.colors" to set custom values for $color_notice, $color_lesser and $color_warn. No color can be set to an invalid ANSI specification; in such cases, the default value is used instead. See Term::ANSIColor(3) for details.

  get_kernel_version
  my $kv = get_kernel_version();

get_kernel_version() checks the version of the running kernel and returns it in a format suitable for appending to a Slackware package version.

  get_optional
  my $optional = get_optional($sbo)

get_optional() checks for user-requested optional dependencies for $sbo. In all cases, results for "compat32" scripts have the corresponding "compat32" scripts to the results for the base script.

  get_sbo_from_loc
  my $sbo = get_sbo_from_loc($location);

get_sbo_from_loc() returns the package name from the $location passed in.

  get_slack_branch
  my $url = get_slack_branch();

get_slack_branch() returns the default git branch for the given Slackware version, if any. If the upstream repository does not have this branch, an onscreen message appears.

  get_slack_version
  my $version = get_slack_version();

get_slack_version() returns the appropriate version of the SBo reposiotry.

The program exits if the version is unsupported or if an error occurs.

  get_slack_version_url
  my $url = get_slack_version_url();

get_slack_version_url() returns the default URL for the given Slackware version.

The program exits if the version is unsupported or if an error occurs.

  idx
  my $idx = idx($needle, @haystack);

idx() looks for $needle in @haystack, and returns the index of where it was found, or "undef" if it was not found.

  ignore_tests
  my $result = ignore_tests($sbo)

ignore_tests() checks whether test failures for $sbo are to be ignored by sboupgrade(1). Results will be the same for the "compat32" version of the script.

  in
  my $found = in($needle, @haystack);

in() looks for $needle in @haystack, and returns a true value if it was found, and a false value otherwise.

in() formerly matched "Regexp", but this was changed for performance reasons. Use in_regexp() for the old functionality.

  indent
  my $str = indent($indent, $text);

indent() indents every non-empty line in $text by $indent spaces and returns the resulting string.

  is_obsolete
  my $is_obsolete = is_obsolete($sbo);

is_obsolete() takes the name of a SlackBuild and searches for it in the @obsolete array. It returns true if the SlackBuild is found and the Slackware version is -current equivalent.

  lint_sbo_config
  lint_sbo_config($running_script, %configs);

lint_sbo_config() takes the name of an sbotools script and a hash with configuration parameters. It checks the validity of all parameters except for REPO, exiting with an error message in case of invalid options.

sboconfig(1) runs this subroutine to lint any requested parameter changes; all other scripts lint the full configuration at startup.

  merge_obsolete
  merge_obsolete();

merge_obsolete() appends the contents of the @obsolete array to the blacklist, provided that the "FORCE_OBSOLETE" setting is "TRUE". It has no useful return value. It is currently called in sboinstall(1), sboupgrade(1) and sbofind(1).

  obsolete_array
  our @obsolete = obsolete_array();

obsolete_array() populates the shared @obsolete array based on the "/etc/sbotools/obsolete" file on Slackware -current.

  on_blacklist
  my $result = on_blacklist($sbo);

on_blacklist() checks whether $sbo has been blacklisted. Results will be the same for the "compat32" version of the script.

  open_fh
  my ($ret, $exit) = open_fh($fn, $op);

open_fh() opens $fn for reading and/or writing depending on $op (e.g., ">" or "<").

It returns two values: the file handle and the exit status. If the exit status is non-zero, it returns an error message rather than a file handle.

  open_read
  my ($ret, $exit) = open_read($fn);

open_read() opens $fn for reading.

It returns two values: the file handle and the exit status. If the exit status is non-zero, it returns an error message rather than a file handle.

  print_color
  print_color "red bold";

print_color() takes one or more ANSI colors and prints, provided that the "NOCOLOR" setting is not "TRUE". See the "Function Interface" section in Term::ANSIColor(3) for a list of available colors.

Using colors "black" through "bright_white", "bold" and "reset" only is advisable to ensure terminal compatibility. When calling print_color() before exiting, ensure that a new line follows to avoid an improper cursor on some terminals.

There is no useful return value.

  print_failures
  print_failures($failures);

print_failures() prints all failures in the $failures array reference to STDERR, if any.

There is no useful return value.

  prompt
  exit unless prompt $color_notice, "Should we continue?", default => "yes";

prompt() prompts the user for an answer, optionally specifying a default of "yes" or "no".

If the default has been specified, it returns a true value for 'yes' and a false one for 'no'. Otherwise, it returns the content of the user's answer.

Output is wrapped at 72 characters.

  read_config
  read_config();

read_config() reads in the configuration settings from "/etc/sbotools/sbotools.conf", updating the %config hash. If "SBO_HOME" is "FALSE", it changes to "/var/lib/sbotools". Additionally, "BUILD_IGNORE", "RSYNC_DEFAULT" and "NOCOLOR" are turned on if "CLASSIC" is "TRUE".

When "sbotest" is running, the default value of "SBO_HOME" is "/var/lib/sbotest", and "ETC_PROFILE" and "CPAN_IGNORE" default to "TRUE". Supplementary setting "SBO_ARCHIVE" defaults to "/var/lib/sbotest/archive". "PKG_DIR" and "LOG_DIR" default to "/var/lib/sbotest/tests" and "/var/lib/sbotest/logs", respectively, but "sbotest" uses timestamped directories under the configured paths.

There is no useful return value.

  read_ionice
  my @ionice = read_ionice();

read_ionice() parses ionice(1) output and returns an array with the current "class" and "prioritiy level" for the running script. The script exits if proper values cannot be parsed.

  read_hints
  our @listings = read_hints();

read_hints() reads the contents of "/etc/sbotools/sbotools.hints", returning an array of potentially valid lines in "/etc/sbotools/sbotools.hints". read_hints() is used to populate global array @listings, and should only be called at the start and again when editing the hints file.

@on_blacklist, @auto_reverse, %optional and @ignore_tests are populated here and used by on_blacklist(), auto_reverse(), get_optional() and "ignore_tests" later.

  reconcile_time
  my $corrected_seconds = reconcile_time($seconds);

reconcile_time() takes a duration in seconds (integer or otherwise) and subtracts any time spent stopped from keyboard signal. It returns the corrected number of seconds.

  save_options
  save_options($sbo, $opts)

save_options() saves build options to "/var/log/sbotools/sbo". For "compat32" packages, the file for the base script is used. If the file already exists and the user supplies no build options, the existing file is retained.

  script_error
  script_error();
  script_error($msg);

script_error() warns and exits with code "_ERR_SCRIPT", printing the following to STDERR:

  A fatal script error has occurred. Exiting.

If a $msg was supplied, it instead prints:

  A fatal script error has occurred:
  $msg.
  Exiting.

dialog(1) displays $msg when running "sbotools".

There is no useful return value. For "_ERR_USAGE", use usage_error(). For other error codes, use error_code().

  set_ionice
  set_ionice($class, $level);

set_ionice() takes an array with an ionice(1) class and level, and runs the appropriate command to set the IO priority levels to those settings for the running script. The script exits if invalid ionice(1) settings are passed. There is no useful return value.

  show_version
  show_version();

show_version() prints the sbotools version and licensing information to STDOUT.

There is no useful return value.

  slurp
  my $data = slurp($fn);

slurp() takes a filename in $fn, opens it, and reads in the entire file. The contents are then returned. On error, it returns "undef".

  time_format
  my $time_string = time_format($time);

time_format() takes a number of seconds (integer or otherwise) and returns a string H:MM:SS.

  tput_update
  tput_update();

tput_update() updates the number of columns in the terminal using tput(1), provided that the "cols" capability is available and the terminal has been resized since the last update.

  uniq
  my @uniq = uniq(@duplicates);

uniq() removes any duplicates from @duplicates, otherwise returning the list in the same order.

  usage_error
  usage_error($msg);

usage_error() warns and exits with code "_ERR_USAGE", printing $msg to STDERR. Error messages wrap at 72 characters.

dialog(1) displays $msg when running "sbotools".

There is no useful return value. For "_ERR_SCRIPT", use script_error(); for other error codes, use error_code().

  version_cmp
  my $cmp = version_cmp($ver1, $ver2);

version_cmp() compares $ver1 with $ver2. It returns 1 if $ver1 is higher, -1 if $ver2 is higher and 0 if they are equal. It strips the running kernel version, as well as any locale information that may have been appended to the version strings.

This subroutine is a wrapper for "Sort::Versions", which is bundled under "SBO::ThirdParty".

  warn_color
  warn_color($color, $msg);

warn_color() emits a warning in the chosen color and resets the color afterwards. No colors are used unless "NOCOLOR" is "FALSE". A newline is added automatically after the message. There is no useful return value.

  wrapsay
  wrapsay($msg, $trail);

wrapsay() outputs a message with the lines wrapped at 72 characters and a trailing newline. Messages are not wrapped if the running terminal is too narrow than the wrap width. There is no useful return value. Optional $trail outputs an extra newline if present.

Use this subroutine whenever it is either obvious that the output exceeds 80 characters or the output includes a variable. "say" can be used in other cases. wrapsay() should not be used on output that can be piped for use in scripts (e.g., queue reports from sbofind(1)).

  wrapsay_color
  wrapsay_color($color, $msg, $trail);

wrapsay_color() takes a color, a message and any true value if a trailing line is required. It applies a color, prints a wrapped message at 72 characters and resets the color at the end of the line. No colors are used unless "NOCOLOR" is "FALSE"; please note that print_color() checks the configuration value. Messages are not wrapped if the terminal is too narrow. There is no useful return value.

EXIT CODES
The sbotools share the following exit codes:

  _ERR_USAGE         1   usage errors
  _ERR_SCRIPT        2   script or module bug
  _ERR_BUILD         3   errors when executing a SlackBuild
  _ERR_MD5SUM        4   download verification failure
  _ERR_DOWNLOAD      5   download failure
  _ERR_OPENFH        6   failure to open file handles
  _ERR_NOINFO        7   missing download information
  _ERR_F_SETD        8   fd-related temporary file failure
  _ERR_NOMULTILIB    9   lacking multilib capabilities when needed
  _ERR_CONVERTPKG    10  convertpkg-compat32 failure
  _ERR_NOCONVERTPKG  11  lacking convertpkg-compat32 when needed
  _ERR_INST_SIGNAL   12  the script was interrupted while building
  _ERR_CIRCULAR      13  attempted to calculate a circular dependency
  _ERR_USR_GRP       14  a required user or group is missing
  _ERR_GPG           15  GPG verification failed
  _ERR_STDIN         16  reading keyboard input failed
  _ERR_SBO_HOME      17  could not give SBO_HOME valid contents
  _ERR_TPUT          18  needed terminal capabilities absent

SEE ALSO
SBO::Lib(3), SBO::Lib::Build(3), SBO::Lib::Download(3), SBO::Lib::Info(3), SBO::Lib::Pkgs(3), SBO::Lib::Readme(3), SBO::Lib::Repo(3), SBO::Lib::Tree(3), dialog(1), ionice(1), Term::ANSIColor(3)

AUTHORS
SBO::Lib was originally written by Jacob Pipkin <jacob.pipkin@icloud.com> with contributions from Luke Williams <xocel@iquidus.org> and Andreas Guldstrand <andreas.guldstrand@gmail.com>.

MAINTAINER
SBO::Lib is maintained by K. Eugene Carlson <kvngncrlsn@gmail.com>.

LICENSE
The sbotools are licensed under the MIT License.

Copyright (C) 2012-2017, Jacob Pipkin, Luke Williams, Andreas Guldstrand.

Copyright (C) 2024-2026, K. Eugene Carlson.

Copyright (C) 2026, K. Eugene Carlson, Jacob Pipkin.