NAME

       Mail::SpamAssassin::Util - utility functions

DESCRIPTION

       A general class for utility functions.  Please use this for functions that stand alone, without requiring
       a $self object, Portability functions especially.

       NOTE: The functions in this module are to be considered private.  Their API may change at any point, and
       it's expected that they'll only be used by other Mail::SpamAssassin modules. (TODO: we should probably
       revisit this if it's useful for plugin development.)

       NOTE: Utility functions should not be changing global variables such as $_, $1, $2, ... $/, etc. unless
       explicitly documented.  If these variables are in use by these functions, they should be localized.

METHODS

       untaint_var($var)
           This sub takes a scalar or a reference to an array, hash, scalar or another reference and recursively
           untaints all its values (and keys if it's a reference to a hash).  It will return the untainted value
           if  requested  but  to  avoid unnecessary copying, the return value should be ignored when working on
           lists.

       is_fqdn_valid($host)
           Check for full hostname / FQDN / DNS name validity.   IP  addresses  must  be  validated  with  other
           functions     like     Constants::IP_ADDRESS.     Does    not    check    for    valid    TLD,    use
           $self->{main}->{registryboundaries}->is_domain_valid() additionally for that.  If $is_ascii given and
           true, skip idn_to_ascii() conversion.

       is_valid_utf8($str)
           The sub returns true if the provided string of octets represents a syntactically valid UTF-8  string,
           otherwise a false is returned.

       idn_to_ascii($domain)
           Given  an  international  domain  name  with  U-labels (UTF-8 or Unicode chars) converts it to ASCII-
           compatible encoding (ACE).  If the argument is in ASCII (or is an invalid IDN), returns it lowercased
           but otherwise unchanged.  The result is always in octets (utf8 flag off) even if the argument was  in
           Unicode characters.

       "exit_status_str($stat, $errno)"
           map  process  termination  status number to an informative string, and append optional message (dual-
           valued errno or a string or a number), returning the resulting string

       "proc_status_ok($exit_status, $errno, @success)"
           check errno to be 0 and a process exit status to be in the list of success  status  codes,  returning
           true if both are ok, and false otherwise.

       parse_rfc822_date($date)
           Parses  an  RFC  2822  formatted  date string and returns a Unix timestamp.  Takes a date to parse as
           input and returns a Unix timestamp (seconds since epoch) if the date  can  be  parsed,  or  undef  on
           failure.

       time_to_rfc822_date($timestamp)
           Converts a Unix timestamp and returns an RFC 2822 formatted date string.

       qp_decode($str)
           Decodes a string that has been encoded using the Quoted-Printable content transfer encoding.

       extract_ipv4_addr_from_string($str)
           Given a string, extract an IPv4 address from it.

       reverse_ip_address($ip)
           Given  a  quad-dotted  IPv4  address  or  an  IPv6 address, reverses the order of its bytes (IPv4) or
           nibbles (IPv6), joins them with dots, producing a string suitable for reverse  DNS  lookups.  Returns
           undef in case of a syntactically invalid IP address.

       first_available_module(@module_list)
           Return  the  name  of  the first module that can be successfully loaded with "require" from the list.
           Returns "undef" if none are available.

           This is used instead of "AnyDBM_File" as follows:

             my $module = Mail::SpamAssassin::Util::first_available_module
                                   (qw(DB_File GDBM_File NDBM_File SDBM_File));
             tie %hash, $module, $path, [... args];

           Note that "SDBM_File" is guaranteed to be present, since it comes with Perl.

       "touch_file($file, $args)"
           Touch or create a file.

           Possible args:

           create_exclusive => 1
             Create a new empty file safely, only if not existing before

       secure_tmpfile()
           Generates a filename for a  temporary  file,  opens  it  exclusively  and  securely,  and  returns  a
           filehandle to the open file (opened O_RDWR) and it filename.

           If it cannot open a file after 20 tries, it returns "undef".

       secure_tmpdir()
           Generates  a  directory  for  temporary  files.   Creates  it  securely  and  returns the path to the
           directory.

           If it cannot create a directory after 20 tries, it returns "undef".

       "compile_regexp($re, $strip_delimiters, $ignore_always_matching)"
           Compiles a regular expression pattern for efficient and safe use within SpamAssassin.

perl v5.40.1                                       2025-08-11                      Mail::SpamAssassin::Util(3pm)