Tim Potter > Net-Pcap-0.04 > Net::Pcap



Annotate this POD (4)

Related Modules

By perlmonks.org


New  5
Open  8
View/Report Bugs
Module Version: 0.04   Source   Latest Release: Net-Pcap-0.17


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

Lookup functions


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::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 ms. 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_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.

  • 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.


Close the packet capture device associated with descriptor $pcap_t.

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.

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.

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.

Net::Pcap::setfilter($pcap_t, $filter_t);

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

Savefile commands

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

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 Net::Pcap::loop() callback.


Close the savefile associated with descriptor $pcap_dumper_t.

Status functions


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


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


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


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


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 $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.


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


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

Error handling


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


Return a string describing error number $errno.

Net::Pcap::perror($pcap_t, $prefix);

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


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


See the 't' directory of the Net::Pcap distribution for examples on using this module.


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>

syntax highlighting: