ClamAV::Client(3pm)

💖 ClamAV::Client — the Perl bestie for your clamd virus scanner 💖

okay so literally this is ClamAV::Client, straight out of the User Contributed Perl Documentation corner of town. Manual page name? It's ClamAV::Client(3pm), periodt.

---

✨ VERSION ✨

0.11 — she's got lore, she's been around, she still slays. 🫶

---

🌸 SYNOPSIS 🌸

Creating a scanner client

use ClamAV::Client;

# Try using socket options from clamd.conf, or use default socket:
my $scanner = ClamAV::Client->new();

# Use a local Unix domain socket:
my $scanner = ClamAV::Client->new(
    socket_name     => '/var/run/clamav/clamd.ctl'
);

# Use a TCP socket:
my $scanner = ClamAV::Client->new(
    socket_host     => '127.0.0.1',
    socket_port     => 3310
);

die("ClamAV daemon not alive")
    if not defined($scanner) or not $scanner->ping();

Daemon maintenance

my $version = $scanner->version;
                        # Retrieve the ClamAV version string.

$scanner->reload();     # Reload the malware pattern database.

$scanner->quit();       # Terminates the ClamAV daemon.
$scanner->shutdown();   # Likewise.

Path scanning (lazy)

# Scan a single file or a whole directory structure,
# and stop at the first infected file:
my ($path, $result) = $scanner->scan_path($path);
my ($path, $result) = $scanner->scan_path(
    $path, ClamAV::Client::SCAN_MODE_NORMAL );
my ($path, $result) = $scanner->scan_path(
    $path, ClamAV::Client::SCAN_MODE_RAW );

Path scanning (complete)

# Scan a single file or a whole directory structure,
# and scan all files without stopping at the first infected one:
my %results = $scanner->scan_path_complete($path);
while (my ($path, $result) = each %results) { ... }

Other scanning methods

# Scan a stream, i.e. read from an I/O handle:
my $result = $scanner->scan_stream($handle);

# Scan a scalar value:
my $result = $scanner->scan_scalar(\$value);

---

🦋 DESCRIPTION 🦋

So ClamAV::Client is a class that acts as a client for a ClamAV clamd virus scanner daemon. And bestie, the daemon can live locally or on some remote system, because ClamAV::Client speaks both Unix domain sockets and TCP/IP sockets. The full functionality of the clamd client/server protocol is supported. not a crumb left behind. 💅

🌈 Constructor

Here's the constructor she gives you:

new(%options): RETURNS ClamAV::Client

Makes you a brand new ClamAV::Client object. 🎀 And here's the vibe check on sockets: if you don't specify any socket options, she first tries the socket options from the local clamd.conf configuration file, then she tries the Unix domain socket /var/run/clamav/clamd.ctl, and then finally she tries the TCP/IP socket at 127.0.0.1 on port 3310. But if you explicitly specify either Unix domain or TCP/IP socket options, then only those get used. no backups, no plan B, just your choices. 👑

%options is a list of key/value pairs representing any of the following options:

• socket_name — a scalar holding the absolute name of the local Unix domain socket. Defaults to /var/run/clamav/clamd.ctl.
• socket_host — a scalar holding the name or IP address of the TCP/IP socket. Defaults to 127.0.0.1.
• socket_port — a scalar holding the port number of the TCP/IP socket. Defaults to 3310.

💜 Instance methods

And these are the instance methods she comes with:

🛠️ Daemon maintenance

• ping: RETURNS SCALAR; THROWS ClamAV::Client::Error — returns true ('PONG') if the ClamAV daemon is alive. Otherwise she throws a ClamAV::Client::Error exception. it's giving "are you there bestie" energy. 📞
• version: RETURNS SCALAR; THROWS ClamAV::Client::Error — returns the version string of the ClamAV daemon.
• reload: RETURNS SCALAR; THROWS ClamAV::Client::Error — tells the ClamAV daemon to reload its malware database. Returns true if the reloading succeeds, or throws a ClamAV::Client::Error exception otherwise.
• quit: RETURNS SCALAR; THROWS ClamAV::Client::Error
• shutdown: RETURNS SCALAR; THROWS ClamAV::Client::Error — (yes, both of these 💀) terminates the ClamAV daemon. Returns true if the termination succeeds, or throws a ClamAV::Client::Error exception otherwise.

bestie these two literally end the daemon. this is not a vibe check, this is a goodbye. 😭

🔍 Scanning

• scan_path($path): RETURNS SCALAR, SCALAR; THROWS ClamAV::Client::Error
• scan_path($path, $scan_mode): RETURNS SCALAR, SCALAR; THROWS ClamAV::Client::Error — scans a single file or a whole directory structure, and stops at the first infected file found. The path you pass must be absolute, no shortcuts. You can also specify a scan mode: ClamAV::Client::SCAN_MODE_NORMAL (which is the default) gives you a normal scan (SCAN) with archive support enabled, and ClamAV::Client::SCAN_MODE_RAW gives you a raw scan with archive support disabled.

If an infected file is found, she returns a list of two things: the path of the file, and the name of the malware signature that matched it. If nothing's infected, she returns the originally specified path and undef. lowkey polite of her.

• scan_path_complete($path): RETURNS HASH; THROWS ClamAV::Client::Error — scans a single file or a whole directory structure completely, and does not stop at the first infected file found. So like, all of them. every last one. 👑 The path you pass must be absolute again. And heads up: only the normal, non-raw mode is supported for complete scans by ClamAV — no raw mode for this one, she said no.

Returns a hash with the list of infected files found: the file paths are the keys and the matched malware signature names are the values.

• scan_stream($handle): RETURNS SCALAR; THROWS ClamAV::Client::Error — scans a stream, i.e. she reads from an I/O handle. If the stream turns out to be infected, she returns the name of the matching malware signature, and undef otherwise.
• scan_scalar(\$value): RETURNS SCALAR; THROWS ClamAV::Client::Error — scans the value referenced by the scalarref you handed her. If that value is infected, she returns the name of the matching malware signature, and undef otherwise.

---

👀 SEE ALSO 👀

The clamd and clamav man-pages. go read them, bestie, they're the lore. 📚

---

🫶 AVAILABILITY and SUPPORT 🫶

The latest version of ClamAV::Client is available on CPAN and at <http://www.mehnle.net/software/clamav-client>. 🌐

Support is usually (but not guaranteed to be) given by the author, Julian Mehnle <julian@mehnle.net>. so like, he's around, but no promises, iykyk.

---

🎀 AUTHOR and LICENSE 🎀

ClamAV::Client is Copyright (C) 2004-2005 Julian Mehnle <julian@mehnle.net>.

ClamAV::Client is free software. You may use, modify, and distribute it under the same terms as Perl itself, i.e. under the GNU GPL or the Artistic License. so go forth and distribute, bestie. 💖

---

and that's the whole page, fr fr — perl v5.38.2, dated 2024-05-16, and the manual is ClamAV::Client(3pm). mwah, slay, take care of your files. 🦋✨