Technical Reference: Base Operating System and Extensions, Volume 1

pcap_loop Subroutine

Purpose

Collects and processes packets.

Library

pcap Library (libpcap.a)

Syntax

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

Description

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

This subroutine is similar to pcap_dispatch subroutine except it continues to read packets until cnt packets have been processed, EOF is reached (in the case of offline reading), or an error occurs. It does not return when live read timeouts occur. That is, specifying a non-zero read timeout to the pcap_open_live subroutine and then calling the pcap_loop subroutine allows the reception and processing of any packets that arrive when the timeout occurs.

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 *phrd, u_char *pdata)

The parameter, user, will be the user parameter that was 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 their filtered packets.

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, call the pcap_dump_open subroutine first. Then use the pointer to the pcap_dumper_t struct returned from the pcap_dump_open subroutine 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 negative value causes the pcap_loop subroutine to loop forever, or until EOF is reached or an error occurs. A cnt of 0 processes all packets until an error occurs or EOF is reached.
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_loop subroutine returns 0. 0 is also returned if EOF has been reached in a savefile. If the pcap_loop subroutine is unsuccessful, -1 is returned. In this case, the pcap_geterr subroutine or the pcap_perror subroutine can be used to get the error text.

Related Information

The pcap_dispatch (pcap_dispatch Subroutine) subroutine, 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.