Skip to main content
Version: v23.09

Part 1: Introduction And Basics

Library structure

As you could probably already notice, PcapPlusPlus is built of 3 libraries: Common++, Packet++ and Pcap++. Let's describes the purposes of each one and its main classes:


A library for parsing, creating and editing packets of various supported protocols. This library can be used stand-alone and doesn't depend on Pcap++, libpcap/WinPcap/Npcap, etc. Main classes and utilities:

  1. RawPacket - representing the raw data captured from the network
  2. Layer - the base class for all protocol layers. Each protocol layer is in-charge of parsing the specific bytes in the packet that belong to this protocol
  3. Packet - representing a packet that was parsed by the different PcapPlusPlus protocol parsers and contains the different protocol layers
  4. Protocol layers (for example: EthLayer, IPv4Layer, IPv6Layer, TcpLayer, UdpLayer, DnsLayer, HttpRequestLayer, HttpResponseLayer, PayloadLayer, etc.) - classes representing specific protocol parsers. All inherit the Layer class
  5. PacketUtils - a class containing several widely used utilities such as calculating a hash value based on 5-tuple or 2-tuple
  6. TcpReassembly - a class for providing TCP reassembly (a.k.a TCP reconstruction) of TCP streams
  7. IPv4Reassembly - a class for providing IPv4 reassembly (a.k.a IPv4 de-fragmentation) of IPv4 packets


A library for intercepting and sending packets, providing network and NIC info, stats, etc. This library is mostly a C++ wrapper for packet capturing engines such as libpcap, WinPcap, Npcap, DPDK and PF_RING, but also provide some unique features and capabilities that doesn't exist in any of these engines. Main classes and utilities:

  1. PcapLiveDevice - representing a Linux/MacOS/FreeBSD network interface and enables capturing and sending packets as well as retrieving interface information. Also available for rooted Android devices
  2. WinPcapLiveDevice - representing a Windows network interface and contains all functionality exposed in PcapLiveDevice. This class actually inherits PcapLiveDevice and does the relevant adjustments for WinPcap/Npcap and Windows OS
  3. DpdkDevice - representing a DPDK-enabled network interface and wraps DPDK basic functionality for capturing and sending packets as well as retrieving interface information
  4. PfRingDevice - representing PF_RING-enabled network interface and wraps PF_RING functionality for capturing and sending packets as well as retrieving interface information
  5. PcapRemoteDevice - representing a network interface on a remote machine and enables to capture and send packets on this interface using the rpcap protocol. This class actually wraps WinPcap's Remote Capture capabilities and so available only on Windows
  6. pcap and pcap-ng file readers and writers (PcapFileReaderDevice, PcapFileWriterDevice, PcapNgFileReaderDevice, PcapNgFileWriterDevice, IFileReaderDevice, IFileWriterDevice)
  7. Packet filtering engine - a C++ API for the BPF (Berkeley Packet Filter) format for easy-to-use packet filtering from a network interface or pcap/pcap-ng file
  8. NetworkUtils - a class containing common and basic actions requiring network interaction such as discovery of a remote machine MAC address by sending ARP requests, discovery of IPv4 address from a host-name (by sending DNS requests), and so on


A library containing common code utilities and classes used by both Packet++ and Pcap++. Main classes and utilities:

  1. IPv4Address, IPv6Address - classes representing IPv4 and IPv6 addresses accordingly
  2. MacAddress - a class representing a MAC (Ethernet) address
  3. IpUtils.h - all kinds of helpful network utilities
  4. LoggerPP - a simple logging infrastructure used widely in PcapPlusPlus
  5. SystemUtils.h - several useful utilities for interaction with the operating system

Packets and Layers

Parsing and crafting of packets is one of the fundamentals of PcapPlusPlus and the heart of the Packet++ library. We'll dive deep into it later, but first let's understand the basic structures as everything else is built on that.

Raw packets vs. Parsed packets

There are 2 types of packets in PcapPlusPlus: raw packets and parsed packets. A raw packet is the raw byte-stream that was captured from the network together with the timestamp it was captured on. A raw packet doesn't contain any data about the protocols it's built from and of course protocol data can't be added, removed or edited. On the other hand, parsed packets are packets that contain all protocol data and can be edited per protocol. This reveals one of the core functionalities of PcapPlusPlus: taking raw packets that were captured from the network and create parsed packets out of them, meaning identifying their protocols, saving meta data about these protocols, and allowing the user easy access to all of this parsed data for both reading and writing (edit, add data and remove data).


A layer in PcapPlusPlus means protocol layer. Parsed packets contain layers, each one represents a protocol the packet is built from. For example: an HTTP packet may contain an Ethernet layer, an IPv4 (or IPv6) layer, a TCP layer and an HTTP layer. Each supported protocol is represented by a corresponding layer class. A layer class exposes the protocol's data for the user to read and usually also to write or modify. For example: A TCP layer exposes all TCP fields like ports, flags, sequence numbers, TCP options, etc. and also allows editing of all of those fields and also adding/removing/editing TCP options. Layers inside a parsed packet are ordered in a link list so the parsed packet actually points only to the first (lowest) layer (for example: Ethernet), this layer points to the next layer (for example: IPv4), and so on. A list of all supported protocols (and layers) can be found here.

Packet and Layers schematic structure

In the following diagram you can see the relations between RawPackets, (parsed) Packets and Layers:

Packets and Layers

As can be seen in this diagram, a Packet (= parsed packet) holds a pointer to the RawPacket object and to the first (lowest) Layer. Each Layer has pointers to the next layer and to the previous one.

It may be implied from this structure that the actual packet data (the raw byte stream) is duplicated between the raw packet and the various layers. This is not the case. We don't want to duplicate the data from various reasons:

  • We don't want the packet object to take up too much memory
  • We would like the avoid unnecessary data coping because it's expensive
  • Since each layer can be edited, we would like the edited data to be written directly to the byte stream and not copied from one place to another

So the raw byte stream is actually stored once, in the RawPacket object. The various layers only point to the relevant place where their data begins. Here is a diagram to visualize it:

Layers and Raw Data

As you can see in this diagram, each layer points to the place in the raw data where its data starts. In this example: Ethernet Layer points to the beginning of the raw data because it is the first layer, so it actually sees all the raw data. On the other hand, IPv4 Layer points to the place where IPv4 data begins so it doesn't see the Ethernet data. UDP Layer points to the place where UDP data starts so it doesn't see the Ethernet and IPv4 data, and so on.

All of these structures and pointers are built by PcapPlusPlus packet parsing engine residing in the Packet class. When a Packet object is created it is given a RawPacket object (which is created by the capturing engine) and the parsing process begins by understanding which protocols the packet is built of and creating the relevant Layer objects. Another option is to create an "empty" Packet object which doesn't contain any raw data and start building the layers ourselves. In that case a RawPacket object will be created and gradually built.

Packet capture engines

Capturing and sending packets is another fundamental principal in PcapPlusPlus and is the heart of the Pcap++ library. The idea is to provide a simple, easy-to-use and as similar as possible interface to capture and send packets from different types of packet capture engines. Different types can be files (pcap/pcap-ng), network interfaces via libpcap/WinPcap/Npcap, DPDK-enabled interfaces, PF_RING-enabled interfaces, etc. This is not always easy because the APIs and work-flows of the different engines is sometimes very different from one another and it's difficult to keep one flow who suits them all. Also, many of the engine have specific OS and platform requirements, and this is also a challenge. The engine families currently supported are:

  • Files (pcap and pcap-ng)
  • Network interfaces using libpcap or WinPcap/Npcap
  • DPDK-enabled interfaces
  • PF_RING-enabled interfaces
  • Remote packet capture

Each packet capture engine is represented in PcapPlusPlus in a class called "Device". All devices inherit from a common abstract parent class called IPcapDevice which contains a few capabilities that are common for most devices such as opening/closing the device, gathering packet statistics, setting a filter, etc. The rest is implemented in each class.

The next parts of the tutorial will dive deep into the various device types and explain how to use them.

Writing a simple app

Creating applications using PcapPlusPlus is easy. Let's have a guided tour demonstrating how to create a simple application and its CMakeLists.txt.

First let's make sure PcapPlusPlus is configured and built successfully. Please follow the download page for building instructions.

Another option is to download a pre-compiled version of PcapPlusPlus, please download the latest release for your platform and follow the instructions on how to configure and install it.

Now that PcapPlusPlus is installed on our system we're ready to start writing some code!

So let's write this code in main.cpp:

#include <iostream>
#include <IPv4Layer.h>
#include <Packet.h>
#include <PcapFileDevice.h>

int main(int argc, char* argv[])
// open a pcap file for reading
pcpp::PcapFileReaderDevice reader("1_packet.pcap");
if (!
std::cerr << "Error opening the pcap file" << std::endl;
return 1;

// read the first (and only) packet from the file
pcpp::RawPacket rawPacket;
if (!reader.getNextPacket(rawPacket))
std::cerr << "Couldn't read the first packet in the file" << std::endl;
return 1;

// parse the raw packet into a parsed packet
pcpp::Packet parsedPacket(&rawPacket);

// verify the packet is IPv4
if (parsedPacket.isPacketOfType(pcpp::IPv4))
// extract source and dest IPs
pcpp::IPv4Address srcIP = parsedPacket.getLayerOfType<pcpp::IPv4Layer>()->getSrcIPv4Address();
pcpp::IPv4Address destIP = parsedPacket.getLayerOfType<pcpp::IPv4Layer>()->getDstIPv4Address();

// print source and dest IPs
<< "Source IP is '" << srcIP << "'; "
<< "Dest IP is '" << destIP << "'"
<< std::endl;

// close the file

return 0;

This code does the following:

  1. Opens a pcap file ("1_packet.pcap") containing only 1 packet
  2. Reads the packet
  3. Parses the packet (converting it from RawPacket to Packet)
  4. Extracts the IPv4 layer
  5. Reads the source and destination IPs and prints them to console

This code is rather simple. Now let's write a CMakeLists.txt file to build this app:

cmake_minimum_required(VERSION 3.12)


add_executable("${PROJECT_NAME}" main.cpp)

find_package(PcapPlusPlus REQUIRED)

# We want to have the binary compiled in the same folder as the code

target_link_libraries("${PROJECT_NAME}" PUBLIC PcapPlusPlus::Pcap++)

Now that we have the code and the CMakeLists.txt we can build and run the code. Here is the output:

Source IP is ''; Dest IP is ''

Running the code

All code that was covered in this tutorial can be found here. In order to compile and run the code please choose one of these options:

Option 1: Install a pre-compiled version of PcapPlusPlus

You can download and install PcapPlusPlus using one of the options mentioned in the installation page.

Once installed, download all of the files in the tutorial folder and run CMake:

cmake -S . -B build
cmake --build build

The executable will be created in the same directory.

  1. If you're running on Windows with MinGW you need to run cmake with -G "MinGW Makefiles"
  2. If PcapPlusPlus is NOT installed in the default directory you may need to specify CMAKE_PREFIX_PATH, for example:
    CMAKE_PREFIX_PATH=/my/pcapplusplus/path cmake -S . -B build
    Or on Windows:
    set CMAKE_PREFIX_PATH=C:\my\pcapplusplus\path
    cmake -S . -B build
  3. On Windows you may also need to specify Npcap/WinPcap path in CMAKE_PREFIX_PATH, for example:
    set CMAKE_PREFIX_PATH=C:\my\pcapplusplus\path;C:\my\npcap\path
    cmake -S . -B build

Option 2: build the tutorials with PcapPlusPlus

If you're building PcapPlusPlus from source and would like to build the tutorials as well you can use the -DPCAPPP_BUILD_TUTORIALS=ON option. Please refer to the build from source page for more details (choose your platform page).