How the-tcpdump-group/tcpdump works
1. What this repository is
This is the source tree for tcpdump, a native C command-line packet analyzer. Its core job is to read captured packets from libpcap and render human-readable protocol dissections. The repo is mostly one executable plus a large set of protocol decoder modules.
2. Primary runtime flow
The main data path is: packet capture source → libpcap → tcpdump core → protocol dispatch → protocol-specific printers → text output. tcpdump does not own packet capture itself; it relies on libpcap for capture file reading, live capture, link-layer decoding support, and platform-specific capture APIs.
3. Entry point and orchestration
tcpdump.c is the program entry and command-line driver. It handles option parsing, capture source setup, snapshot/verbosity/filter behavior, and overall packet-processing loop. It coordinates the session and delegates the actual decoding of each packet to lower-level dissection code.
4. Dissection framework
The architectural center is the netdissect layer: netdissect.h, netdissect.c, print.c, print.h, util-print.c, and related support files. This layer defines the packet-dissection context, output helpers, bounds checking, and common formatting utilities that every protocol printer uses.
5. Protocol decoder subsystem
Most of the tree consists of print-*.c modules, each responsible for one protocol, encapsulation, or link type. Examples include Ethernet, IPv4/IPv6, TCP/UDP, MPLS, PPP, VLAN, VXLAN, BGP, OSPF, DNS, NFS, and many more. These modules are selected by the dispatch layer based on link type and protocol headers, then recursively decode nested encapsulations.
6. Shared protocol definitions
The many .h files at the top level provide shared packet structure definitions, constants, and helper declarations for protocol families such as IP, TCP, UDP, GRE, MPLS, NTP, SMB, RPC, and link-layer types. These headers form the shared contract between the generic dissection engine and the individual printers.
7. Safety and parsing boundaries
A major architectural concern is defensive parsing of untrusted packet data. Files like netdissect-alloc.c, signature.c, checksum.c, in_cksum.c, and numerous bounds- and formatting-related helpers support careful length checks and safe output. The many regression tests with names like oobr, heapoverflow, seg-fault, and invalid-length reflect that robustness is a first-class boundary.
8. Portability layer
The tree includes portability shims under missing/ and platform notes under doc/. These compatibility sources replace or normalize libc/platform functions such as getopt_long, strlcpy, strlcat, and strsep when the host OS lacks them. This makes the same decoder code build across Unix variants, macOS, Windows, and others.
9. Build and configuration architecture
The project supports both Autotools and CMake-based builds. Files like configure.ac, Makefile.in, CMakeLists.txt, and cmake/Modules/Find*.cmake define feature detection for dependencies such as libpcap, OpenSSL/crypto, and SMI. This is a classic native-system build, not an application framework stack.
10. Test and verification subsystem
The tests/ directory is a large golden-output suite: packet captures (.pcap/.pcapng) paired with expected text outputs (.out). The tests verify decoding correctness across many protocols, link types, and malformed inputs. Architecturally, this is a regression harness around the dissection engine rather than a unit-test-per-function design.
11. Generated and release-support files
Files such as VERSION, CHANGES, INSTALL.md, and various *.in, *.awk, and helper scripts support packaging, release engineering, and ancillary trace-processing tasks. They are not part of the packet-processing runtime path, but they influence how the binary is produced and validated.
12. External boundary and operational context
The only major external runtime dependency is libpcap; everything else is largely self-contained C code. The tool is designed for offline analysis of capture files and live packet monitoring on supported OSes, with platform integration handled through the build system and libpcap rather than through internal service components.
Main entry points: netdissect.c netdissect · print-ip.c IP stack · print.c dispatch · tcpdump.c tcpdump
Components 18
Runtime path
Packet capture, dispatch, decoding, and text rendering
- tcpdump · Program entry point, option handling, capture setup, and packet-processing loop
tcpdump.c - libpcap · Capture-file and live-capture backend relied on by tcpdump
Protocol decoders
Representative protocol printer modules and dispatch helpers
- dispatch · Selects link-type and protocol-specific printers, then recurses into nested encapsulations
print.c - link types · Representative link-layer decoders such as Ethernet, PPP, VLAN, MPLS, and loopback
print-ether.c - IP stack · IPv4, IPv6, TCP, UDP, ICMP, fragments, and related protocol demuxing
print-ip.c - tunnels · GRE, VXLAN, Geneve, ERSPAN, L2TP, and similar encapsulation decoders
print-gre.c - routing · BGP, OSPF, IS-IS, RIP, PIM, RSVP, LDP, and other routing protocol decoders
print-bgp.c - services · DNS, DHCP, HTTP, NFS, SMB, SNMP, RADIUS, SIP, SSH, TFTP, and similar service decoders
print-domain.c
Shared support
Common parsing, safety, portability, and shared definitions
- netdissect · Dissection context, bounds checks, and shared output helpers
netdissect.c - print core · Common formatting and printer orchestration used by protocol modules
print.c - util print · Shared text-rendering helpers for protocol printers
util-print.c - alloc/safety · Memory and parsing support for defensive handling of packet data
netdissect-alloc.c - checksums · Checksum and integrity helpers used by several decoders
checksum.c - protocol headers · Top-level .h files defining packet structures, constants, and printer contracts
ip.h - helper sources · Common address conversion, string formatting, name lookup, and protocol utility code
addrtoname.c
Build and verification
Build systems, portability shims, and regression assets
- missing shims · Portable replacements for libc and OS-specific functions
missing/getopt_long.c - build system · Autotools and CMake configuration, feature detection, and packaging support
CMakeLists.txt - tests · Capture fixtures and expected outputs for regression and malformed-input coverage
tests/TESTLIST
Connections 20
- tcpdump → libpcap: uses · Reads packets and capture files through libpcap
- tcpdump → netdissect: initializes · Creates and configures the dissection context
- tcpdump → dispatch: drives · Feeds captured packets into decoder dispatch
- dispatch → link types: selects · Dispatches by link type and framing
- link types → IP stack: nests into · Hands off to network and transport decoders
- IP stack → tunnels: unwraps · Decodes tunneled or encapsulated payloads
- IP stack → routing: decodes · Prints routing and control-plane protocols
- IP stack → services: decodes · Prints application and service protocols
- dispatch → print core: formats via · Uses the shared output pipeline
- print core → util print: calls · Relies on common text-formatting helpers
- print core → helper sources: uses · Depends on address and name formatting utilities
- netdissect → alloc/safety: uses · Shares safe allocation and parsing support
- netdissect → checksums: uses · Performs integrity checks while decoding packets
- netdissect → protocol headers: declares · Defines shared packet and context interfaces
- helper sources → protocol headers: depends on · Uses protocol and address-family definitions
- missing shims → build system: enabled by · Selected through platform feature detection
- build system → libpcap: finds · Locates required external capture library
- build system → tests: verifies · Builds and runs regression coverage
- tests → dispatch: checks · Validates decoder behavior against captures and expected text
- tests → netdissect: stresses · Exercises bounds checks and malformed-input handling