unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (NetBSD-6.1.5)
Page:
Section:
Apropos / Subsearch:
optional field

PCAP_LOOP(3)               Library Functions Manual               PCAP_LOOP(3)



NAME
       pcap_loop, pcap_dispatch - process packets from a live capture or
       savefile

SYNOPSIS
       #include <&lt;pcap/pcap.h>&gt;

       typedef void (*pcap_handler)(u_char *user, const struct pcap_pkthdr *h,
                           const u_char *bytes);

       int pcap_loop(pcap_t *p, int cnt,
       pcap_handler callback, u_char *user);
       int pcap_dispatch(pcap_t *p, int cnt,
       pcap_handler callback, u_char *user);

DESCRIPTION
       pcap_loop() processes packets from a live capture or ``savefile'' until
       cnt packets are processed, the end of the ``savefile'' is reached when
       reading from a ``savefile'', pcap_breakloop() is called, or an error
       occurs.  It does not return when live read timeouts occur.  A value of
       -1 or 0 for cnt is equivalent to infinity, so that packets are
       processed until another ending condition occurs.

       pcap_dispatch() processes packets from a live capture or ``savefile''
       until cnt packets are processed, the end of the current bufferful of
       packets is reached when doing a live capture, the end of the
       ``savefile'' is reached when reading from a ``savefile'',
       pcap_breakloop() is called, or an error occurs.  Thus, when doing a
       live capture, cnt is the maximum number of packets to process before
       returning, but is not a minimum number; when reading a live capture,
       only one bufferful of packets is read at a time, so fewer than cnt
       packets may be processed. A value of -1 or 0 for cnt causes all the
       packets received in one buffer to be processed when reading a live
       capture, and causes all the packets in the file to be processed when
       reading a ``savefile''.

       (In older versions of libpcap, the behavior when cnt was 0 was
       undefined; different platforms and devices behaved differently, so code
       that must work with older versions of libpcap should use -1, nor 0, as
       the value of cnt.)

       callback specifies a pcap_handler routine to be called with three
       arguments: a u_char pointer which is passed in the user argument to
       pcap_loop() or pcap_dispatch(), a const struct pcap_pkthdr pointer
       pointing to the packet time stamp and lengths, and a const u_char
       pointer to the first caplen (as given in the struct pcap_pkthdr a
       pointer to which is passed to the callback routine) bytes of data from
       the packet.

RETURN VALUE
       pcap_loop() returns 0 if cnt is exhausted, -1 if an error occurs, or -2
       if the loop terminated due to a call to pcap_breakloop() before any
       packets were processed.  It does not return when live read timeouts
       occur; instead, it attempts to read more packets.

       pcap_dispatch() returns the number of packets processed on success;
       this can be 0 if no packets were read from a live capture (if, for
       example, they were discarded because they didn't pass the packet
       filter, or if, on platforms that support a read timeout that starts
       before any packets arrive, the timeout expires before any packets
       arrive, or if the file descriptor for the capture device is in non-
       blocking mode and no packets were available to be read) or if no more
       packets are available in a ``savefile.''  It returns -1 if an error
       occurs or -2 if the loop terminated due to a call to pcap_breakloop()
       before any packets were processed.  If your application uses
       pcap_breakloop(), make sure that you explicitly check for -1 and -2,
       rather than just checking for a return value <&lt; 0.

       If -1 is returned, pcap_geterr() or pcap_perror() may be called with p
       as an argument to fetch or display the error text.

SEE ALSO
       pcap(3), pcap_geterr(3), pcap_breakloop(3)



                               24 December 2008                   PCAP_LOOP(3)