/ 
Mail-ClamAV-0.06
River stage zero No dependents
/ Mail::ClamAV

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 http://clamav.elektrapro.com/. 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 http://www.clamav.net/doc/html-0.65/node44.html

AUTHOR

Scott Beck <sbeck@gossamer-threads.com>

COPYRIGHT AND LICENSE

Copyright (C) 2003 by Gossamer Threads Inc. http://www.gossamer-threads.com

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.