#
# Pcap.pm
#
# An interface to the LBL pcap(3) library. This module simply
# bootstraps the extensions defined in Pcap.xs
#
# Copyright (c) 1999-2000 Tim Potter. All rights reserved. This program is
# free# software; you can redistribute it and/or modify it under the same
# terms as Perl itself.
#
# Comments/suggestions to tpot@frungy.org
#
# $Id: Pcap.pm,v 1.9 2000/05/15 05:02:50 tpot Exp $
#
package Net::Pcap;
require Exporter;
require DynaLoader;
use vars qw($VERSION @ISA);
@ISA = qw(Exporter DynaLoader);
@EXPORT = qw();
$VERSION = '0.05';
bootstrap Net::Pcap $VERSION;
1;
# autoloaded methods go after the END token (&& pod) below
__END__
=head1 NAME
B<Net::Pcap> - Interface to pcap(3) LBL packet capture library
=head1 SYNOPSIS
use Net::Pcap;
=head1 DESCRIPTION
B<Net::Pcap> is a Perl binding to the LBL pcap(3) library, version
0.7.2. The README for libpcap describes itself as:
"a system-independent interface for user-level packet capture.
libpcap provides a portable framework for low-level network
monitoring. Applications include network statistics collection,
security monitoring, network debugging, etc."
=head1 FUNCTIONS
All functions defined by B<Net::Pcap> are direct mappings to the
libpcap functions. Consult the pcap(3) documentation and source code
for more information.
Arguments that change a parameter, for example B<Net::Pcap::lookupdev()>,
are passed that parameter as a reference. This is to retain
compatibility with previous versions of B<Net::Pcap>.
=head2 Lookup functions
=over
=item B<Net::Pcap::lookupdev(\$err);>
Returns the name of a network device that can be used with
B<Net::Pcap::open_live() function>. On error, the $err parameter is
filled with an appropriate error message else it is undefined.
=item B<Net::Pcap::findalldevs(\$err);>
Returns a list of all network device names that can be used with
B<Net::Pcap::open_live() function>. On error, the $err parameter is
filled with an appropriate error message else it is undefined.
=item B<Net::Pcap::lookupnet($dev, \$net, \$mask, \$err);>
Determine the network number and netmask for the device specified in
$dev. The function returns 0 on success and sets the $net and
$mask parameters with values. On failure it returns -1 and the
$err parameter is filled with an appropriate error message.
=head2 Packet capture functions
=over
=item B<Net::Pcap::open_live($dev, $snaplen, $promisc, $to_ms, \$err);>
Returns a packet capture descriptor for looking at packets on the
network. The $dev parameter specifies which network interface to
capture packets from. The $snaplen and $promisc parameters specify
the maximum number of bytes to capture from each packet, and whether
to put the interface into promiscuous mode, respectively. The $to_ms
parameter specifies a read timeout in ms. The packet descriptor will
be undefined if an error occurs, and the $err parameter will be set
with an appropriate error message.
=item B<Net::Pcap::loop($pcap_t, $cnt, \&callback_fn, $user_data);>
Read $cnt packets from the packet capture descriptor $pcap_t and call
the perl function &callback_fn with an argument of $user_data. If $cnt is negative, then the function loops forever or until an error occurs.
The callback function is also passed packet header information and
packet data like so:
sub process_pkt {
my($user_data, $hdr, $pkt) = @_;
...
}
The header information is a reference to a hash containing the
following fields.
=over
=item * len
The total length of the packet.
=item * caplen
The actual captured length of the packet data. This corresponds to
the snapshot length parameter passed to B<Net::Pcap::open_live()>.
=item * tv_sec
Seconds value of the packet timestamp.
=item * tv_usec
Microseconds value of the packet timestamp.
=back
=item B<Net::Pcap::open_offline($filename, \$err);>
Return a packet capture descriptor to read from a previously created
"savefile". The returned descriptor is undefined if there was an
error and in this case the $err parameter will be filled. Savefiles
are created using the Net::Pcap::dump_* commands.
=item B<Net::Pcap::close($pcap_t);>
Close the packet capture device associated with descriptor $pcap_t.
=item B<Net::Pcap::dispatch($pcap_t, $cnt, \&callback_fn, $user_data);>
Collect $cnt packets and process them with callback function
&callback_fn. if $cnt is -1, all packets currently buffered are
processed. If $cnt is 0, process all packets until an error occurs.
=item B<Net::Pcap::next($pcap_t, \%hdr);>
Return the next available packet on the interface associated with
packet descriptor $pcap_t. Into the %hdr hash is stored the received
packet header. If not packet is available, the return value and
header is undefined.
=item B<Net::Pcap::compile($pcap_t, \$filter_t, $filter_str, $optimize, $netmask);>
Compile the filter string contained in $filter_str and store it in
$filter_t. A description of the filter language can be found in the
libpcap source code, or the manual page for tcpdump(8) . The filter
is optimized the filter if the $optimize variable is true. The
netmask of the network device must be specified in the $netmask
parameter. The function returns 0 if the compilation was successful,
or -1 if there was a problem.
=item B<Net::Pcap::setfilter($pcap_t, $filter_t);>
Associate the compiled filter stored in $filter_t with the packet
capture descriptor $pcap_t.
=back
=head2 Savefile commands
=over
=item B<Net::Pcap::dump_open($pcap_t, $filename);>
Open a savefile for writing and return a descriptor for doing so. If
$filename is "-" data is written to standard output. On error, the
return value is undefined and B<Net::Pcap::geterr()> can be used to
retrieve the error text.
=item B<Net::Pcap::dump($pcap_dumper_t, \%hdr, $pkt);>
Dump the packet described by header %hdr and packet data $pkt to the
savefile associated with $pcap_dumper_t. The packet header has the
same format as that passed to the B<Net::Pcap::loop()> callback.
=item B<Net::Pcap::dump_close($pcap_dumper_t);>
Close the savefile associated with descriptor $pcap_dumper_t.
=back
=head2 Status functions
=over
=item B<Net::Pcap::datalink($pcap_t);>
Returns the link layer type associated with the currently open device.
=item B<Net::Pcap::snapshot($pcap_t);>
Returns the snapshot length (snaplen) specified in the call to
B<Net::Pcap::open_live()>.
=item B<Net::Pcap::is_swapped($pcap_t);>
This function returns true if the endianess of the currently open
savefile is different from the endianess of the machine.
=item B<Net::Pcap::major_version($pcap_t);>
Return the major version number of the pcap library used to write the
currently open savefile.
=item B<Net::Pcap::minor_version($pcap_t);>
Return the minor version of the pcap library used to write the
currently open savefile.
=item B<Net::Pcap::stats($pcap_t, \%stats);>
Returns a hash containing information about the status of packet
capture device $pcap_t. The hash contains the following fields.
=over
=item * B<ps_recv>
The number of packets received by the packet capture software.
=item * B<ps_drop>
The number of packets dropped by the packet capture software.
=item * B<ps_ifdrop>
The number of packets dropped by the network interface.
=back
=item B<Net::Pcap::file($pcap_t);>
Return the filehandle associated with a savefile opened with
B<Net::Pcap::open_offline()>.
=item B<Net::Pcap::fileno($pcap_t);>
Return the file number of the network device opened with
B<Net::Pcap::open_live()>.
=back
=head2 Error handling
=over
=item B<Net::Pcap::geterr($pcap_t);>
Return an error message for the last error associated with the packet
capture device $pcap_t.
=item B<Net::Pcap::strerror($errno);>
Return a string describing error number $errno.
=item B<Net::Pcap::perror($pcap_t, $prefix);>
Print the text of the last error associated with descriptor $pcap_t on
standard error, prefixed by $prefix.
=back
=head1 LIMITATIONS
The following limitations apply to this version of B<Net::Pcap>.
=over
=item *
At present, only one callback function and user data scalar can be
current at any time as they are both stored in global variables.
=back
=head1 EXAMPLES
See the 't' directory of the B<Net::Pcap> distribution for examples
on using this module.
=head1 COPYRIGHT
Copyright (c) 1999-2000 Tim Potter. All rights reserved. This program is
free software; you can redistribute it and/or modify it under the same
terms as Perl itself.
=head1 SEE ALSO
pcap(3), tcpdump(8)
The source code for libpcap is available from B<ftp://ftp.ee.lbl.gov/libpcap.tar.Z>
=head1 AUTHOR
Tim Potter E<lt>tpot@frungy.orgE<gt>
=cut