Introduction

Table of Contents
What is libpcapnav?
How does it work?

Welcome! You're looking at the manual for libpcapnav. Thanks for reading this.


What is libpcapnav?

libpcapnav is a libpcap wrapper library that allows navigation to arbitrary locations in a tcpdump trace file between reads. The API is intentionally much like that of the pcap library. You can navigate in trace files both in time and space: you can jump to a packet which is at appr. 2/3 of the trace, or you can jump as closely as possible to a packet with a given timestamp, and then read packets from there. In addition, the API provides convenience functions for manipulating timeval structures.

Like libpcap, this library handles things through an opaque handle struct. For trace file navigation and reading packets, this handle is enough. If you need to apply BPF filters or write packets to disk, you can access the familiar pcap handle that is used internally.


How does it work?

At the core of libpcapnav is the ability to resynchronize to the sequence of packets contained in a tcpdump trace file at arbitrary location of the file position indicator. The algorithm is based on Vern Paxson's method from the the tcpslice tool, that basically works as follows: the point near which the file position indicator is to be synchronized with the packet sequence is undershot a little bit, as it is much easier to scan forwards to the desired location, once the packet sequence has been detected. The file is scanned from that initial offset in single-byte steps, at each step assuming a libpcap packet header is present and sanity-checking the values read. Several checks analyze this potential header for sane timestamps, capture lengths etc. If the header appears valid, the next packet header is examined in a similar function, based upon the offset that the checked header provides. If a sequence of three packets seems valid, the algorithm considers the file position pointer to be synchronized with the packet flow and scans as closely as possible to the desired location. If the synchronization point is supposed to be a packet with a given timestamp, some interpolation is done and the process repeated, until the packet closest to the desired timestamp has been found.

libpcapnav's algorithm contains a few modifications that are explained in gory detail in the Netdude Freenix paper, and briefly listed here: