Technical Reference: Base Operating System and Extensions, Volume 1

pcap_dispatch Subroutine

Purpose

Collects and processes packets.

Library

pcap Library (libpcap.a)

Syntax

#include <pcap.h> int pcap_dispatch(pcap_t * p, int cnt, pcap_handler callback, u_char * user);

Description

The pcap_dispatch subroutine reads and processes packets. This subroutine can be called to read and process packets that are stored in a previously saved packet capture data file, known as the savefile. The subroutine can also read and process packets that are being captured live.

Notice that the third parameter, callback, is of the type pcap_handler. This is a pointer to a user-provided subroutine with three parameters. Define this user-provided subroutine as follows:

   void user_routine(u_char *user, struct pcap_pkthdr *phdr, u_char *pdata)

The parameter, user, is the user parameter that is passed into the pcap_dispatch subroutine. The parameter, phdr, is a pointer to the pcap_pkthdr structure which precedes each packet in the savefile. The parameter, pdata, points to the packet data. This allows users to define their own handling of packet capture data.

Parameters

callback	Points to a user-provided routine that will be called for each packet read. The user is responsible for providing a valid pointer, and that unpredictable results can occur if an invalid pointer is supplied. Note The pcap_dump subroutine can also be specified as the callback parameter. If this is done, the pcap_dump_open subroutine should be called first. The pointer to the pcap_dumper_t struct returned from the pcap_dump_open subroutine should be used as the user parameter to the pcap_dispatch subroutine. The following program fragment illustrates this use: pcap_dumper_t pd pcap_t p; int rc = 0; pd = pcap_dump_open(p, "/tmp/savefile"); rc = pcap_dispatch(p, 0 , pcap_dump, (u_char *) pd);
cnt	Specifies the maximum number of packets to process before returning. A cnt of -1 processes all the packets received in one buffer. A cnt of 0 processes all packets until an error occurs, EOF is reached, or the read times out (when doing live reads and a non-zero read timeout is specified).
p	Points to a packet capture descriptor returned from the pcap_open_offline or the pcap_open_live subroutine. This will be used to store packet data that is read in.
user	Specifies the first argument to pass into the callback routine.

Return Values

Upon successful completion, the pcap_dispatch subroutine returns the number of packets read. If EOF is reached in a savefile, zero is returned. If the pcap_dispatch subroutine is unsuccessful, -1 is returned. In this case, the pcap_geterr or pcap_perror subroutine can be used to get the error text.

Related Information

The pcap_dump (pcap_dump Subroutine) subroutine, pcap_dump_close (pcap_dump_close Subroutine) subroutine, pcap_dump_open (pcap_dump_open Subroutine) subroutine, pcap_geterr (pcap_geterr Subroutine) subroutine, pcap_open_live (pcap_open_live Subroutine) subroutine, pcap_open_offline (pcap_open_offline Subroutine) subroutine, pcap_perror (pcap_perror Subroutine) subroutine.