]> The Tcpdump Group git mirrors - libpcap/blob - pcap.3
9f19df3b0376881f0f8a309d40c9afc106b7f6db
[libpcap] / pcap.3
1 .\" @(#) $Header: /tcpdump/master/libpcap/Attic/pcap.3,v 1.58 2004-02-28 02:51:26 guy Exp $
2 .\"
3 .\" Copyright (c) 1994, 1996, 1997
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
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.
21 .\"
22 .TH PCAP 3 "27 February 2004"
23 .SH NAME
24 pcap \- Packet Capture library
25 .SH SYNOPSIS
26 .nf
27 .ft B
28 #include <pcap.h>
29 .ft
30 .LP
31 .nf
32 .ft B
33 char errbuf[PCAP_ERRBUF_SIZE];
34 .ft
35 .LP
36 .ft B
37 pcap_t *pcap_open_live(const char *device, int snaplen,
38 .ti +8
39 int promisc, int to_ms, char *errbuf)
40 pcap_t *pcap_open_dead(int linktype, int snaplen)
41 pcap_t *pcap_open_offline(const char *fname, char *errbuf)
42 pcap_dumper_t *pcap_dump_open(pcap_t *p, const char *fname)
43 .ft
44 .LP
45 .ft B
46 int pcap_setnonblock(pcap_t *p, int nonblock, char *errbuf);
47 int pcap_getnonblock(pcap_t *p, char *errbuf);
48 .ft
49 .LP
50 .ft B
51 int pcap_findalldevs(pcap_if_t **alldevsp, char *errbuf)
52 void pcap_freealldevs(pcap_if_t *alldevs)
53 char *pcap_lookupdev(char *errbuf)
54 int pcap_lookupnet(const char *device, bpf_u_int32 *netp,
55 .ti +8
56 bpf_u_int32 *maskp, char *errbuf)
57 .ft
58 .LP
59 .ft B
60 int pcap_dispatch(pcap_t *p, int cnt,
61 .ti +8
62 pcap_handler callback, u_char *user)
63 int pcap_loop(pcap_t *p, int cnt,
64 .ti +8
65 pcap_handler callback, u_char *user)
66 void pcap_dump(u_char *user, struct pcap_pkthdr *h,
67 .ti +8
68 u_char *sp)
69 .ft
70 .LP
71 .ft B
72 int pcap_compile(pcap_t *p, struct bpf_program *fp,
73 .ti +8
74 char *str, int optimize, bpf_u_int32 netmask)
75 int pcap_setfilter(pcap_t *p, struct bpf_program *fp)
76 void pcap_freecode(struct bpf_program *);
77 .ft
78 .LP
79 .ft B
80 const u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h)
81 int pcap_next_ex(pcap_t *p, struct pcap_pkthdr **pkt_header,
82 .ti +8
83 const u_char **pkt_data)
84 .ft
85 .LP
86 .ft B
87 void pcap_breakloop(pcap_t *)
88 .ft
89 .LP
90 .ft B
91 int pcap_datalink(pcap_t *p)
92 int pcap_list_datalinks(pcap_t *p, int **dlt_buf);
93 int pcap_set_datalink(pcap_t *p, int dlt);
94 int pcap_datalink_name_to_val(const char *name);
95 const char *pcap_datalink_val_to_name(int dlt);
96 const char *pcap_datalink_val_to_description(int dlt);
97 int pcap_snapshot(pcap_t *p)
98 int pcap_is_swapped(pcap_t *p)
99 int pcap_major_version(pcap_t *p)
100 int pcap_minor_version(pcap_t *p)
101 int pcap_stats(pcap_t *p, struct pcap_stat *ps)
102 FILE *pcap_file(pcap_t *p)
103 int pcap_fileno(pcap_t *p)
104 int pcap_get_selectable_fd(pcap_t *p);
105 void pcap_perror(pcap_t *p, char *prefix)
106 char *pcap_geterr(pcap_t *p)
107 char *pcap_strerror(int error)
108 const char *pcap_lib_version(void)
109 .ft
110 .LP
111 .ft B
112 void pcap_close(pcap_t *p)
113 int pcap_dump_flush(pcap_dumper_t *p)
114 FILE *pcap_dump_file(pcap_dumper_t *p)
115 void pcap_dump_close(pcap_dumper_t *p)
116 .ft
117 .fi
118 .SH DESCRIPTION
119 The Packet Capture library
120 provides a high level interface to packet capture systems. All packets
121 on the network, even those destined for other hosts, are accessible
122 through this mechanism.
123 .PP
124 .SH ROUTINES
125 NOTE:
126 .I errbuf
127 in
128 .BR pcap_open_live() ,
129 .BR pcap_open_dead() ,
130 .BR pcap_open_offline() ,
131 .BR pcap_setnonblock() ,
132 .BR pcap_getnonblock() ,
133 .BR pcap_findalldevs() ,
134 .BR pcap_lookupdev() ,
135 and
136 .B pcap_lookupnet()
137 is assumed to be able to hold at least
138 .B PCAP_ERRBUF_SIZE
139 chars.
140 .PP
141 .B pcap_open_live()
142 is used to obtain a packet capture descriptor to look
143 at packets on the network.
144 .I device
145 is a string that specifies the network device to open; on Linux systems
146 with 2.2 or later kernels, a
147 .I device
148 argument of "any" or
149 .B NULL
150 can be used to capture packets from all interfaces.
151 .I snaplen
152 specifies the maximum number of bytes to capture. If this value is less
153 than the size of a packet that is captured, only the first
154 .I snaplen
155 bytes of that packet will be captured and provided as packet data. A
156 value of 65535 should be sufficient, on most if not all networks, to
157 capture all the data available from the packet.
158 .I promisc
159 specifies if the interface is to be put into promiscuous mode.
160 (Note that even if this parameter is false, the interface
161 could well be in promiscuous mode for some other reason.) For now, this
162 doesn't work on the "any" device; if an argument of "any" or NULL is
163 supplied, the
164 .I promisc
165 flag is ignored.
166 .I to_ms
167 specifies the read timeout in milliseconds. The read timeout is used to
168 arrange that the read not necessarily return immediately when a packet
169 is seen, but that it wait for some amount of time to allow more packets
170 to arrive and to read multiple packets from the OS kernel in one
171 operation. Not all platforms support a read timeout; on platforms that
172 don't, the read timeout is ignored. A zero value for
173 .IR to_ms ,
174 on platforms that support a read timeout,
175 will cause a read to wait forever to allow enough packets to
176 arrive, with no timeout.
177 .I errbuf
178 is used to return error or warning text. It will be set to error text when
179 .B pcap_open_live()
180 fails and returns
181 .BR NULL .
182 .I errbuf
183 may also be set to warning text when
184 .B pcap_open_live()
185 succeds; to detect this case the caller should store a zero-length string in
186 .I errbuf
187 before calling
188 .B pcap_open_live()
189 and display the warning to the user if
190 .I errbuf
191 is no longer a zero-length string.
192 .PP
193 .B pcap_open_dead()
194 is used for creating a
195 .B pcap_t
196 structure to use when calling the other functions in libpcap. It is
197 typically used when just using libpcap for compiling BPF code.
198 .PP
199 .B pcap_open_offline()
200 is called to open a ``savefile'' for reading.
201 .I fname
202 specifies the name of the file to open. The file has
203 the same format as those used by
204 .B tcpdump(1)
205 and
206 .BR tcpslice(1) .
207 The name "-" in a synonym for
208 .BR stdin .
209 .I errbuf
210 is used to return error text and is only set when
211 .B pcap_open_offline()
212 fails and returns
213 .BR NULL .
214 .PP
215 .B pcap_dump_open()
216 is called to open a ``savefile'' for writing. The name "-" in a synonym
217 for
218 .BR stdout .
219 .B NULL
220 is returned on failure.
221 .I p
222 is a
223 .I pcap
224 struct as returned by
225 .B pcap_open_offline()
226 or
227 .BR pcap_open_live() .
228 .I fname
229 specifies the name of the file to open.
230 If
231 .B NULL
232 is returned,
233 .B pcap_geterr()
234 can be used to get the error text.
235 .PP
236 .B pcap_setnonblock()
237 puts a capture descriptor, opened with
238 .BR pcap_open_live() ,
239 into ``non-blocking'' mode, or takes it out of ``non-blocking'' mode,
240 depending on whether the
241 .I nonblock
242 argument is non-zero or zero. It has no effect on ``savefiles''.
243 If there is an error, \-1 is returned and
244 .I errbuf
245 is filled in with an appropriate error message; otherwise, 0 is
246 returned.
247 In
248 ``non-blocking'' mode, an attempt to read from the capture descriptor
249 with
250 .B pcap_dispatch()
251 will, if no packets are currently available to be read, return 0
252 immediately rather than blocking waiting for packets to arrive.
253 .B pcap_loop()
254 and
255 .B pcap_next()
256 will not work in ``non-blocking'' mode.
257 .PP
258 .B pcap_getnonblock()
259 returns the current ``non-blocking'' state of the capture descriptor; it
260 always returns 0 on ``savefiles''.
261 If there is an error, \-1 is returned and
262 .I errbuf
263 is filled in with an appropriate error message.
264 .PP
265 .B pcap_findalldevs()
266 constructs a list of network devices that can be opened with
267 .BR pcap_open_live() .
268 (Note that there may be network devices that cannot be opened with
269 .BR pcap_open_live()
270 by the
271 process calling
272 .BR pcap_findalldevs() ,
273 because, for example, that process might not have sufficient privileges
274 to open them for capturing; if so, those devices will not appear on the
275 list.)
276 .I alldevsp
277 is set to point to the first element of the list; each element of the
278 list is of type
279 .BR pcap_if_t ,
280 and has the following members:
281 .RS
282 .TP
283 .B next
284 if not
285 .BR NULL ,
286 a pointer to the next element in the list;
287 .B NULL
288 for the last element of the list
289 .TP
290 .B name
291 a pointer to a string giving a name for the device to pass to
292 .B pcap_open_live()
293 .TP
294 .B description
295 if not
296 .BR NULL ,
297 a pointer to a string giving a human-readable description of the device
298 .TP
299 .B addresses
300 a pointer to the first element of a list of addresses for the interface
301 .TP
302 .B flags
303 interface flags:
304 .RS
305 .TP
306 .B PCAP_IF_LOOPBACK
307 set if the interface is a loopback interface
308 .RE
309 .RE
310 .PP
311 Each element of the list of addresses is of type
312 .BR pcap_addr_t ,
313 and has the following members:
314 .RS
315 .TP
316 .B next
317 if not
318 .BR NULL ,
319 a pointer to the next element in the list;
320 .B NULL
321 for the last element of the list
322 .TP
323 .B addr
324 a pointer to a
325 .B "struct sockaddr"
326 containing an address
327 .TP
328 .B netmask
329 if not
330 .BR NULL ,
331 a pointer to a
332 .B "struct sockaddr"
333 that contains the netmask corresponding to the address pointed to by
334 .B addr
335 .TP
336 .B broadaddr
337 if not
338 .BR NULL ,
339 a pointer to a
340 .B "struct sockaddr"
341 that contains the broadcast address corresponding to the address pointed
342 to by
343 .BR addr ;
344 may be null if the interface doesn't support broadcasts
345 .TP
346 .B dstaddr
347 if not
348 .BR NULL ,
349 a pointer to a
350 .B "struct sockaddr"
351 that contains the destination address corresponding to the address pointed
352 to by
353 .BR addr ;
354 may be null if the interface isn't a point-to-point interface
355 .RE
356 .PP
357 .B \-1
358 is returned on failure, in which case
359 .B errbuf
360 is filled in with an appropriate error message;
361 .B 0
362 is returned on success.
363 .PP
364 .B pcap_freealldevs()
365 is used to free a list allocated by
366 .BR pcap_findalldevs() .
367 .PP
368 .B pcap_lookupdev()
369 returns a pointer to a network device suitable for use with
370 .B pcap_open_live()
371 and
372 .BR pcap_lookupnet() .
373 If there is an error,
374 .B NULL
375 is returned and
376 .I errbuf
377 is filled in with an appropriate error message.
378 .PP
379 .B pcap_lookupnet()
380 is used to determine the network number and mask
381 associated with the network device
382 .BR device .
383 Both
384 .I netp
385 and
386 .I maskp
387 are
388 .I bpf_u_int32
389 pointers.
390 A return of \-1 indicates an error in which case
391 .I errbuf
392 is filled in with an appropriate error message.
393 .PP
394 .B pcap_dispatch()
395 is used to collect and process packets.
396 .I cnt
397 specifies the maximum number of packets to process before returning.
398 This is not a minimum number; when reading a live capture, only one
399 bufferful of packets is read at a time, so fewer than
400 .I cnt
401 packets may be processed. A
402 .I cnt
403 of \-1 processes all the packets received in one buffer when reading a
404 live capture, or all the packets in the file when reading a
405 ``savefile''.
406 .I callback
407 specifies a routine to be called with three arguments:
408 a
409 .I u_char
410 pointer which is passed in from
411 .BR pcap_dispatch() ,
412 a
413 .I const struct pcap_pkthdr
414 pointer to a structure with the following members:
415 .RS
416 .TP
417 .B ts
418 a
419 .I struct timeval
420 containing the time when the packet was captured
421 .TP
422 .B caplen
423 a
424 .I bpf_u_int32
425 giving the number of bytes of the packet that are available from the
426 capture
427 .TP
428 .B len
429 a
430 .I bpf_u_int32
431 giving the length of the packet, in bytes (which might be more than the
432 number of bytes available from the capture, if the length of the packet
433 is larger than the maximum number of bytes to capture)
434 .RE
435 .PP
436 and a
437 .I const u_char
438 pointer to the first
439 .B caplen
440 (as given in the
441 .I struct pcap_pkthdr
442 a pointer to which is passed to the callback routine)
443 bytes of data from the packet (which won't necessarily be the entire
444 packet; to capture the entire packet, you will have to provide a value
445 for
446 .I snaplen
447 in your call to
448 .B pcap_open_live()
449 that is sufficiently large to get all of the packet's data - a value of
450 65535 should be sufficient on most if not all networks).
451 .PP
452 The number of packets read is returned.
453 0 is returned if no packets were read from a live capture (if, for
454 example, they were discarded because they didn't pass the packet filter,
455 or if, on platforms that support a read timeout that starts before any
456 packets arrive, the timeout expires before any packets arrive, or if the
457 file descriptor for the capture device is in non-blocking mode and no
458 packets were available to be read) or if no more packets are available
459 in a ``savefile.'' A return of \-1 indicates
460 an error in which case
461 .B pcap_perror()
462 or
463 .B pcap_geterr()
464 may be used to display the error text.
465 A return of \-2 indicates that the loop terminated due to a call to
466 .B pcap_breakloop()
467 before any packets were processed.
468 .ft B
469 If your application uses pcap_breakloop(),
470 make sure that you explicitly check for \-1 and \-2, rather than just
471 checking for a return value < 0.
472 .ft R
473 .PP
474 .BR NOTE :
475 when reading a live capture,
476 .B pcap_dispatch()
477 will not necessarily return when the read times out; on some platforms,
478 the read timeout isn't supported, and, on other platforms, the timer
479 doesn't start until at least one packet arrives. This means that the
480 read timeout should
481 .B NOT
482 be used in, for example, an interactive application, to allow the packet
483 capture loop to ``poll'' for user input periodically, as there's no
484 guarantee that
485 .B pcap_dispatch()
486 will return after the timeout expires.
487 .PP
488 .B pcap_loop()
489 is similar to
490 .B pcap_dispatch()
491 except it keeps reading packets until
492 .I cnt
493 packets are processed or an error occurs.
494 It does
495 .B not
496 return when live read timeouts occur.
497 Rather, specifying a non-zero read timeout to
498 .B pcap_open_live()
499 and then calling
500 .B pcap_dispatch()
501 allows the reception and processing of any packets that arrive when the
502 timeout occurs.
503 A negative
504 .I cnt
505 causes
506 .B pcap_loop()
507 to loop forever (or at least until an error occurs). \-1 is returned on
508 an error; 0 is returned if
509 .I cnt
510 is exhausted; \-2 is returned if the loop terminated due to a call to
511 .B pcap_breakloop()
512 before any packets were processed.
513 .ft B
514 If your application uses pcap_breakloop(),
515 make sure that you explicitly check for \-1 and \-2, rather than just
516 checking for a return value < 0.
517 .ft R
518 .PP
519 .B pcap_next()
520 reads the next packet (by calling
521 .B pcap_dispatch()
522 with a
523 .I cnt
524 of 1) and returns a
525 .I u_char
526 pointer to the data in that packet. (The
527 .I pcap_pkthdr
528 struct for that packet is not supplied.)
529 .B NULL
530 is returned if an error occured, or if no packets were read from a live
531 capture (if, for example, they were discarded because they didn't pass
532 the packet filter, or if, on platforms that support a read timeout that
533 starts before any packets arrive, the timeout expires before any packets
534 arrive, or if the file descriptor for the capture device is in
535 non-blocking mode and no packets were available to be read), or if no
536 more packets are available in a ``savefile.'' Unfortunately, there is
537 no way to determine whether an error occured or not.
538 .PP
539 .B pcap_next_ex()
540 reads the next packet and returns a success/failure indication:
541 .RS
542 .TP
543 1
544 the packet was read without problems
545 .TP
546 0
547 packets are being read from a live capture, and the timeout expired
548 .TP
549 \-1
550 an error occurred while reading the packet
551 .TP
552 \-2
553 packets are being read from a ``savefile'', and there are no more
554 packets to read from the savefile.
555 .RE
556 .PP
557 If the packet was read without problems, the pointer pointed to by the
558 .I pkt_header
559 argument is set to point to the
560 .I pcap_pkthdr
561 struct for the packet, and the
562 pointer pointed to by the
563 .I pkt_data
564 argument is set to point to the data in the packet.
565 .PP
566 .B pcap_breakloop()
567 sets a flag that will force
568 .B pcap_dispatch()
569 or
570 .B pcap_loop()
571 to return rather than looping; they will return the number of packets
572 that have been processed so far, or \-2 if no packets have been
573 processed so far.
574 .PP
575 This routine is safe to use inside a signal handler on UNIX or a console
576 control handler on Windows, as it merely sets a flag that is checked
577 within the loop.
578 .PP
579 The flag is checked in loops reading packets from the OS - a signal by
580 itself will not necessarily terminate those loops - as well as in loops
581 processing a set of packets returned by the OS.
582 .ft B
583 Note that if you are catching signals on UNIX systems that support
584 restarting system calls after a signal, and calling pcap_breakloop()
585 in the signal handler, you must specify, when catching those signals,
586 that system calls should NOT be restarted by that signal. Otherwise,
587 if the signal interrupted a call reading packets in a live capture,
588 when your signal handler returns after calling pcap_breakloop(), the
589 call will be restarted, and the loop will not terminate until more
590 packets arrive and the call completes.
591 .PP
592 Note also that, in a multi-threaded application, if one thread is
593 blocked in
594 .BR pcap_dispatch() ,
595 .BR pcap_loop() ,
596 .BR pcap_next() ,
597 or
598 .BR pcap_next_ex() ,
599 a call to
600 .B pcap_breakloop()
601 in a different thread will not unblock that thread; you will need to use
602 whatever mechanism the OS provides for breaking a thread out of blocking
603 calls in order to unblock the thread, such as thread cancellation in
604 systems that support POSIX threads.
605 .ft R
606 .PP
607 Note that
608 .B pcap_next()
609 will, on some platforms, loop reading packets from the OS; that loop
610 will not necessarily be terminated by a signal, so
611 .B pcap_breakloop()
612 should be used to terminate packet processing even if
613 .B pcap_next()
614 is being used.
615 .PP
616 .B pcap_breakloop()
617 does not guarantee that no further packets will be processed by
618 .B pcap_dispatch()
619 or
620 .B pcap_loop()
621 after it is called; at most one more packet might be processed.
622 .PP
623 If \-2 is returned from
624 .B pcap_dispatch()
625 or
626 .BR pcap_loop() ,
627 the flag is cleared, so a subsequent call will resume reading packets.
628 If a positive number is returned, the flag is not cleared, so a
629 subsequent call will return \-2 and clear the flag.
630 .PP
631 .B pcap_dump()
632 outputs a packet to the ``savefile'' opened with
633 .BR pcap_dump_open() .
634 Note that its calling arguments are suitable for use with
635 .B pcap_dispatch()
636 or
637 .BR pcap_loop() .
638 If called directly, the
639 .I user
640 parameter is of type
641 .I pcap_dumper_t
642 as returned by
643 .BR pcap_dump_open() .
644 .PP
645 .B pcap_compile()
646 is used to compile the string
647 .I str
648 into a filter program.
649 .I program
650 is a pointer to a
651 .I bpf_program
652 struct and is filled in by
653 .BR pcap_compile() .
654 .I optimize
655 controls whether optimization on the resulting code is performed.
656 .I netmask
657 specifies the IPv4 netmask of the network on which packets are being
658 captured; it is used only when checking for IPv4 broadcast addresses in
659 the filter program. If the netmask of the network on which packets are
660 being captured isn't known to the program, or if packets are being
661 captured on the Linux "any" pseudo-interface that can capture on more
662 than one network, a value of 0 can be supplied; tests for IPv4 broadcast
663 addreses won't be done correctly, but all other tests in the filter
664 program will be OK. A return of \-1 indicates an error in which case
665 .BR pcap_geterr()
666 may be used to display the error text.
667 .PP
668 .B pcap_compile_nopcap()
669 is similar to
670 .B pcap_compile()
671 except that instead of passing a pcap structure, one passes the
672 snaplen and linktype explicitly. It is intended to be used for
673 compiling filters for direct BPF usage, without necessarily having
674 called
675 .BR pcap_open() .
676 A return of \-1 indicates an error; the error text is unavailable.
677 .RB ( pcap_compile_nopcap()
678 is a wrapper around
679 .BR pcap_open_dead() ,
680 .BR pcap_compile() ,
681 and
682 .BR pcap_close() ;
683 the latter three routines can be used directly in order to get the error
684 text for a compilation error.)
685 .B
686 .PP
687 .B pcap_setfilter()
688 is used to specify a filter program.
689 .I fp
690 is a pointer to a
691 .I bpf_program
692 struct, usually the result of a call to
693 .BR pcap_compile() .
694 .B \-1
695 is returned on failure, in which case
696 .BR pcap_geterr()
697 may be used to display the error text;
698 .B 0
699 is returned on success.
700 .PP
701 .B pcap_freecode()
702 is used to free up allocated memory pointed to by a
703 .I bpf_program
704 struct generated by
705 .B pcap_compile()
706 when that BPF program is no longer needed, for example after it
707 has been made the filter program for a pcap structure by a call to
708 .BR pcap_setfilter() .
709 .PP
710 .B pcap_datalink()
711 returns the link layer type; link layer types it can return include:
712 .PP
713 .RS 5
714 .TP 5
715 .B DLT_NULL
716 BSD loopback encapsulation; the link layer header is a 4-byte field, in
717 .I host
718 byte order, containing a PF_ value from
719 .B socket.h
720 for the network-layer protocol of the packet.
721 .IP
722 Note that ``host byte order'' is the byte order of the machine on which
723 the packets are captured, and the PF_ values are for the OS of the
724 machine on which the packets are captured; if a live capture is being
725 done, ``host byte order'' is the byte order of the machine capturing the
726 packets, and the PF_ values are those of the OS of the machine capturing
727 the packets, but if a ``savefile'' is being read, the byte order and PF_
728 values are
729 .I not
730 necessarily those of the machine reading the capture file.
731 .TP 5
732 .B DLT_EN10MB
733 Ethernet (10Mb, 100Mb, 1000Mb, and up)
734 .TP 5
735 .B DLT_IEEE802
736 IEEE 802.5 Token Ring
737 .TP 5
738 .B DLT_ARCNET
739 ARCNET
740 .TP 5
741 .B DLT_SLIP
742 SLIP; the link layer header contains, in order:
743 .RS 10
744 .LP
745 a 1-byte flag, which is 0 for packets received by the machine and 1 for
746 packets sent by the machine;
747 .LP
748 a 1-byte field, the upper 4 bits of which indicate the type of packet,
749 as per RFC 1144:
750 .RS 5
751 .TP 5
752 0x40
753 an unmodified IP datagram (TYPE_IP);
754 .TP 5
755 0x70
756 an uncompressed-TCP IP datagram (UNCOMPRESSED_TCP), with that byte being
757 the first byte of the raw IP header on the wire, containing the
758 connection number in the protocol field;
759 .TP 5
760 0x80
761 a compressed-TCP IP datagram (COMPRESSED_TCP), with that byte being the
762 first byte of the compressed TCP/IP datagram header;
763 .RE
764 .LP
765 for UNCOMPRESSED_TCP, the rest of the modified IP header, and for
766 COMPRESSED_TCP, the compressed TCP/IP datagram header;
767 .RE
768 .RS 5
769 .LP
770 for a total of 16 bytes; the uncompressed IP datagram follows the header.
771 .RE
772 .TP 5
773 .B DLT_PPP
774 PPP; if the first 2 bytes are 0xff and 0x03, it's PPP in HDLC-like
775 framing, with the PPP header following those two bytes, otherwise it's
776 PPP without framing, and the packet begins with the PPP header.
777 .TP 5
778 .B DLT_FDDI
779 FDDI
780 .TP 5
781 .B DLT_ATM_RFC1483
782 RFC 1483 LLC/SNAP-encapsulated ATM; the packet begins with an IEEE 802.2
783 LLC header.
784 .TP 5
785 .B DLT_RAW
786 raw IP; the packet begins with an IP header.
787 .TP 5
788 .B DLT_PPP_SERIAL
789 PPP in HDLC-like framing, as per RFC 1662, or Cisco PPP with HDLC
790 framing, as per section 4.3.1 of RFC 1547; the first byte will be 0xFF
791 for PPP in HDLC-like framing, and will be 0x0F or 0x8F for Cisco PPP
792 with HDLC framing.
793 .TP 5
794 .B DLT_PPP_ETHER
795 PPPoE; the packet begins with a PPPoE header, as per RFC 2516.
796 .TP 5
797 .B DLT_C_HDLC
798 Cisco PPP with HDLC framing, as per section 4.3.1 of RFC 1547.
799 .TP 5
800 .B DLT_IEEE802_11
801 IEEE 802.11 wireless LAN
802 .TP 5
803 .B DLT_FRELAY
804 Frame Relay
805 .TP 5
806 .B DLT_LOOP
807 OpenBSD loopback encapsulation; the link layer header is a 4-byte field, in
808 .I network
809 byte order, containing a PF_ value from OpenBSD's
810 .B socket.h
811 for the network-layer protocol of the packet.
812 .IP
813 Note that, if a ``savefile'' is being read, those PF_ values are
814 .I not
815 necessarily those of the machine reading the capture file.
816 .TP 5
817 .B DLT_LINUX_SLL
818 Linux "cooked" capture encapsulation; the link layer header contains, in
819 order:
820 .RS 10
821 .LP
822 a 2-byte "packet type", in network byte order, which is one of:
823 .RS 5
824 .TP 5
825 0
826 packet was sent to us by somebody else
827 .TP 5
828 1
829 packet was broadcast by somebody else
830 .TP 5
831 2
832 packet was multicast, but not broadcast, by somebody else
833 .TP 5
834 3
835 packet was sent by somebody else to somebody else
836 .TP 5
837 4
838 packet was sent by us
839 .RE
840 .LP
841 a 2-byte field, in network byte order, containing a Linux ARPHRD_ value
842 for the link layer device type;
843 .LP
844 a 2-byte field, in network byte order, containing the length of the
845 link layer address of the sender of the packet (which could be 0);
846 .LP
847 an 8-byte field containing that number of bytes of the link layer header
848 (if there are more than 8 bytes, only the first 8 are present);
849 .LP
850 a 2-byte field containing an Ethernet protocol type, in network byte
851 order, or containing 1 for Novell 802.3 frames without an 802.2 LLC
852 header or 4 for frames beginning with an 802.2 LLC header.
853 .RE
854 .TP 5
855 .B DLT_LTALK
856 Apple LocalTalk; the packet begins with an AppleTalk LLAP header.
857 .TP 5
858 .B DLT_PFLOG
859 OpenBSD pflog; the link layer header contains, in order:
860 .RS 10
861 .LP
862 a 4-byte PF_ value, in network byte order;
863 .LP
864 a 16-character interface name;
865 .LP
866 a 2-byte rule number, in network byte order;
867 .LP
868 a 2-byte reason code, in network byte order, which is one of:
869 .RS 5
870 .TP 5
871 0
872 match
873 .TP 5
874 1
875 bad offset
876 .TP 5
877 2
878 fragment
879 .TP 5
880 3
881 short
882 .TP 5
883 4
884 normalize
885 .TP 5
886 memory
887 .RE
888 .LP
889 a 2-byte action code, in network byte order, which is one of:
890 .RS 5
891 .TP 5
892 0
893 passed
894 .TP 5
895 1
896 dropped
897 .TP 5
898 2
899 scrubbed
900 .RE
901 .LP
902 a 2-byte direction, in network byte order, which is one of:
903 .RS 5
904 .TP 5
905 0
906 incoming or outgoing
907 .TP 5
908 1
909 incoming
910 .TP 5
911 2
912 outgoing
913 .RE
914 .RE
915 .TP 5
916 .B DLT_PRISM_HEADER
917 Prism monitor mode information followed by an 802.11 header.
918 .TP 5
919 .B DLT_IP_OVER_FC
920 RFC 2625 IP-over-Fibre Channel, with the link-layer header being the
921 Network_Header as described in that RFC.
922 .TP 5
923 .B DLT_SUNATM
924 SunATM devices; the link layer header contains, in order:
925 .RS 10
926 .LP
927 a 1-byte flag field, containing a direction flag in the uppermost bit,
928 which is set for packets transmitted by the machine and clear for
929 packets received by the machine, and a 4-byte traffic type in the
930 low-order 4 bits, which is one of:
931 .RS 5
932 .TP 5
933 0
934 raw traffic
935 .TP 5
936 1
937 LANE traffic
938 .TP 5
939 2
940 LLC-encapsulated traffic
941 .TP 5
942 3
943 MARS traffic
944 .TP 5
945 4
946 IFMP traffic
947 .TP 5
948 5
949 ILMI traffic
950 .TP 5
951 6
952 Q.2931 traffic
953 .RE
954 .LP
955 a 1-byte VPI value;
956 .LP
957 a 2-byte VCI field, in network byte order.
958 .RE
959 .TP 5
960 .B DLT_IEEE802_11_RADIO
961 link-layer information followed by an 802.11 header - see
962 http://www.shaftnet.org/~pizza/software/capturefrm.txt for a description
963 of the link-layer information.
964 .TP 5
965 .B DLT_ARCNET_LINUX
966 ARCNET, with no exception frames, reassembled packets rather than raw
967 frames, and an extra 16-bit offset field between the destination host
968 and type bytes.
969 .TP 5
970 .B DLT_LINUX_IRDA
971 Linux-IrDA packets, with a
972 .B DLT_LINUX_SLL
973 header followed by the IrLAP header.
974 .RE
975 .PP
976 .B pcap_list_datalinks()
977 is used to get a list of the supported data link types of the interface
978 associated with the pcap descriptor.
979 .B pcap_list_datalinks()
980 allocates an array to hold the list and sets
981 .IR *dlt_buf .
982 The caller is responsible for freeing the array.
983 .B \-1
984 is returned on failure;
985 otherwise, the number of data link types in the array is returned.
986 .PP
987 .B pcap_set_datalink()
988 is used to set the current data link type of the pcap descriptor
989 to the type specified by
990 .IR dlt .
991 .B \-1
992 is returned on failure.
993 .PP
994 .B pcap_datalink_name_to_val()
995 translates a data link type name, which is a
996 .B DLT_
997 name with the
998 .B DLT_
999 removed, to the corresponding data link type value. The translation
1000 is case-insensitive.
1001 .B \-1
1002 is returned on failure.
1003 .PP
1004 .B pcap_datalink_val_to_name()
1005 translates a data link type value to the corresponding data link type
1006 name. NULL is returned on failure.
1007 .PP
1008 .B pcap_datalink_val_to_description()
1009 translates a data link type value to a short description of that data
1010 link type. NULL is returned on failure.
1011 .PP
1012 .B pcap_snapshot()
1013 returns the snapshot length specified when
1014 .B pcap_open_live()
1015 was called.
1016 .PP
1017 .B pcap_is_swapped()
1018 returns true if the current ``savefile'' uses a different byte order
1019 than the current system.
1020 .PP
1021 .B pcap_major_version()
1022 returns the major number of the file format of the savefile;
1023 .B pcap_minor_version()
1024 returns the minor number of the file format of the savefile. The
1025 version number is stored in the header of the savefile.
1026 .PP
1027 .B pcap_file()
1028 returns the standard I/O stream of the ``savefile,'' if a ``savefile''
1029 was opened with
1030 .BR pcap_open_offline() ,
1031 or NULL, if a network device was opened with
1032 .BR pcap_open_live() .
1033 .PP
1034 .B pcap_stats()
1035 returns 0 and fills in a
1036 .B pcap_stat
1037 struct. The values represent packet statistics from the start of the
1038 run to the time of the call. If there is an error or the underlying
1039 packet capture doesn't support packet statistics, \-1 is returned and
1040 the error text can be obtained with
1041 .B pcap_perror()
1042 or
1043 .BR pcap_geterr() .
1044 .B pcap_stats()
1045 is supported only on live captures, not on ``savefiles''; no statistics
1046 are stored in ``savefiles'', so no statistics are available when reading
1047 from a ``savefile''.
1048 .PP
1049 .B pcap_fileno()
1050 returns the file descriptor number from which captured packets are read,
1051 if a network device was opened with
1052 .BR pcap_open_live() ,
1053 or \-1, if a ``savefile'' was opened with
1054 .BR pcap_open_offline() .
1055 .PP
1056 .B pcap_get_selectable_fd()
1057 returns, on UNIX, a file descriptor number for a file descriptor on
1058 which one can
1059 do a
1060 .B select()
1061 or
1062 .B poll()
1063 to wait for it to be possible to read packets without blocking, if such
1064 a descriptor exists, or \-1, if no such descriptor exists. Some network
1065 devices opened with
1066 .B pcap_open_live()
1067 do not support
1068 .B select()
1069 or
1070 .B poll()
1071 (for example, regular network devices on FreeBSD 4.3 and 4.4, and Endace
1072 DAG devices), so \-1 is returned for those devices.
1073 .PP
1074 Note that on most versions of most BSDs (including Mac OS X)
1075 .B select()
1076 and
1077 .B poll()
1078 do not work correctly on BPF devices;
1079 .B pcap_get_selectable_fd()
1080 will return a file descriptor on most of those versions (the exceptions
1081 being FreeBSD 4.3 and 4.4), a simple
1082 .B select()
1083 or
1084 .B poll()
1085 will not return even after a timeout specified in
1086 .B pcap_open_live()
1087 expires. To work around this, an application that uses
1088 .B select()
1089 or
1090 .B poll()
1091 to wait for packets to arrive must put the
1092 .B pcap_t
1093 in non-blocking mode, and must arrange that the
1094 .B select()
1095 or
1096 .B poll()
1097 have a timeout less than or equal to the timeout specified in
1098 .BR pcap_open_live() ,
1099 and must try to read packets after that timeout expires, regardless of
1100 whether
1101 .B select()
1102 or
1103 .B poll()
1104 indicated that the file descriptor for the
1105 .B pcap_t
1106 is ready to be read or not. (That workaround will not work in FreeBSD
1107 4.3 and later; however, in FreeBSD 4.6 and later,
1108 .B select()
1109 and
1110 .B poll()
1111 work correctly on BPF devices, so the workaround isn't necessary,
1112 although it does no harm.)
1113 .PP
1114 .B pcap_get_selectable_fd()
1115 is not available on Windows.
1116 .PP
1117 .B pcap_perror()
1118 prints the text of the last pcap library error on
1119 .BR stderr ,
1120 prefixed by
1121 .IR prefix .
1122 .PP
1123 .B pcap_geterr()
1124 returns the error text pertaining to the last pcap library error.
1125 .BR NOTE :
1126 the pointer it returns will no longer point to a valid error message
1127 string after the
1128 .B pcap_t
1129 passed to it is closed; you must use or copy the string before closing
1130 the
1131 .BR pcap_t .
1132 .PP
1133 .B pcap_strerror()
1134 is provided in case
1135 .BR strerror (1)
1136 isn't available.
1137 .PP
1138 .B pcap_lib_version()
1139 returns a pointer to a string giving information about the version of
1140 the libpcap library being used; note that it contains more information
1141 than just a version number.
1142 .PP
1143 .B pcap_close()
1144 closes the files associated with
1145 .I p
1146 and deallocates resources.
1147 .PP
1148 .B pcap_dump_file()
1149 returns the standard I/O stream of the ``savefile'' opened by
1150 .BR pcap_dump_open().
1151 .PP
1152 .B pcap_dump_flush()
1153 flushes the output buffer to the ``savefile,'' so that any packets
1154 written with
1155 .B pcap_dump()
1156 but not yet written to the ``savefile'' will be written.
1157 .B \-1
1158 is returned on error, 0 on success.
1159 .PP
1160 .B pcap_dump_close()
1161 closes the ``savefile.''
1162 .PP
1163 .SH SEE ALSO
1164 tcpdump(1), tcpslice(1)
1165 .SH AUTHORS
1166 The original authors are:
1167 .LP
1168 Van Jacobson,
1169 Craig Leres and
1170 Steven McCanne, all of the
1171 Lawrence Berkeley National Laboratory, University of California, Berkeley, CA.
1172 .LP
1173 The current version is available from "The Tcpdump Group"'s Web site at
1174 .LP
1175 .RS
1176 .I http://www.tcpdump.org/
1177 .RE
1178 .SH BUGS
1179 Please send problems, bugs, questions, desirable enhancements, etc. to:
1180 .LP
1181 .RS
1182 tcpdump-workers@tcpdump.org
1183 .RE
1184 .LP
1185 Please send source code contributions, etc. to:
1186 .LP
1187 .RS
1188 patches@tcpdump.org
1189 .RE