NAME

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

SYNOPSIS

  use Net::Pcap;

DESCRIPTION

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

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

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

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.

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

Close the savefile associated with descriptor $pcap_dumper_t.

Status functions

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 Net::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 $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 Net::Pcap::open_offline().

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

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

Error handling

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

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

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

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.

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.

EXAMPLES

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

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.

SEE ALSO

pcap(3), tcpdump(8)

The source code for libpcap is available from ftp://ftp.ee.lbl.gov/libpcap.tar.Z

AUTHOR

Tim Potter <tpot@frungy.org>

cpanm Net::Pcap

perl -MCPAN -e shell
install Net::Pcap