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