1 .\" @(#) $Header: /tcpdump/master/libpcap/pcap.3,v 1.17.2.1 2001/01/18 04:42:11 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.
24 .TH PCAP 3 "3 January 2001"
26 pcap \- Packet Capture library
34 pcap_t *pcap_open_live(char *device, int snaplen,
36 int promisc, int to_ms, char *ebuf)
37 pcap_t *pcap_open_dead(int linktype, int snaplen)
38 pcap_t *pcap_open_offline(char *fname, char *ebuf)
39 pcap_dumper_t *pcap_dump_open(pcap_t *p, char *fname)
43 char errbuf[PCAP_ERRBUF_SIZE];
44 char *pcap_lookupdev(char *errbuf)
45 int pcap_lookupnet(char *device, bpf_u_int32 *netp,
47 bpf_u_int32 *maskp, char *errbuf)
51 int pcap_dispatch(pcap_t *p, int cnt,
53 pcap_handler callback, u_char *user)
54 int pcap_loop(pcap_t *p, int cnt,
56 pcap_handler callback, u_char *user)
57 void pcap_dump(u_char *user, struct pcap_pkthdr *h,
63 int pcap_compile(pcap_t *p, struct bpf_program *fp,
65 char *str, int optimize, bpf_u_int32 netmask)
66 int pcap_setfilter(pcap_t *p, struct bpf_program *fp)
67 void pcap_freecode(struct bpf_program *);
71 u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h)
75 int pcap_datalink(pcap_t *p)
76 int pcap_snapshot(pcap_t *p)
77 int pcap_is_swapped(pcap_t *p)
78 int pcap_major_version(pcap_t *p)
79 int pcap_minor_version(pcap_t *p)
80 int pcap_stats(pcap_t *p, struct pcap_stat *ps)
81 FILE *pcap_file(pcap_t *p)
82 int pcap_fileno(pcap_t *p)
83 void pcap_perror(pcap_t *p, char *prefix)
84 char *pcap_geterr(pcap_t *p)
85 char *pcap_strerror(int error)
89 void pcap_close(pcap_t *p)
90 void pcap_dump_close(pcap_dumper_t *p)
94 The Packet Capture library
95 provides a high level interface to packet capture systems. All packets
96 on the network, even those destined for other hosts, are accessible
97 through this mechanism.
104 .B pcap_open_offline(),
108 is assumed to be able to hold at least
113 is used to obtain a packet capture descriptor to look
114 at packets on the network.
116 is a string that specifies the network device to open; on Linux systems
117 with 2.2 or later kernels, a
121 can be used to capture packets from all interfaces.
123 specifies the maximum number of bytes to capture.
125 specifies if the interface is to be put into promiscuous mode.
126 (Note that even if this parameter is false, the interface
127 could well be in promiscuous mode for some other reason.) For now, this
128 doesn't work on the "any" device; if an argument of "any" or NULL is
133 specifies the read timeout in milliseconds. The read timeout is used to
134 arrange that the read not necessarily return immediately when a packet
135 is seen, but that it wait for some amount of time to allow more packets
136 to arrive and to read multiple packets from the OS kernel in one
137 operation. Not all platforms support a read timeout; on platforms that
138 don't, the read timeout is ignored.
140 is used to return error text and is only set when
146 is used for creating a
148 structure to use when calling the other functions in libpcap. It is
149 typically used when just using libpcap for compiling BPF code.
151 .B pcap_open_offline()
152 is called to open a ``savefile'' for reading.
154 specifies the name of the file to open. The file has
155 the same format as those used by
159 The name "-" in a synonym for
162 is used to return error text and is only set when
163 .B pcap_open_offline()
168 is called to open a ``savefile'' for writing. The name "-" in a synonym
172 is returned on failure.
176 struct as returned by
177 .B pcap_open_offline()
179 .BR pcap_open_live() .
181 specifies the name of the file to open.
186 can be used to get the error text.
189 returns a pointer to a network device suitable for use with
192 .BR pcap_lookupnet() .
193 If there is an error,
197 is filled in with an appropriate error message.
200 is used to determine the network number and mask
201 associated with the network device
210 A return of \-1 indicates an error in which case
212 is filled in with an appropriate error message.
215 is used to collect and process packets.
217 specifies the maximum number of packets to process before returning.
218 This is not a minimum number; when reading a live capture, only one
219 bufferful of packets is read at a time, so fewer than
221 packets may be processed. A
223 of \-1 processes all the packets received in one buffer when reading a
224 live capture, or all the packets in the file when reading a
227 specifies a routine to be called with three arguments:
230 pointer which is passed in from
231 .BR pcap_dispatch() ,
234 struct (which precede the actual network headers and data),
237 pointer to the packet data.
239 The number of packets read is returned.
240 0 is returned if no packets were read from a live capture (if, for
241 example, they were discarded because they didn't pass the packet filter,
242 or if, on platforms that support a read timeout that starts before any
243 packets arrive, the timeout expires before any packets arrive, or if the
244 file descriptor for the capture device is in non-blocking mode and no
245 packets were available to be read) or if no more packets are available
246 in a ``savefile.'' A return of \-1 indicates
247 an error in which case
251 may be used to display the error text.
254 when reading a live capture,
256 will not necessarily return when the read times out; on some platforms,
257 the read timeout isn't supported, and, on other platforms, the timer
258 doesn't start until at least one packet arrives. This means that the
261 be used in, for example, an interactive application, to allow the packet
262 capture loop to ``poll'' for user input periodically, as there's no
265 will return after the timeout expires.
270 except it keeps reading packets until
272 packets are processed or an error occurs.
275 return when live read timeouts occur.
276 Rather, specifying a non-zero read timeout to
280 allows the reception and processing of any packets that arrive when the
286 to loop forever (or at least until an error occurs).
291 pointer to the next packet.
294 outputs a packet to the ``savefile'' opened with
295 .BR pcap_dump_open() .
296 Note that its calling arguments are suitable for use with
302 is used to compile the string
304 into a filter program.
308 struct and is filled in by
311 controls whether optimization on the resulting code is performed.
313 specifies the netmask of the local net.
314 A return of \-1 indicates an error in which case
316 may be used to display the error text.
318 .B pcap_compile_nopcap()
321 except that instead of passing a pcap structure, one passes the
322 snaplen and linktype explicitly. It is intended to be used for
323 compiling filters for direct BPF usage, without necessarily having
326 A return of \-1 indicates an error; the error text is unavailable.
327 .RB ( pcap_compile_nopcap()
329 .BR pcap_open_dead() ,
333 the latter three routines can be used directly in order to get the error
334 text for a compilation error.)
338 is used to specify a filter program.
342 struct, usually the result of a call to
345 is returned on failure, in which case
347 may be used to display the error text;
349 is returned on success.
352 is used to free up allocated memory pointed to by a
356 when that BPF program is no longer needed, for example after it
357 has been made the filter program for a pcap structure by a call to
358 .BR pcap_setfilter() .
361 returns the link layer type, e.g.
365 returns the snapshot length specified when
370 returns true if the current ``savefile'' uses a different byte order
371 than the current system.
373 .B pcap_major_version()
374 returns the major number of the version of the pcap used to write the
377 .B pcap_minor_version()
378 returns the minor number of the version of the pcap used to write the
382 returns the name of the ``savefile.''
385 returns 0 and fills in a
387 struct. The values represent packet statistics from the start of the
388 run to the time of the call. If there is an error or the under lying
389 packet capture doesn't support packet statistics, \-1 is returned and
390 the error text can be obtained with
396 returns the file descriptor number of the ``savefile.''
399 prints the text of the last pcap library error on
405 returns the error text pertaining to the last pcap library error.
407 the pointer it returns will no longer point to a valid error message
410 passed to it is closed; you must use or copy the string before closing
420 closes the files associated with
422 and deallocates resources.
425 closes the ``savefile.''
428 tcpdump(1), tcpslice(1)
430 The original authors are:
434 Steven McCanne, all of the
435 Lawrence Berkeley National Laboratory, University of California, Berkeley, CA.
437 The current version is available from "The Tcpdump Group"'s Web site at
440 .I http://www.tcpdump.org/
443 Please send problems, bugs, questions, desirable enhancements, etc. to:
446 tcpdump-workers@tcpdump.org
449 Please send source code contributions, etc. to: