/ 
Net-Pcap-0.06
River stage two • 12 direct dependents • 20 total dependents
/ Net::Pcap

NAME

Net::Pcap - Interface to pcap(3) LBL packet capture library

VERSION

Version 0.06

SYNOPSIS

use Net::Pcap;

my $err = '';
my $dev = Net::Pcap::lookupdev(\$err);  # find a device

# open the device for live listening
my $pcap = Net::Pcap::open_live($dev, 1024, 1, 0, \$err);

# loop over next 10 packets
Net::Pcap::loop($pcap, 10, \&process_packet, "just for the demo");

# close the device
Net::Pcap::close($pcap);

sub process_packet {
    my($user_data, $header, $packet) = @_;
    # do something ...
}

DESCRIPTION

Net::Pcap is a Perl binding to the LBL pcap(3) library. 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."

FUNCTIONS

All functions defined by 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 Net::Pcap::lookupdev(), are passed that parameter as a reference. This is to retain compatibility with previous versions of Net::Pcap.

Lookup functions

Net::Pcap::lookupdev(\$err)

Returns the name of a network device that can be used with Net::Pcap::open_live() function. On error, the $err parameter is filled with an appropriate error message else it is undefined.

Net::Pcap::findalldevs(\$err)

Returns a list of all network device names that can be used with Net::Pcap::open_live() function. On error, the $err parameter is filled with an appropriate error message else it is undefined.

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.

Packet capture functions

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 milliseconds. The packet descriptor will be undefined if an error occurs, and the $err parameter will be set with an appropriate error message.

Net::Pcap::loop($pcap, $count, \&callback, $user_data)

Read $cnt packets from the packet capture descriptor $pcap and call the perl function &callback with an argument of $user_data. If $count 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_packet {
    my($user_data, $header, $packet) = @_;

    ...
}

The header information is a reference to a hash containing the following fields.

  • len

    The total length of the packet.

  • caplen

    The actual captured length of the packet data. This corresponds to the snapshot length parameter passed to Net::Pcap::open_live().

  • tv_sec

    Seconds value of the packet timestamp.

  • tv_usec

    Microseconds value of the packet timestamp.

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.

Net::Pcap::close($pcap)

Close the packet capture device associated with descriptor $pcap.

Net::Pcap::dispatch($pcap, $count, \&callback, $user_data)

Collect $count packets and process them with callback function &callback. if $count is -1, all packets currently buffered are processed. If $count is 0, process all packets until an error occurs.

Net::Pcap::next($pcap, \%header)

Return the next available packet on the interface associated with packet descriptor $pcap. Into the %header hash is stored the received packet header. If not packet is available, the return value and header is undefined.

Net::Pcap::compile($pcap, \$filter, $filter_str, $optimize, $netmask)

Compile the filter string contained in $filter_str and store it in $filter. 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 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.

Net::Pcap::setfilter($pcap, $filter)

Associate the compiled filter stored in $filter with the packet capture descriptor $pcap.

Net::Pcap::setnonblock($pcap, $mode, \$err)

Set the non-blocking mode of a live capture descriptor, depending on the value of $mode (zero to activate and non-zero to desactivate). It has no effect on offline descriptors. If there is an error, it returns -1 and sets $err.

In non-blocking mode, an attempt to read from the capture descriptor with pcap_dispatch() will, if no packets are currently available to be read, return 0 immediately rather than blocking waiting for packets to arrive. pcap_loop() and pcap_next() will not work in non-blocking mode.

Net::Pcap::getnonblock($pcap, \$err)

Returns the non-blocking state of the capture descriptor $pcap. Always returns 0 on savefiles. If there is an error, it returns -1 and sets $err.

Savefile commands

Net::Pcap::dump_open($pcap, $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 Net::Pcap::geterr() can be used to retrieve the error text.

Net::Pcap::dump($pcap_dumper_t, \%header, $packet)

Dump the packet described by header %header and packet data $packet to the savefile associated with $pcap_dumper_t. The packet header has the same format as that passed to the Net::Pcap::loop() callback.

Net::Pcap::dump_close($pcap_dumper_t)

Close the savefile associated with descriptor $pcap_dumper_t.

Status functions

Net::Pcap::datalink($pcap)

Returns the link layer type associated with the currently open device.

Net::Pcap::snapshot($pcap)

Returns the snapshot length (snaplen) specified in the call to Net::Pcap::open_live().

Net::Pcap::is_swapped($pcap)

This function returns true if the endianess of the currently open savefile is different from the endianess of the machine.

Net::Pcap::major_version($pcap)

Return the major version number of the pcap library used to write the currently open savefile.

Net::Pcap::minor_version($pcap)

Return the minor version of the pcap library used to write the currently open savefile.

Net::Pcap::stats($pcap, \%stats)

Returns a hash containing information about the status of packet capture device $pcap. The hash contains the following fields.

  • ps_recv

    The number of packets received by the packet capture software.

  • ps_drop

    The number of packets dropped by the packet capture software.

  • ps_ifdrop

    The number of packets dropped by the network interface.

Net::Pcap::file($pcap)

Return the filehandle associated with a savefile opened with Net::Pcap::open_offline().

Net::Pcap::fileno($pcap)

Return the file number of the network device opened with Net::Pcap::open_live().

Error handling

Net::Pcap::geterr($pcap)

Return an error message for the last error associated with the packet capture device $pcap.

Net::Pcap::strerror($errno)

Return a string describing error number $errno.

Net::Pcap::perror($pcap, $prefix)

Print the text of the last error associated with descriptor $pcap on standard error, prefixed by $prefix.

DIAGNOSTICS

arg%d not a hash ref
arg%d not a reference

(F) These errors occur if you forgot to give a reference to a function which expect one or more of its arguments to be references.

LIMITATIONS

The following limitations apply to this version of Net::Pcap.

  • At present, only one callback function and user data scalar can be current at any time as they are both stored in global variables.

BUGS

Please report any bugs or feature requests to bug-Net-Pcap@rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-Pcap. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

Currently known bugs:

  • the ps_recv field is not correctly set; see t/07-stats.t; see http://rt.cpan.org/NoAuth/Bug.html?id=7371

  • the error string associated to a pcap_tPtr is never reset, thus leading to potential false errors; see t/09-error.t

  • Net::Pcap::file() seems to always returns undef for live connection and causes segmentation fault for dump files; see t/10-fileno.t

EXAMPLES

See the eg/ and t/ directories of the Net::Pcap distribution for examples on using this module.

SEE ALSO

pcap(3), tcpdump(8)

The source code for libpcap is available from http://www.tcpdump.org/

AUTHORS

Current maintainer:

Sébastien Aperghis-Tramoni <sebastien@aperghis.net>

Previous authors & maintainers:

Marco Carnut <kiko@tempest.com.br>
Tim Potter <tpot@frungy.org>
Bo Adler <thumper@alumni.caltech.edu>
Peter Lister <p.lister@cranfield.ac.uk>

COPYRIGHT

Copyright (c) 2005 Sébastien Aperghis-Tramoni. All rights reserved.

Copyright (c) 2003 Marco Carnut. All rights reserved.

Copyright (c) 1999-2000 Tim Potter. All rights reserved.

Copyright (c) 1998 Bo Adler. All rights reserved.

Copyright (c) 1997 Peter Lister. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.