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

Provided by: libclamav-client-perl_0.11-2_all

NAME

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

VERSION

       0.11

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

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.

Instance methods
The following instance methods are provided:

Daemon maintenance

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

AVAILABILITY and SUPPORT

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

       Support is usually (but not guaranteed to be) given by the author, Julian Mehnle
       <julian@mehnle.net>.

AUTHOR and LICENSE