NAME

"Net::PcapUtils" - Utility routines for Net::Pcap module

SYNOPSIS

  require Net::Pcap 0.03;
  use Net::PcapUtils;

  # Call function for all packets received

  Net::PcapUtils::loop(\&callbackfn, [optional args]);

  # Return the next packet available on the interface

  ($pkt, %hdr) = Net::PcapUtils::next($pcap_t);

  # Open a network device for processing

  $pcap_t = Net::PcapUtils::open([optional args]);

DESCRIPTION

Net::PcapUtils is a module to sit in front of Net::Pcap in order to hide some of the pcap(3) initialisation by providing sensible defaults. This enables a programmer to easily write small, specific scripts for a particular purpose without having to worry about too many details.

The functions implemented in Net::PcapUtils are named after those in Net::Pcap. The loop function sits in a loop and executes a callback for each packet received, while next retrieves the next packet from the network device, and open returns an opened packet descriptor suitable for use with other Net::Pcap routines.

Functions

Net::PcapUtils::loop(\&callback_fn, [ARG => value]);

Given a callback function and a list of optional named parameterss, open a network interface, configure it, and execute the callback function for each packet received on the interface. If the SAVEFILE parameter is present, a saved file of that name will be opened for reading, else the network interface specified by the DEV parameter will be opened. If no saved file or device is specified, the interface returned by Net::Pcap::lookupdev() is opened.

The optional arguments are those which are normally passed to the pcap_open_live() function from the pcap(3) library. Their defaults are given below.

    my %args = (
        SNAPLEN => 100,         # Num bytes to capture from packet
        PROMISC => 1,           # Operate in promiscuous mode?
        TIMEOUT => 1000,        # Read timeout (ms)
        NUMPACKETS => -1,       # Pkts to read (-1 = loop forever)
        FILTER => '',           # Filter string
        USERDATA => '',         # Passed as first arg to callback fn
        SAVEFILE => '',         # Default save file
        DEV => '',              # Network interface to open
        );

Consult the documentation for the pcap(3) library for more details on the nature of these parameters.

On error, this function returns an error string describing the error. An empty string is returned upon success.

Net::PcapUtils::open([ARG => value]);

Return a packet capture descriptor. The optional arguments passed to this function are the same as those which can be passed to Net::PcapUtils::loop().

If the open() command was successful, it returns a reference to a packet capture descriptor, else a string containing an error message.

Net::PcapUtils::next($pcap_t);

Return the next packet available on the interface specified by packet capture descriptor $pcap_t. This may be obtained from the Net::PcapUtils::open() function, Net::Pcap::open_live() or Net::Pcap::open_offline().

EXAMPLE

The following script prints a message for each IP packet received.

  #!/usr/bin/perl -w

  use strict;
  use Net::PcapUtils;

  sub process_pkt {
      print("packet\n");
  }

  Net::PcapUtils::loop(\&process_pkt, FILTER => 'ip');

COPYRIGHT

  Copyright (c) 1995,1996,1997,1998,1999 ANU and CSIRO on behalf of
  the participants in the CRC for Advanced Computational Systems
  ('ACSys').

  ACSys makes this software and all associated data and documentation
  ('Software') available free of charge.  You may make copies of the 
  Software but you must include all of this notice on any copy.

  The Software was developed for research purposes and ACSys does not
  warrant that it is error free or fit for any purpose.  ACSys
  disclaims any liability for all claims, expenses, losses, damages
  and costs any user may incur as a result of using, copying or
  modifying the Software.

AUTHOR

Tim Potter <tpot@acsys.anu.edu.au>