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

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:

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.