JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 1 | @(#) $Header: /tcpdump/master/libpcap/README,v 1.34 2008-12-14 19:44:14 guy Exp $ (LBL) |
The Android Open Source Project | 478ab6c | 2009-03-03 19:30:05 -0800 | [diff] [blame] | 2 | |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 3 | LIBPCAP 1.x.y |
The Android Open Source Project | 478ab6c | 2009-03-03 19:30:05 -0800 | [diff] [blame] | 4 | |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 5 | www.tcpdump.org |
The Android Open Source Project | 478ab6c | 2009-03-03 19:30:05 -0800 | [diff] [blame] | 6 | |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 7 | Please send inquiries/comments/reports to: |
| 8 | tcpdump-workers@lists.tcpdump.org |
The Android Open Source Project | 478ab6c | 2009-03-03 19:30:05 -0800 | [diff] [blame] | 9 | |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 10 | Anonymous Git is available via: |
| 11 | git clone git://bpf.tcpdump.org/libpcap |
The Android Open Source Project | 478ab6c | 2009-03-03 19:30:05 -0800 | [diff] [blame] | 12 | |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 13 | Please submit patches by forking the branch on GitHub at |
| 14 | |
| 15 | http://github.com/the-tcpdump-group/libpcap/tree/master |
| 16 | |
| 17 | and issuing a pull request. |
The Android Open Source Project | 478ab6c | 2009-03-03 19:30:05 -0800 | [diff] [blame] | 18 | |
| 19 | formerly from Lawrence Berkeley National Laboratory |
| 20 | Network Research Group <libpcap@ee.lbl.gov> |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 21 | ftp://ftp.ee.lbl.gov/old/libpcap-0.4a7.tar.Z |
The Android Open Source Project | 478ab6c | 2009-03-03 19:30:05 -0800 | [diff] [blame] | 22 | |
| 23 | This directory contains source code for libpcap, a system-independent |
| 24 | interface for user-level packet capture. libpcap provides a portable |
| 25 | framework for low-level network monitoring. Applications include |
| 26 | network statistics collection, security monitoring, network debugging, |
| 27 | etc. Since almost every system vendor provides a different interface |
| 28 | for packet capture, and since we've developed several tools that |
| 29 | require this functionality, we've created this system-independent API |
| 30 | to ease in porting and to alleviate the need for several |
| 31 | system-dependent packet capture modules in each application. |
| 32 | |
The Android Open Source Project | 478ab6c | 2009-03-03 19:30:05 -0800 | [diff] [blame] | 33 | For some platforms there are README.{system} files that discuss issues |
| 34 | with the OS's interface for packet capture on those platforms, such as |
| 35 | how to enable support for that interface in the OS, if it's not built in |
| 36 | by default. |
| 37 | |
| 38 | The libpcap interface supports a filtering mechanism based on the |
| 39 | architecture in the BSD packet filter. BPF is described in the 1993 |
| 40 | Winter Usenix paper ``The BSD Packet Filter: A New Architecture for |
| 41 | User-level Packet Capture''. A compressed PostScript version can be |
| 42 | found at |
| 43 | |
| 44 | ftp://ftp.ee.lbl.gov/papers/bpf-usenix93.ps.Z |
| 45 | |
| 46 | or |
| 47 | |
| 48 | http://www.tcpdump.org/papers/bpf-usenix93.ps.Z |
| 49 | |
| 50 | and a gzipped version can be found at |
| 51 | |
| 52 | http://www.tcpdump.org/papers/bpf-usenix93.ps.gz |
| 53 | |
| 54 | A PDF version can be found at |
| 55 | |
| 56 | http://www.tcpdump.org/papers/bpf-usenix93.pdf |
| 57 | |
| 58 | Although most packet capture interfaces support in-kernel filtering, |
| 59 | libpcap utilizes in-kernel filtering only for the BPF interface. |
| 60 | On systems that don't have BPF, all packets are read into user-space |
| 61 | and the BPF filters are evaluated in the libpcap library, incurring |
| 62 | added overhead (especially, for selective filters). Ideally, libpcap |
| 63 | would translate BPF filters into a filter program that is compatible |
| 64 | with the underlying kernel subsystem, but this is not yet implemented. |
| 65 | |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 66 | BPF is standard in 4.4BSD, BSD/OS, NetBSD, FreeBSD, OpenBSD, DragonFly |
| 67 | BSD, and Mac OS X; an older, modified and undocumented version is |
| 68 | standard in AIX. {DEC OSF/1, Digital UNIX, Tru64 UNIX} uses the |
| 69 | packetfilter interface but has been extended to accept BPF filters |
| 70 | (which libpcap utilizes). Also, you can add BPF filter support to |
| 71 | Ultrix using the kernel source and/or object patches available in: |
The Android Open Source Project | 478ab6c | 2009-03-03 19:30:05 -0800 | [diff] [blame] | 72 | |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 73 | http://www.tcpdump.org/other/bpfext42.tar.Z |
The Android Open Source Project | 478ab6c | 2009-03-03 19:30:05 -0800 | [diff] [blame] | 74 | |
| 75 | Linux, in the 2.2 kernel and later kernels, has a "Socket Filter" |
| 76 | mechanism that accepts BPF filters; see the README.linux file for |
| 77 | information on configuring that option. |
| 78 | |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 79 | Note to Linux distributions and *BSD systems that include libpcap: |
The Android Open Source Project | 478ab6c | 2009-03-03 19:30:05 -0800 | [diff] [blame] | 80 | |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 81 | There's now a rule to make a shared library, which should work on Linux |
| 82 | and *BSD, among other platforms. |
| 83 | |
| 84 | It sets the soname of the library to "libpcap.so.1"; this is what it |
| 85 | should be, *NOT* libpcap.so.1.x or libpcap.so.1.x.y or something such as |
| 86 | that. |
| 87 | |
| 88 | We've been maintaining binary compatibility between libpcap releases for |
| 89 | quite a while; there's no reason to tie a binary linked with libpcap to |
| 90 | a particular release of libpcap. |
| 91 | |
| 92 | Problems, bugs, questions, desirable enhancements, etc. should be sent |
| 93 | to the address "tcpdump-workers@lists.tcpdump.org". Bugs, support |
| 94 | requests, and feature requests may also be submitted on the GitHub issue |
| 95 | tracker for libpcap at |
| 96 | |
| 97 | https://github.com/the-tcpdump-group/libpcap/issues |
The Android Open Source Project | 478ab6c | 2009-03-03 19:30:05 -0800 | [diff] [blame] | 98 | |
| 99 | Source code contributions, etc. should be sent to the email address |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 100 | above or submitted by forking the branch on GitHub at |
The Android Open Source Project | 478ab6c | 2009-03-03 19:30:05 -0800 | [diff] [blame] | 101 | |
JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 102 | http://github.com/the-tcpdump-group/libpcap/tree/master |
| 103 | |
| 104 | and issuing a pull request. |
| 105 | |
| 106 | Current versions can be found at www.tcpdump.org. |
The Android Open Source Project | 478ab6c | 2009-03-03 19:30:05 -0800 | [diff] [blame] | 107 | |
| 108 | - The TCPdump team |