1 .\" @(#) $Header: /tcpdump/master/libpcap/pcap_loop.3pcap,v 1.4 2008-12-25 02:01:32 guy Exp $
3 .\" Copyright (c) 1994, 1996, 1997
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that: (1) source code distributions
8 .\" retain the above copyright notice and this paragraph in its entirety, (2)
9 .\" distributions including binary code include the above copyright notice and
10 .\" this paragraph in its entirety in the documentation or other materials
11 .\" provided with the distribution, and (3) all advertising materials mentioning
12 .\" features or use of this software display the following acknowledgement:
13 .\" ``This product includes software developed by the University of California,
14 .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
15 .\" the University nor the names of its contributors may be used to endorse
16 .\" or promote products derived from this software without specific prior
17 .\" written permission.
18 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
19 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
20 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
22 .TH PCAP_LOOP 3PCAP "24 December 2008"
24 pcap_loop, pcap_dispatch \- process packets from a live capture or savefile
28 #include <pcap/pcap.h>
32 typedef void (*pcap_handler)(u_char *user, const struct pcap_pkthdr *h,
38 int pcap_loop(pcap_t *p, int cnt,
40 pcap_handler callback, u_char *user);
41 int pcap_dispatch(pcap_t *p, int cnt,
43 pcap_handler callback, u_char *user);
48 processes packets from a live capture or ``savefile'' until
50 packets are processed, the end of the ``savefile'' is
51 reached when reading from a ``savefile'',
53 is called, or an error occurs.
56 return when live read timeouts occur.
57 A value of \-1 or 0 for
59 is equivalent to infinity, so that packets are processed until another
60 ending condition occurs.
63 processes packets from a live capture or ``savefile'' until
65 packets are processed, the end of the current bufferful of packets is
66 reached when doing a live capture, the end of the ``savefile'' is
67 reached when reading from a ``savefile'',
69 is called, or an error occurs.
70 Thus, when doing a live capture,
72 is the maximum number of packets to process before returning, but is not
73 a minimum number; when reading a live capture, only one
74 bufferful of packets is read at a time, so fewer than
76 packets may be processed. A value of \-1 or 0 for
78 causes all the packets received in one buffer to be processed when
79 reading a live capture, and causes all the packets in the file to be
80 processed when reading a ``savefile''.
83 (In older versions of libpcap, the behavior when
85 was 0 was undefined; different platforms and devices behaved
86 differently, so code that must work with older versions of libpcap
87 should use \-1, nor 0, as the value of
94 routine to be called with three arguments:
97 pointer which is passed in the
102 .BR pcap_dispatch() ,
104 .I const struct pcap_pkthdr
105 pointer pointing to the packet time stamp and lengths, and a
110 .I struct pcap_pkthdr
111 a pointer to which is passed to the callback routine)
112 bytes of data from the packet. The
113 .I struct pcap_pkthdr
114 and the packet data are not to be freed by the callback routine, and are
115 not guaranteed to be valid after the callback routine returns; if the
116 code needs them to be valid after the callback, it must make a copy of
122 is exhausted, \-1 if an error occurs, or \-2 if the loop terminated due
125 before any packets were processed.
128 return when live read timeouts occur; instead, it attempts to read more
132 returns the number of packets processed on success; this can be 0 if no
133 packets were read from a live capture (if, for example, they were
134 discarded because they didn't pass the packet filter, or if, on
135 platforms that support a read timeout that starts before any packets
136 arrive, the timeout expires before any packets arrive, or if the file
137 descriptor for the capture device is in non-blocking mode and no packets
138 were available to be read) or if no more packets are available in a
139 ``savefile.'' It returns \-1 if an error occurs or \-2 if the loop
140 terminated due to a call to
142 before any packets were processed.
144 If your application uses pcap_breakloop(),
145 make sure that you explicitly check for \-1 and \-2, rather than just
146 checking for a return value < 0.
155 as an argument to fetch or display the error text.
157 pcap(3PCAP), pcap_geterr(3PCAP), pcap_breakloop(3PCAP)