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.