.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ClamAV::Client 3pm"
.TH ClamAV::Client 3pm "2022-05-27" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ClamAV::Client \- A client class for the ClamAV "clamd" virus scanner daemon
.SH "VERSION"
.IX Header "VERSION"
0.11
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SS "Creating a scanner client"
.IX Subsection "Creating a scanner client"
.Vb 1
\&    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     => \*(Aq/var/run/clamav/clamd.ctl\*(Aq
\&    );
\&    
\&    # Use a TCP socket:
\&    my $scanner = ClamAV::Client\->new(
\&        socket_host     => \*(Aq127.0.0.1\*(Aq,
\&        socket_port     => 3310
\&    );
\&    
\&    die("ClamAV daemon not alive")
\&        if not defined($scanner) or not $scanner\->ping();
.Ve
.SS "Daemon maintenance"
.IX Subsection "Daemon maintenance"
.Vb 2
\&    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.
.Ve
.SS "Path scanning (lazy)"
.IX Subsection "Path scanning (lazy)"
.Vb 7
\&    # 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 );
.Ve
.SS "Path scanning (complete)"
.IX Subsection "Path scanning (complete)"
.Vb 4
\&    # 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) { ... }
.Ve
.SS "Other scanning methods"
.IX Subsection "Other scanning methods"
.Vb 2
\&    # 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(\e$value);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBClamAV::Client\fR is a class acting as a client for a ClamAV \f(CW\*(C`clamd\*(C'\fR virus
scanner daemon.  The daemon may run locally or on a remote system as
\&\fBClamAV::Client\fR can use both Unix domain sockets and \s-1TCP/IP\s0 sockets.  The
full functionality of the \f(CW\*(C`clamd\*(C'\fR client/server protocol is supported.
.SS "Constructor"
.IX Subsection "Constructor"
The following constructor is provided:
.IP "\fBnew(%options)\fR: \s-1RETURNS\s0 ClamAV::Client" 4
.IX Item "new(%options): RETURNS ClamAV::Client"
Creates a new \f(CW\*(C`ClamAV::Client\*(C'\fR object.  If \fIno\fR socket options are specified,
first the socket options from the local \f(CW\*(C`clamd.conf\*(C'\fR configuration file are
tried, then the Unix domain socket \f(CW\*(C`/var/run/clamav/clamd.ctl\*(C'\fR is tried, then
finally the \s-1TCP/IP\s0 socket at \f(CW127.0.0.1\fR on port \f(CW3310\fR is tried.  If either
Unix domain or \s-1TCP/IP\s0 socket options are explicitly specified, only these are
used.
.Sp
\&\f(CW%options\fR is a list of key/value pairs representing any of the following
options:
.RS 4
.IP "\fBsocket_name\fR" 4
.IX Item "socket_name"
A scalar containing the absolute name of the local Unix domain socket.
Defaults to \fB'/var/run/clamav/clamd.ctl'\fR.
.IP "\fBsocket_host\fR" 4
.IX Item "socket_host"
A scalar containing the name or \s-1IP\s0 address of the \s-1TCP/IP\s0 socket.  Defaults to
\&\fB'127.0.0.1'\fR.
.IP "\fBsocket_port\fR" 4
.IX Item "socket_port"
A scalar containing the port number of the \s-1TCP/IP\s0 socket.  Defaults to \fB3310\fR.
.RE
.RS 4
.RE
.SS "Instance methods"
.IX Subsection "Instance methods"
The following instance methods are provided:
.PP
\fIDaemon maintenance\fR
.IX Subsection "Daemon maintenance"
.IP "\fBping\fR: \s-1RETURNS SCALAR\s0; \s-1THROWS\s0 ClamAV::Client::Error" 4
.IX Item "ping: RETURNS SCALAR; THROWS ClamAV::Client::Error"
Returns \fBtrue\fR ('\s-1PONG\s0') if the ClamAV daemon is alive.  Throws a
ClamAV::Client::Error exception otherwise.
.IP "\fBversion\fR: \s-1RETURNS SCALAR\s0; \s-1THROWS\s0 ClamAV::Client::Error" 4
.IX Item "version: RETURNS SCALAR; THROWS ClamAV::Client::Error"
Returns the version string of the ClamAV daemon.
.IP "\fBreload\fR: \s-1RETURNS SCALAR\s0; \s-1THROWS\s0 ClamAV::Client::Error" 4
.IX Item "reload: RETURNS SCALAR; THROWS ClamAV::Client::Error"
Instructs the ClamAV daemon to reload its malware database.  Returns \fBtrue\fR if
the reloading succeeds, or throws a ClamAV::Client::Error exception otherwise.
.IP "\fBquit\fR: \s-1RETURNS SCALAR\s0; \s-1THROWS\s0 ClamAV::Client::Error" 4
.IX Item "quit: RETURNS SCALAR; THROWS ClamAV::Client::Error"
.PD 0
.IP "\fBshutdown\fR: \s-1RETURNS SCALAR\s0; \s-1THROWS\s0 ClamAV::Client::Error" 4
.IX Item "shutdown: RETURNS SCALAR; THROWS ClamAV::Client::Error"
.PD
Terminates the ClamAV daemon.  Returns \fBtrue\fR if the termination succeeds,
or throws a ClamAV::Client::Error exception otherwise.
.IP "\fBscan_path($path)\fR: \s-1RETURNS SCALAR, SCALAR\s0; \s-1THROWS\s0 ClamAV::Client::Error" 4
.IX Item "scan_path($path): RETURNS SCALAR, SCALAR; THROWS ClamAV::Client::Error"
.PD 0
.IP "\fBscan_path($path, \f(CB$scan_mode\fB)\fR: \s-1RETURNS SCALAR, SCALAR\s0; \s-1THROWS\s0 ClamAV::Client::Error" 4
.IX Item "scan_path($path, $scan_mode): RETURNS SCALAR, SCALAR; THROWS ClamAV::Client::Error"
.PD
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 \fBClamAV::Client::SCAN_MODE_NORMAL\fR (which is the default)
causes a normal scan (\f(CW\*(C`SCAN\*(C'\fR) with archive support enabled, a mode of
\&\fBClamAV::Client::SCAN_MODE_RAW\fR causes a raw scan with archive support
disabled.
.Sp
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 \fBundef\fR.
.IP "\fBscan_path_complete($path)\fR: \s-1RETURNS HASH\s0; \s-1THROWS\s0 ClamAV::Client::Error" 4
.IX Item "scan_path_complete($path): RETURNS HASH; THROWS ClamAV::Client::Error"
Scans a single file or a whole directory structure \fIcompletely\fR, 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.
.Sp
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.
.IP "\fBscan_stream($handle)\fR: \s-1RETURNS SCALAR\s0; \s-1THROWS\s0 ClamAV::Client::Error" 4
.IX Item "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, \fBundef\fR
otherwise.
.IP "\fBscan_scalar(\e$value)\fR: \s-1RETURNS SCALAR\s0; \s-1THROWS\s0 ClamAV::Client::Error" 4
.IX Item "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, \fBundef\fR
otherwise.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The clamd and clamav man-pages.
.SH "AVAILABILITY and SUPPORT"
.IX Header "AVAILABILITY and SUPPORT"
The latest version of ClamAV::Client is available on \s-1CPAN\s0 and at
<http://www.mehnle.net/software/clamav\-client>.
.PP
Support is usually (but not guaranteed to be) given by the author, Julian
Mehnle <julian@mehnle.net>.
.SH "AUTHOR and LICENSE"
.IX Header "AUTHOR and LICENSE"
ClamAV::Client is Copyright (C) 2004\-2005 Julian Mehnle <julian@mehnle.net>.
.PP
ClamAV::Client is free software.  You may use, modify, and distribute it under
the same terms as Perl itself, i.e. under the \s-1GNU GPL\s0 or the Artistic License.