1PCAP(3) Library Functions Manual PCAP(3)
2
6 pcap - Packet Capture library
7
9 #include <pcap.h>
10 char errbuf[PCAP_ERRBUF_SIZE];
12 pcap_t *pcap_open_live(const char *device, int snaplen,
14 int promisc, int to_ms, char *errbuf)
15 pcap_t *pcap_open_dead(int linktype, int snaplen)
16 pcap_t *pcap_open_offline(const char *fname, char *errbuf)
17 pcap_t *pcap_fopen_offline(FILE *fp, char *errbuf)
18 pcap_dumper_t *pcap_dump_open(pcap_t *p, const char *fname)
19 pcap_dumper_t *pcap_dump_fopen(pcap_t *p, FILE *fp)
20 int pcap_setnonblock(pcap_t *p, int nonblock, char *errbuf);
22 int pcap_getnonblock(pcap_t *p, char *errbuf);
23 int pcap_findalldevs(pcap_if_t **alldevsp, char *errbuf)
25 void pcap_freealldevs(pcap_if_t *alldevs)
26 char *pcap_lookupdev(char *errbuf)
27 int pcap_lookupnet(const char *device, bpf_u_int32 *netp,
28 bpf_u_int32 *maskp, char *errbuf)
29 typedef void (*pcap_handler)(u_char *user, const struct pcap_pkthdr *h,
31 const u_char *bytes);
32 int pcap_dispatch(pcap_t *p, int cnt,
33 pcap_handler callback, u_char *user)
34 int pcap_loop(pcap_t *p, int cnt,
35 pcap_handler callback, u_char *user)
36 void pcap_dump(u_char *user, struct pcap_pkthdr *h,
37 u_char *sp)
38 int pcap_compile(pcap_t *p, struct bpf_program *fp,
40 const char *str, int optimize, bpf_u_int32 netmask)
41 int pcap_setfilter(pcap_t *p, struct bpf_program *fp)
42 void pcap_freecode(struct bpf_program *)
43 int pcap_setdirection(pcap_t *p, pcap_direction_t d)
44 const u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h)
46 int pcap_next_ex(pcap_t *p, struct pcap_pkthdr **pkt_header,
47 const u_char **pkt_data)
48 void pcap_breakloop(pcap_t *)
50 int pcap_inject(pcap_t *p, const void *buf, size_t size)
52 int pcap_sendpacket(pcap_t *p, const u_char *buf, int size)
53 int pcap_datalink(pcap_t *p)
55 int pcap_list_datalinks(pcap_t *p, int **dlt_buf);
56 int pcap_set_datalink(pcap_t *p, int dlt);
57 int pcap_datalink_name_to_val(const char *name);
58 const char *pcap_datalink_val_to_name(int dlt);
59 const char *pcap_datalink_val_to_description(int dlt);
60 int pcap_snapshot(pcap_t *p)
61 int pcap_is_swapped(pcap_t *p)
62 int pcap_major_version(pcap_t *p)
63 int pcap_minor_version(pcap_t *p)
64 int pcap_stats(pcap_t *p, struct pcap_stat *ps)
65 FILE *pcap_file(pcap_t *p)
66 int pcap_fileno(pcap_t *p)
67 int pcap_get_selectable_fd(pcap_t *p);
68 void pcap_perror(pcap_t *p, char *prefix)
69 char *pcap_geterr(pcap_t *p)
70 const char *pcap_strerror(int error)
71 const char *pcap_lib_version(void)
72 void pcap_close(pcap_t *p)
74 int pcap_dump_flush(pcap_dumper_t *p)
75 long pcap_dump_ftell(pcap_dumper_t *p)
76 FILE *pcap_dump_file(pcap_dumper_t *p)
77 void pcap_dump_close(pcap_dumper_t *p)
78
80 The Packet Capture library provides a high level interface to packet
81 capture systems. All packets on the network, even those destined for
82 other hosts, are accessible through this mechanism.
83
85 NOTE: errbuf in pcap_open_live(), pcap_open_dead(), pcap_open_off‐
86 line(), pcap_fopen_offline(), pcap_setnonblock(), pcap_getnonblock(),
87 pcap_findalldevs(), pcap_lookupdev(), and pcap_lookupnet() is assumed
88 to be able to hold at least PCAP_ERRBUF_SIZE chars.
89 pcap_open_live() is used to obtain a packet capture descriptor to look
91 at packets on the network. device is a string that specifies the net‐
92 work device to open; on Linux systems with 2.2 or later kernels, a
93 device argument of "any" or NULL can be used to capture packets from
94 all interfaces. snaplen specifies the maximum number of bytes to cap‐
95 ture. If this value is less than the size of a packet that is cap‐
96 tured, only the first snaplen bytes of that packet will be captured and
97 provided as packet data. A value of 65535 should be sufficient, on
98 most if not all networks, to capture all the data available from the
99 packet. promisc specifies if the interface is to be put into promiscu‐
100 ous mode. (Note that even if this parameter is false, the interface
101 could well be in promiscuous mode for some other reason.) For now,
102 this doesn't work on the "any" device; if an argument of "any" or NULL
103 is supplied, the promisc flag is ignored. to_ms specifies the read
104 timeout in milliseconds. The read timeout is used to arrange that the
105 read not necessarily return immediately when a packet is seen, but that
106 it wait for some amount of time to allow more packets to arrive and to
107 read multiple packets from the OS kernel in one operation. Not all
108 platforms support a read timeout; on platforms that don't, the read
109 timeout is ignored. A zero value for to_ms, on platforms that support
110 a read timeout, will cause a read to wait forever to allow enough pack‐
111 ets to arrive, with no timeout. errbuf is used to return error or
112 warning text. It will be set to error text when pcap_open_live() fails
113 and returns NULL. errbuf may also be set to warning text when
114 pcap_open_live() succeds; to detect this case the caller should store a
115 zero-length string in errbuf before calling pcap_open_live() and dis‐
116 play the warning to the user if errbuf is no longer a zero-length
117 string.
118 pcap_open_dead() is used for creating a pcap_t structure to use when
120 calling the other functions in libpcap. It is typically used when just
121 using libpcap for compiling BPF code.
122 pcap_open_offline() is called to open a ``savefile'' for reading.
124 fname specifies the name of the file to open. The file has the same
125 format as those used by tcpdump(8) and tcpslice(8). The name "-" in a
126 synonym for stdin. Alternatively, you may call pcap_fopen_offline() to
127 read dumped data from an existing open stream fp. Note that on Win‐
128 dows, that stream should be opened in binary mode. errbuf is used to
129 return error text and is only set when pcap_open_offline() or
130 pcap_fopen_offline() fails and returns NULL.
131 pcap_dump_open() is called to open a ``savefile'' for writing. The name
133 "-" in a synonym for stdout. NULL is returned on failure. p is a pcap
134 struct as returned by pcap_open_offline() or pcap_open_live(). fname
135 specifies the name of the file to open. Alternatively, you may call
136 pcap_dump_fopen() to write data to an existing open stream fp. Note
137 that on Windows, that stream should be opened in binary mode. If NULL
138 is returned, pcap_geterr() can be used to get the error text.
139 pcap_setnonblock() puts a capture descriptor, opened with
141 pcap_open_live(), into ``non-blocking'' mode, or takes it out of ``non-
142 blocking'' mode, depending on whether the nonblock argument is non-zero
143 or zero. It has no effect on ``savefiles''. If there is an error, -1
144 is returned and errbuf is filled in with an appropriate error message;
145 otherwise, 0 is returned. In ``non-blocking'' mode, an attempt to read
146 from the capture descriptor with pcap_dispatch() will, if no packets
147 are currently available to be read, return 0 immediately rather than
148 blocking waiting for packets to arrive. pcap_loop() and pcap_next()
149 will not work in ``non-blocking'' mode.
150 pcap_getnonblock() returns the current ``non-blocking'' state of the
152 capture descriptor; it always returns 0 on ``savefiles''. If there is
153 an error, -1 is returned and errbuf is filled in with an appropriate
154 error message.
155 pcap_findalldevs() constructs a list of network devices that can be
157 opened with pcap_open_live(). (Note that there may be network devices
158 that cannot be opened with pcap_open_live() by the process calling
159 pcap_findalldevs(), because, for example, that process might not have
160 sufficient privileges to open them for capturing; if so, those devices
161 will not appear on the list.) alldevsp is set to point to the first
162 element of the list; each element of the list is of type pcap_if_t, and
163 has the following members:
164 next if not NULL, a pointer to the next element in the list;
166 NULL for the last element of the list
167 name a pointer to a string giving a name for the device to
169 pass to pcap_open_live()
170 description
172 if not NULL, a pointer to a string giving a human-read‐
173 able description of the device
174 addresses
176 a pointer to the first element of a list of addresses for
177 the interface
178 flags interface flags:
180 PCAP_IF_LOOPBACK
182 set if the interface is a loopback interface
183 Each element of the list of addresses is of type pcap_addr_t, and has
185 the following members:
186 next if not NULL, a pointer to the next element in the list;
188 NULL for the last element of the list
189 addr a pointer to a struct sockaddr containing an address
191 netmask
193 if not NULL, a pointer to a struct sockaddr that contains
194 the netmask corresponding to the address pointed to by
195 addr
196 broadaddr
198 if not NULL, a pointer to a struct sockaddr that contains
199 the broadcast address corresponding to the address
200 pointed to by addr; may be null if the interface doesn't
201 support broadcasts
202 dstaddr
204 if not NULL, a pointer to a struct sockaddr that contains
205 the destination address corresponding to the address
206 pointed to by addr; may be null if the interface isn't a
207 point-to-point interface
208 Note that not all the addresses in the list of addresses are necessar‐
210 ily IPv4 or IPv6 addresses - you must check the sa_family member of the
211 struct sockaddr before interpreting the contents of the address.
212 -1 is returned on failure, in which case errbuf is filled in with an
214 appropriate error message; 0 is returned on success.
215 pcap_freealldevs() is used to free a list allocated by pcap_find‐
217 alldevs().
218 pcap_lookupdev() returns a pointer to a network device suitable for use
220 with pcap_open_live() and pcap_lookupnet(). If there is an error, NULL
221 is returned and errbuf is filled in with an appropriate error message.
222 pcap_lookupnet() is used to determine the network number and mask asso‐
224 ciated with the network device device. Both netp and maskp are
225 bpf_u_int32 pointers. A return of -1 indicates an error in which case
226 errbuf is filled in with an appropriate error message.
227 pcap_dispatch() is used to collect and process packets. cnt specifies
229 the maximum number of packets to process before returning. This is not
230 a minimum number; when reading a live capture, only one bufferful of
231 packets is read at a time, so fewer than cnt packets may be processed.
232 A cnt of -1 processes all the packets received in one buffer when read‐
233 ing a live capture, or all the packets in the file when reading a
234 ``savefile''. callback specifies a routine to be called with three
235 arguments: a u_char pointer which is passed in from pcap_dispatch(), a
236 const struct pcap_pkthdr pointer to a structure with the following mem‐
237 bers:
238 ts a struct timeval containing the time when the packet was
240 captured
241 caplen a bpf_u_int32 giving the number of bytes of the packet
243 that are available from the capture
244 len a bpf_u_int32 giving the length of the packet, in bytes
246 (which might be more than the number of bytes available
247 from the capture, if the length of the packet is larger
248 than the maximum number of bytes to capture)
249 and a const u_char pointer to the first caplen (as given in the struct
251 pcap_pkthdr a pointer to which is passed to the callback routine) bytes
252 of data from the packet (which won't necessarily be the entire packet;
253 to capture the entire packet, you will have to provide a value for
254 snaplen in your call to pcap_open_live() that is sufficiently large to
255 get all of the packet's data - a value of 65535 should be sufficient on
256 most if not all networks).
257 The number of packets read is returned. 0 is returned if no packets
259 were read from a live capture (if, for example, they were discarded
260 because they didn't pass the packet filter, or if, on platforms that
261 support a read timeout that starts before any packets arrive, the time‐
262 out expires before any packets arrive, or if the file descriptor for
263 the capture device is in non-blocking mode and no packets were avail‐
264 able to be read) or if no more packets are available in a ``savefile.''
265 A return of -1 indicates an error in which case pcap_perror() or
266 pcap_geterr() may be used to display the error text. A return of -2
267 indicates that the loop terminated due to a call to pcap_breakloop()
268 before any packets were processed. If your application uses
269 pcap_breakloop(), make sure that you explicitly check for -1 and -2,
270 rather than just checking for a return value < 0.
271 NOTE: when reading a live capture, pcap_dispatch() will not necessarily
273 return when the read times out; on some platforms, the read timeout
274 isn't supported, and, on other platforms, the timer doesn't start until
275 at least one packet arrives. This means that the read timeout should
276 NOT be used in, for example, an interactive application, to allow the
277 packet capture loop to ``poll'' for user input periodically, as there's
278 no guarantee that pcap_dispatch() will return after the timeout
279 expires.
280 pcap_loop() is similar to pcap_dispatch() except it keeps reading pack‐
282 ets until cnt packets are processed or an error occurs. It does not
283 return when live read timeouts occur. Rather, specifying a non-zero
284 read timeout to pcap_open_live() and then calling pcap_dispatch()
285 allows the reception and processing of any packets that arrive when the
286 timeout occurs. A negative cnt causes pcap_loop() to loop forever (or
287 at least until an error occurs). -1 is returned on an error; 0 is
288 returned if cnt is exhausted; -2 is returned if the loop terminated due
289 to a call to pcap_breakloop() before any packets were processed. If
290 your application uses pcap_breakloop(), make sure that you explicitly
291 check for -1 and -2, rather than just checking for a return value < 0.
292 pcap_next() reads the next packet (by calling pcap_dispatch() with a
294 cnt of 1) and returns a u_char pointer to the data in that packet.
295 (The pcap_pkthdr struct for that packet is not supplied.) NULL is
296 returned if an error occured, or if no packets were read from a live
297 capture (if, for example, they were discarded because they didn't pass
298 the packet filter, or if, on platforms that support a read timeout that
299 starts before any packets arrive, the timeout expires before any pack‐
300 ets arrive, or if the file descriptor for the capture device is in non-
301 blocking mode and no packets were available to be read), or if no more
302 packets are available in a ``savefile.'' Unfortunately, there is no
303 way to determine whether an error occured or not.
304 pcap_next_ex() reads the next packet and returns a success/failure
306 indication:
307 1 the packet was read without problems
309 0 packets are being read from a live capture, and the time‐
311 out expired
312 -1 an error occurred while reading the packet
314 -2 packets are being read from a ``savefile'', and there are
316 no more packets to read from the savefile.
317 If the packet was read without problems, the pointer pointed to by the
319 pkt_header argument is set to point to the pcap_pkthdr struct for the
320 packet, and the pointer pointed to by the pkt_data argument is set to
321 point to the data in the packet.
322 pcap_breakloop() sets a flag that will force pcap_dispatch() or
324 pcap_loop() to return rather than looping; they will return the number
325 of packets that have been processed so far, or -2 if no packets have
326 been processed so far.
327 This routine is safe to use inside a signal handler on UNIX or a con‐
329 sole control handler on Windows, as it merely sets a flag that is
330 checked within the loop.
331 The flag is checked in loops reading packets from the OS - a signal by
333 itself will not necessarily terminate those loops - as well as in loops
334 processing a set of packets returned by the OS. Note that if you are
335 catching signals on UNIX systems that support restarting system calls
336 after a signal, and calling pcap_breakloop() in the signal handler, you
337 must specify, when catching those signals, that system calls should NOT
338 be restarted by that signal. Otherwise, if the signal interrupted a
339 call reading packets in a live capture, when your signal handler
340 returns after calling pcap_breakloop(), the call will be restarted, and
341 the loop will not terminate until more packets arrive and the call com‐
342 pletes.
343 Note also that, in a multi-threaded application, if one thread is
345 blocked in pcap_dispatch(), pcap_loop(), pcap_next(), or
346 pcap_next_ex(), a call to pcap_breakloop() in a different thread will
347 not unblock that thread; you will need to use whatever mechanism the OS
348 provides for breaking a thread out of blocking calls in order to
349 unblock the thread, such as thread cancellation in systems that support
350 POSIX threads.
351 Note that pcap_next() will, on some platforms, loop reading packets
353 from the OS; that loop will not necessarily be terminated by a signal,
354 so pcap_breakloop() should be used to terminate packet processing even
355 if pcap_next() is being used.
356 pcap_breakloop() does not guarantee that no further packets will be
358 processed by pcap_dispatch() or pcap_loop() after it is called; at most
359 one more packet might be processed.
360 If -2 is returned from pcap_dispatch() or pcap_loop(), the flag is
362 cleared, so a subsequent call will resume reading packets. If a posi‐
363 tive number is returned, the flag is not cleared, so a subsequent call
364 will return -2 and clear the flag.
365 pcap_inject() sends a raw packet through the network interface; buf
367 points to the data of the packet, including the link-layer header, and
368 size is the number of bytes in the packet. It returns the number of
369 bytes written on success. A return of -1 indicates an error in which
370 case pcap_perror() or pcap_geterr() may be used to display the error
371 text. Note that, even if you successfully open the network interface,
372 you might not have permission to send packets on it, or it might not
373 support sending packets; as pcap_open_live() doesn't have a flag to
374 indicate whether to open for capturing, sending, or capturing and send‐
375 ing, you cannot request an open that supports sending and be notified
376 at open time whether sending will be possible. Note also that some
377 devices might not support sending packets.
378 Note that, on some platforms, the link-layer header of the packet
380 that's sent might not be the same as the link-layer header of the
381 packet supplied to pcap_inject(), as the source link-layer address, if
382 the header contains such an address, might be changed to be the address
383 assigned to the interface on which the packet it sent, if the platform
384 doesn't support sending completely raw and unchanged packets. Even
385 worse, some drivers on some platforms might change the link-layer type
386 field to whatever value libpcap used when attaching to the device, even
387 on platforms that do nominally support sending completely raw and
388 unchanged packets.
389 pcap_sendpacket() is like pcap_inject(), but it returns 0 on success
391 and -1 on failure. (pcap_inject() comes from OpenBSD; pcap_send‐
392 packet() comes from WinPcap. Both are provided for compatibility.)
393 pcap_dump() outputs a packet to the ``savefile'' opened with
395 pcap_dump_open(). Note that its calling arguments are suitable for use
396 with pcap_dispatch() or pcap_loop(). If called directly, the user
397 parameter is of type pcap_dumper_t as returned by pcap_dump_open().
398 pcap_compile() is used to compile the string str into a filter program.
400 program is a pointer to a bpf_program struct and is filled in by
401 pcap_compile(). optimize controls whether optimization on the result‐
402 ing code is performed. netmask specifies the IPv4 netmask of the net‐
403 work on which packets are being captured; it is used only when checking
404 for IPv4 broadcast addresses in the filter program. If the netmask of
405 the network on which packets are being captured isn't known to the pro‐
406 gram, or if packets are being captured on the Linux "any" pseudo-inter‐
407 face that can capture on more than one network, a value of 0 can be
408 supplied; tests for IPv4 broadcast addreses won't be done correctly,
409 but all other tests in the filter program will be OK. A return of -1
410 indicates an error in which case pcap_geterr() may be used to display
411 the error text.
412 pcap_compile_nopcap() is similar to pcap_compile() except that instead
414 of passing a pcap structure, one passes the snaplen and linktype
415 explicitly. It is intended to be used for compiling filters for direct
416 BPF usage, without necessarily having called pcap_open(). A return of
417 -1 indicates an error; the error text is unavailable. (pcap_com‐
418 pile_nopcap() is a wrapper around pcap_open_dead(), pcap_compile(), and
419 pcap_close(); the latter three routines can be used directly in order
420 to get the error text for a compilation error.)
421 pcap_setfilter() is used to specify a filter program. fp is a pointer
423 to a bpf_program struct, usually the result of a call to pcap_com‐
424 pile(). -1 is returned on failure, in which case pcap_geterr() may be
425 used to display the error text; 0 is returned on success.
426 pcap_freecode() is used to free up allocated memory pointed to by a
428 bpf_program struct generated by pcap_compile() when that BPF program is
429 no longer needed, for example after it has been made the filter program
430 for a pcap structure by a call to pcap_setfilter().
431 pcap_setdirection() is used to specify a direction that packets will be
433 captured. pcap_direction_t is one of the constants PCAP_D_IN,
434 PCAP_D_OUT or PCAP_D_INOUT. PCAP_D_IN will only capture packets
435 received by the device, PCAP_D_OUT will only capture packets sent by
436 the device and PCAP_D_INOUT will capture packets received by or sent by
437 the device. PCAP_D_INOUT is the default setting if this function is
438 not called. This isn't necessarily supported on all platforms; some
439 platforms might return an error, and some other platforms might not
440 support PCAP_D_OUT. This operation is not supported if a ``savefile''
441 is being read. -1 is returned on failure, 0 is returned on success.
442 pcap_datalink() returns the link layer type; link layer types it can
444 return include:
445 DLT_NULL
447 BSD loopback encapsulation; the link layer header is a 4-byte
448 field, in host byte order, containing a PF_ value from
449 socket.h for the network-layer protocol of the packet.
450 Note that ``host byte order'' is the byte order of the
452 machine on which the packets are captured, and the PF_ values
453 are for the OS of the machine on which the packets are cap‐
454 tured; if a live capture is being done, ``host byte order''
455 is the byte order of the machine capturing the packets, and
456 the PF_ values are those of the OS of the machine capturing
457 the packets, but if a ``savefile'' is being read, the byte
458 order and PF_ values are not necessarily those of the machine
459 reading the capture file.
460 DLT_EN10MB
462 Ethernet (10Mb, 100Mb, 1000Mb, and up)
463 DLT_IEEE802
465 IEEE 802.5 Token Ring
466 DLT_ARCNET
468 ARCNET
469 DLT_SLIP
471 SLIP; the link layer header contains, in order:
472 a 1-byte flag, which is 0 for packets received by the
474 machine and 1 for packets sent by the machine;
475 a 1-byte field, the upper 4 bits of which indicate the
477 type of packet, as per RFC 1144:
478 0x40 an unmodified IP datagram (TYPE_IP);
480 0x70 an uncompressed-TCP IP datagram (UNCOM‐
482 PRESSED_TCP), with that byte being the first
483 byte of the raw IP header on the wire, con‐
484 taining the connection number in the protocol
485 field;
486 0x80 a compressed-TCP IP datagram (COMPRESSED_TCP),
488 with that byte being the first byte of the
489 compressed TCP/IP datagram header;
490 for UNCOMPRESSED_TCP, the rest of the modified IP
492 header, and for COMPRESSED_TCP, the compressed TCP/IP
493 datagram header;
494 for a total of 16 bytes; the uncompressed IP datagram follows
496 the header.
497 DLT_PPP
499 PPP; if the first 2 bytes are 0xff and 0x03, it's PPP in
500 HDLC-like framing, with the PPP header following those two
501 bytes, otherwise it's PPP without framing, and the packet
502 begins with the PPP header.
503 DLT_FDDI
505 FDDI
506 DLT_ATM_RFC1483
508 RFC 1483 LLC/SNAP-encapsulated ATM; the packet begins with an
509 IEEE 802.2 LLC header.
510 DLT_RAW
512 raw IP; the packet begins with an IP header.
513 DLT_PPP_SERIAL
515 PPP in HDLC-like framing, as per RFC 1662, or Cisco PPP with
516 HDLC framing, as per section 4.3.1 of RFC 1547; the first
517 byte will be 0xFF for PPP in HDLC-like framing, and will be
518 0x0F or 0x8F for Cisco PPP with HDLC framing.
519 DLT_PPP_ETHER
521 PPPoE; the packet begins with a PPPoE header, as per RFC
522 2516.
523 DLT_C_HDLC
525 Cisco PPP with HDLC framing, as per section 4.3.1 of RFC
526 1547.
527 DLT_IEEE802_11
529 IEEE 802.11 wireless LAN
530 DLT_FRELAY
532 Frame Relay
533 DLT_LOOP
535 OpenBSD loopback encapsulation; the link layer header is a
536 4-byte field, in network byte order, containing a PF_ value
537 from OpenBSD's socket.h for the network-layer protocol of the
538 packet.
539 Note that, if a ``savefile'' is being read, those PF_ values
541 are not necessarily those of the machine reading the capture
542 file.
543 DLT_LINUX_SLL
545 Linux "cooked" capture encapsulation; the link layer header
546 contains, in order:
547 a 2-byte "packet type", in network byte order, which is
549 one of:
550 0 packet was sent to us by somebody else
552 1 packet was broadcast by somebody else
554 2 packet was multicast, but not broadcast, by
556 somebody else
557 3 packet was sent by somebody else to somebody
559 else
560 4 packet was sent by us
562 a 2-byte field, in network byte order, containing a
564 Linux ARPHRD_ value for the link layer device type;
565 a 2-byte field, in network byte order, containing the
567 length of the link layer address of the sender of the
568 packet (which could be 0);
569 an 8-byte field containing that number of bytes of the
571 link layer header (if there are more than 8 bytes, only
572 the first 8 are present);
573 a 2-byte field containing an Ethernet protocol type, in
575 network byte order, or containing 1 for Novell 802.3
576 frames without an 802.2 LLC header or 4 for frames
577 beginning with an 802.2 LLC header.
578 DLT_LTALK
580 Apple LocalTalk; the packet begins with an AppleTalk LLAP
581 header.
582 DLT_PFLOG
584 OpenBSD pflog; the link layer header contains, in order:
585 a 1-byte header length, in host byte order;
587 a 4-byte PF_ value, in host byte order;
589 a 2-byte action code, in network byte order, which is
591 one of:
592 0 passed
594 1 dropped
596 2 scrubbed
598 a 2-byte reason code, in network byte order, which is
600 one of:
601 0 match
603 1 bad offset
605 2 fragment
607 3 short
609 4 normalize
611 5 memory
613 a 16-character interface name;
615 a 16-character ruleset name (only meaningful if subrule
617 is set);
618 a 4-byte rule number, in network byte order;
620 a 4-byte subrule number, in network byte order;
622 a 1-byte direction, in network byte order, which is one
624 of:
625 0 incoming or outgoing
627 1 incoming
629 2 outgoing
631 DLT_PRISM_HEADER
633 Prism monitor mode information followed by an 802.11 header.
634 DLT_IP_OVER_FC
636 RFC 2625 IP-over-Fibre Channel, with the link-layer header
637 being the Network_Header as described in that RFC.
638 DLT_SUNATM
640 SunATM devices; the link layer header contains, in order:
641 a 1-byte flag field, containing a direction flag in the
643 uppermost bit, which is set for packets transmitted by
644 the machine and clear for packets received by the
645 machine, and a 4-byte traffic type in the low-order 4
646 bits, which is one of:
647 0 raw traffic
649 1 LANE traffic
651 2 LLC-encapsulated traffic
653 3 MARS traffic
655 4 IFMP traffic
657 5 ILMI traffic
659 6 Q.2931 traffic
661 a 1-byte VPI value;
663 a 2-byte VCI field, in network byte order.
665 DLT_IEEE802_11_RADIO
667 link-layer information followed by an 802.11 header - see
668 http://www.shaftnet.org/~pizza/software/capturefrm.txt for a
669 description of the link-layer information.
670 DLT_ARCNET_LINUX
672 ARCNET, with no exception frames, reassembled packets rather
673 than raw frames, and an extra 16-bit offset field between the
674 destination host and type bytes.
675 DLT_LINUX_IRDA
677 Linux-IrDA packets, with a DLT_LINUX_SLL header followed by
678 the IrLAP header.
679 DLT_LINUX_LAPD
681 LAPD (Q.921) frames, with a DLT_LINUX_SLL header captured via
682 vISDN.
683 pcap_list_datalinks() is used to get a list of the supported data link
685 types of the interface associated with the pcap descriptor.
686 pcap_list_datalinks() allocates an array to hold the list and sets
687 *dlt_buf. The caller is responsible for freeing the array. -1 is
688 returned on failure; otherwise, the number of data link types in the
689 array is returned.
690 pcap_set_datalink() is used to set the current data link type of the
692 pcap descriptor to the type specified by dlt. -1 is returned on fail‐
693 ure.
694 pcap_datalink_name_to_val() translates a data link type name, which is
696 a DLT_ name with the DLT_ removed, to the corresponding data link type
697 value. The translation is case-insensitive. -1 is returned on fail‐
698 ure.
699 pcap_datalink_val_to_name() translates a data link type value to the
701 corresponding data link type name. NULL is returned on failure.
702 pcap_datalink_val_to_description() translates a data link type value to
704 a short description of that data link type. NULL is returned on fail‐
705 ure.
706 pcap_snapshot() returns the snapshot length specified when
708 pcap_open_live() was called.
709 pcap_is_swapped() returns true if the current ``savefile'' uses a dif‐
711 ferent byte order than the current system.
712 pcap_major_version() returns the major number of the file format of the
714 savefile; pcap_minor_version() returns the minor number of the file
715 format of the savefile. The version number is stored in the header of
716 the savefile.
717 pcap_file() returns the standard I/O stream of the ``savefile,'' if a
719 ``savefile'' was opened with pcap_open_offline(), or NULL, if a network
720 device was opened with pcap_open_live().
721 pcap_stats() returns 0 and fills in the pcap_stat structure pointed to
723 by its second argument. The values represent packet statistics from
724 the start of the run to the time of the call. If there is an error or
725 the underlying packet capture doesn't support packet statistics, -1 is
726 returned and the error text can be obtained with pcap_perror() or
727 pcap_geterr(). pcap_stats() is supported only on live captures, not on
728 ``savefiles''; no statistics are stored in ``savefiles'', so no statis‐
729 tics are available when reading from a ``savefile''.
730 pcap_fileno() returns the file descriptor number from which captured
732 packets are read, if a network device was opened with pcap_open_live(),
733 or -1, if a ``savefile'' was opened with pcap_open_offline().
734 pcap_get_selectable_fd() returns, on UNIX, a file descriptor number for
736 a file descriptor on which one can do a select() or poll() to wait for
737 it to be possible to read packets without blocking, if such a descrip‐
738 tor exists, or -1, if no such descriptor exists. Some network devices
739 opened with pcap_open_live() do not support select() or poll() (for
740 example, regular network devices on FreeBSD 4.3 and 4.4, and Endace DAG
741 devices), so -1 is returned for those devices.
742 Note that on most versions of most BSDs (including Mac OS X) select()
744 and poll() do not work correctly on BPF devices;
745 pcap_get_selectable_fd() will return a file descriptor on most of those
746 versions (the exceptions being FreeBSD 4.3 and 4.4), a simple select()
747 or poll() will not return even after a timeout specified in
748 pcap_open_live() expires. To work around this, an application that
749 uses select() or poll() to wait for packets to arrive must put the
750 pcap_t in non-blocking mode, and must arrange that the select() or
751 poll() have a timeout less than or equal to the timeout specified in
752 pcap_open_live(), and must try to read packets after that timeout
753 expires, regardless of whether select() or poll() indicated that the
754 file descriptor for the pcap_t is ready to be read or not. (That work‐
755 around will not work in FreeBSD 4.3 and later; however, in FreeBSD 4.6
756 and later, select() and poll() work correctly on BPF devices, so the
757 workaround isn't necessary, although it does no harm.)
758 pcap_get_selectable_fd() is not available on Windows.
760 pcap_perror() prints the text of the last pcap library error on stderr,
762 prefixed by prefix.
763 pcap_geterr() returns the error text pertaining to the last pcap
765 library error. NOTE: the pointer it returns will no longer point to a
766 valid error message string after the pcap_t passed to it is closed; you
767 must use or copy the string before closing the pcap_t.
768 pcap_strerror() is provided in case strerror(1) isn't available.
770 pcap_lib_version() returns a pointer to a string giving information
772 about the version of the libpcap library being used; note that it con‐
773 tains more information than just a version number.
774 pcap_close() closes the files associated with p and deallocates
776 resources.
777 pcap_dump_file() returns the standard I/O stream of the ``savefile''
779 opened by pcap_dump_open().
780 pcap_dump_flush() flushes the output buffer to the ``savefile,'' so
782 that any packets written with pcap_dump() but not yet written to the
783 ``savefile'' will be written. -1 is returned on error, 0 on success.
784 pcap_dump_ftell() returns the current file position for the ``save‐
786 file'', representing the number of bytes written by pcap_dump_open()
787 and pcap_dump(). -1 is returned on error.
788 pcap_dump_close() closes the ``savefile.''
790
792 tcpdump(8), tcpslice(8)
793
795 The original authors are:
796 Van Jacobson, Craig Leres and Steven McCanne, all of the Lawrence
798 Berkeley National Laboratory, University of California, Berkeley, CA.
799 The current version is available from "The Tcpdump Group"'s Web site at
801 http://www.tcpdump.org/
803
805 Please send problems, bugs, questions, desirable enhancements, etc. to:
806 tcpdump-workers@tcpdump.org
808 Please send source code contributions, etc. to:
810 patches@tcpdump.org
812 27 February 2004 PCAP(3)