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, not 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 or if, when reading from a ``savefile'', no more packets
123 are available. It returns \-1 if an error occurs or \-2 if the loop
124 terminated due to a call to
126 before any packets were processed.
129 return when live read timeouts occur; instead, it attempts to read more
133 returns the number of packets processed on success; this can be 0 if no
134 packets were read from a live capture (if, for example, they were
135 discarded because they didn't pass the packet filter, or if, on
136 platforms that support a read timeout that starts before any packets
137 arrive, the timeout expires before any packets arrive, or if the file
138 descriptor for the capture device is in non-blocking mode and no packets
139 were available to be read) or if no more packets are available in a
140 ``savefile.'' It returns \-1 if an error occurs or \-2 if the loop
141 terminated due to a call to
143 before any packets were processed.
145 If your application uses pcap_breakloop(),
146 make sure that you explicitly check for \-1 and \-2, rather than just
147 checking for a return value < 0.
156 as an argument to fetch or display the error text.
158 pcap(3PCAP), pcap_geterr(3PCAP), pcap_breakloop(3PCAP)