NAME
Mail::ClamAV - Perl extension for the clamav virus scanner
SYNOPSIS
use Mail::ClamAV qw/:all/;
# $Mail::ClamAV::Error in numeric context return clamav's
# error status code which corresponds to the constants which
# can be exported
my $c = new Mail::ClamAV("/path/to/directory/or/file")
or die "Failed to load db: $Mail::ClamAV::Error (", 0+$Mail::;
# You can get retdbdir() to get the database dir in
# clamav's conf
my $c = new Mail::ClamAV(retdbdir())
or die "Failed to load db: $Mail::ClamAV::Error";
# When database is loaded, you must create the proper trie with:
$c->buildtrie;
# check to see if we need to reload
if ($c->statchkdir) {
$c = new Mail::ClamAV(retdbdir());
$c->buildtrie;
}
# Set some limits (only applies to scan())
# Only relevant for archives
$c->maxreclevel(4);
$c->maxfiles(20);
$c->maxfilesize(1024 * 1024 * 20); # 20 megs
# Scan a buffer
my $status = $c->scanbuff($buff);
# Scan a filehandle (scandesc in clamav)
# scan(FileHandle or path, Bitfield of options)
my $status = $c->scan(FH, CL_ARCHIVE|CL_MAIL);
# Scan a file (scanfile in clamav)
my $status = $c->scan("/path/to/file.eml", CL_MAIL);
# $status is an overloaded object
die "Failed to scan: $status" unless $status;
if ($status->virus) {
print "Message is a virus: $status\n";
}
else {
print "No virus found!\n";
}
DESCRIPTION
Clam AntiVirus is an anti-virus toolkit for UNIX
. This module provide a simple interface
to its C API.
EXPORT
None by default.
Exportable constants
Options for scanning.
CL_MAIL
enables mbox and Maildir scanning
WARNING WARNING WARNING The MIME parsing in clamav is still beta
quality code as of the time of this writing [Tue Feb 10 10:09:56 PST
2004]. It will segfault with certain emails. This tested with current
CVS of clamav.
CL_ARCHIVE
enables archive scanning
CL_RAW
disables archive scanning
Status returns. These are the first item in the list returned by
"scan()" and "scanbuff()" when put into numeric context
CL_CLEAN
no viruses found
CL_VIRUS
virus found, put the status in scalar context to see the type
These are the error status codes which you can get by putting
$Mail::ClamAV::Error in numeric context
CL_EMAXREC
Recursion limit exceeded.
CL_EMAXSIZE
File size limit exceeded.
CL_EMAXFILES
Files number limit exceeded.
CL_ERAR
RAR module failure.
CL_EZIP
Zip module failure.
CL_EMALFZIP
Malformed Zip detected.
CL_EGZIP
GZip module failure.
CL_ETMPFILE
Unable to create temporary file.
CL_ETMPDIR
Unable to create temporary directory.
CL_EFSYNC
Unable to synchronize file <-> disk.
CL_EMEM
Unable to allocate memory.
CL_EOPEN
Unable to open file or directory.
CL_EMALFDB
Malformed database.
CL_EPATSHORT
Too short pattern detected.
CL_ENULLARG
Null argument passed when initialized is required.
Exportable functions
These function can be exported either individually or using the :all
export flags
retdbdir
This function returns the path to the database directory specified when
clamav was compiled.
METHODS
Settings
NOTE These settings only apply to "scan()" and archives (CL_ARCHIVE).
maxreclevel
Sets the maximum recursion level [default 5].
maxfiles
Maximum number of files that will be scanned [default 1000].
maxfilesize
Maximum file size that will be scanned in bytes [default 10M].
Scanning
All of these methods return a status object. This object is overloaded
to make things cleaner. In boolean context this will return false if
there was an error. For example: my $status = $c->scan("foo.txt"); die
"Error scanning: $status" unless $status;
As you probably just noticed, $status in scalar context returns the
error message. In addition to the overloading you just saw, $status has
the following methods:
errno
The numeric value (if any) clamav returned.
clean
This will be true if the message was not a virus and an error did not
occur.
virus
Returns true if the message is a virus.
error
Return the error message (if any). This is the same thing as quoting
$status.
count
Returns the number of messages scanned. Only works with archives.
scan(FileHandle or Path, Bitfield of options)
"scan()" takes a FileHanle or path and passed the file descriptor for
that off to clamav. The second argument is a bitfield of options,
CL_MAIL, CL_ARCHIVE or CL_RAW "Exportable constants".
This function returns the status object discussed earlier
scanbuff($buff)
scanbuff takes a raw buffer and scans it. No options are available for
this function (it is assumed you already unarchived or de-MIMEed the
buffer and that it is raw).
Data Directory stats
If the path passed into "new()" is a directory Mail::ClamAV will set
things up to check for updated database files. Calling the
"statchkdir()" will check the database directory to the stats we have in
memory. If anything has changed true is returned, otherwise false.
NOTE: trying to use "statchkdir()" when you passed in a database file
instead of directory will produce a fatal error.
"statchkdir()" is useful for long running daemons that need to check to
see if it is time to reload the database. Reloading is simply getting a
new Mail::ClamAV object and initializing it.
SEE ALSO
The ClamAV API documentation
AUTHOR
Scott Beck
COPYRIGHT AND LICENSE
Copyright (C) 2003 by Gossamer Threads Inc.
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself, either Perl version 5.8.1 or, at
your option, any later version of Perl 5 you may have available.