ClamAV::Client - A client class for the ClamAV "clamd" virus scanner daemon

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.

perl v5.38.2                                       2024-05-16                                ClamAV::Client(3pm)

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>.

Description

ClamAV::Client is a class acting as a client for a ClamAV "clamd" virus scanner daemon. The daemon may
run locally or on a remote system as ClamAV::Client can use both Unix domain sockets and TCP/IP sockets.
The full functionality of the "clamd" client/server protocol is supported.

Constructor
The following constructor is provided:

new(%options): RETURNS ClamAV::Client
Creates a new "ClamAV::Client" object. If no socket options are specified, first the socket options
from the local "clamd.conf" configuration file are tried, then the Unix domain socket
"/var/run/clamav/clamd.ctl" is tried, then finally the TCP/IP socket at 127.0.0.1 on port 3310 is
tried. If either Unix domain or TCP/IP socket options are explicitly specified, only these are used.

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

socket_name
A scalar containing the absolute name of the local Unix domain socket. Defaults to
'/var/run/clamav/clamd.ctl'.

socket_host
A scalar containing the name or IP address of the TCP/IP socket. Defaults to '127.0.0.1'.

socket_port
A scalar containing the port number of the TCP/IP socket. Defaults to 3310.

Instancemethods
The following instance methods are provided:

Daemonmaintenanceping: RETURNS SCALAR; THROWS ClamAV::Client::Error
Returns true ('PONG') if the ClamAV daemon is alive. Throws a ClamAV::Client::Error exception
otherwise.

version: RETURNS SCALAR; THROWS ClamAV::Client::Error
Returns the version string of the ClamAV daemon.

reload: RETURNS SCALAR; THROWS ClamAV::Client::Error
Instructs 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
Terminates the ClamAV daemon. Returns true if the termination succeeds, or throws a
ClamAV::Client::Error exception otherwise.

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
specified path must be absolute. A scan mode may be specified: a mode of
ClamAV::Client::SCAN_MODE_NORMAL (which is the default) causes a normal scan ("SCAN") with archive
support enabled, a mode of ClamAV::Client::SCAN_MODE_RAW causes a raw scan with archive support
disabled.

If an infected file is found, returns a list consisting of the path of the file and the name of the
malware signature that matched the file. Otherwise, returns the originally specified path and undef.

scan_path_complete($path): RETURNS HASH; THROWS ClamAV::Client::Error
Scans a single file or a whole directory structure completely, not stopping at the first infected
file found. The specified path must be absolute. Only the normal, non-raw mode is supported for
complete scans by ClamAV.

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

scan_stream($handle): RETURNS SCALAR; THROWS ClamAV::Client::Error
Scans a stream, that is, reads from an I/O handle. If the stream is found to be infected, returns
the name of the matching malware signature, undef otherwise.

scan_scalar(\$value): RETURNS SCALAR; THROWS ClamAV::Client::Error
Scans the value referenced by the given scalarref. If the value is found to be infected, returns the
name of the matching malware signature, undef otherwise.

Name

       ClamAV::Client - A client class for the ClamAV "clamd" virus scanner daemon

Synopsis

Creatingascannerclient
           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();

   Daemonmaintenance
           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.

   Pathscanning(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 );

   Pathscanning(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) { ... }

   Otherscanningmethods
           # 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);