Julian Mehnle > ClamAV-Client > ClamAV::Client

Download:
clamav-client/ClamAV-Client-0.11.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  3
Open  0
View/Report Bugs
Module Version: 0.11   Source  

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.

SEE ALSO ^

The clamd and clamav man-pages.

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

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.

syntax highlighting: