--- name: "ClamAV::Client" section: "3pm" platform: "linux" package: "libclamav-client-perl" version: "0.11+ds-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/ClamAV::Client" --- # ClamAV::Client(3pm) A client class for the ClamAV "clamd" virus scanner daemon ## 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 \. Support is usually (but not guaranteed to be) given by the author, Julian Mehnle \. ## AUTHOR and LICENSE ClamAV::Client is Copyright (C) 2004-2005 Julian Mehnle \. 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.