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

  use Net::Pcap;

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

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

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

Returns the name of a network device that can be used with BINet::Pcap::open_live() function. On error, the CW$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 CW$dev. The function returns 0 on success and sets the CW$net and CW$mask parameters with values. On failure it returns -1 and the CW$err parameter is filled with an appropriate error message.

Returns a packet capture descriptor for looking at packets on the network. The CW$dev parameter specifies which network interface to capture packets from. The CW$snaplen and CW$promisc parameters specify the maximum number of bytes to capture from each packet, and whether to put the interface into promiscuous mode, respectively. The CW$to_ms parameter specifies a read timeout in ms. The packet descriptor will be undefined if an error occurs, and the CW$err parameter will be set with an appropriate error message. Read CW$cnt packets from the packet capture descriptor CW$pcap_t and call the perl function &callback_fn with an argument of CW$user_data. If CW$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) = @_;

      ...
  }

* 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 BINet::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 CW$err parameter will be filled. Savefiles are created using the Net::Pcap::dump_* commands.

Net::Pcap::close($pcap_t);

Close the packet capture device associated with descriptor CW$pcap_t. Collect CW$cnt packets and process them with callback function &callback_fn. if CW$cnt is -1, all packets currently buffered are processed. If CW$cnt is 0, process all packets until an error occurs.

Net::Pcap::next($pcap_t, \%hdr);

Return the next available packet on the interface associated with packet descriptor CW$pcap_t. Into the CW%hdr hash is stored the received packet header. If not packet is available, the return value and header is undefined. Compile the filter string contained in CW$filter_str and store it in CW$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 CW$optimize variable is true. The netmask of the network device must be specified in the CW$netmask parameter. The function returns 0 if the compilation was successful, or -1 if there was a problem. Associate the compiled filter stored in CW$filter_t with the packet capture descriptor CW$pcap_t.

Open a savefile for writing and return a descriptor for doing so. If CW$filename is - data is written to standard output. On error, the return value is undefined and BINet::Pcap::geterr() can be used to retrieve the error text. Dump the packet described by header CW%hdr and packet data CW$pkt to the savefile associated with CW$pcap_dumper_t. The packet header has the same format as that passed to the BINet::Pcap::loop() callback.

Net::Pcap::dump_close($pcap_dumper_t);

Close the savefile associated with descriptor CW$pcap_dumper_t.

Net::Pcap::datalink($pcap_t);

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

Net::Pcap::snapshot($pcap_t);

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

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.

Net::Pcap::major_version($pcap_t);

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

Net::Pcap::minor_version($pcap_t);

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

Net::Pcap::stats($pcap_t, \%stats);

Returns a hash containing information about the status of packet capture device CW$pcap_t. 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_t);

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

Net::Pcap::fileno($pcap_t);

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

Net::Pcap::geterr($pcap_t);

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

Net::Pcap::strerror($errno);

Return a string describing error number CW$errno. Print the text of the last error associated with descriptor CW$pcap_t on standard error, prefixed by CW$prefix.

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.

See the 't' directory of the Net::Pcap distribution for examples on using this module. This directory is installed at /usr/share/doc/libnet-pcap-perl/examples on your Debian system.

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.

pcap(3), tcpdump(8) The source code for libpcap is available from ftp://ftp.ee.lbl.gov/libpcap.tar.Z

Tim Potter <tpot@frungy.org>