doc/guides/prog_guide/pcapng_lib.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2021 Microsoft Corporation
   3
   4 Packet Capture Next Generation Library
   5 ======================================
   6
   7 Exchanging packet traces becomes more and more critical every day.
   8 The de facto standard for this is the format defined by libpcap;
   9 but that format is rather old and is lacking in functionality
  10 for more modern applications.
  11 The `Pcapng file format`_ is the default capture file format
  12 for modern network capture processing tools
  13 such as `wireshark`_ (can also be read by `tcpdump`_).
  14
  15 The Pcapng library is an API for formatting packet data
  16 into a Pcapng file.
  17 The format conforms to the current `Pcapng RFC`_ standard.
  18 It is designed to be integrated with the packet capture library.
  19
  20 Usage
  21 -----
  22
  23 The output stream is created with ``rte_pcapng_fdopen``,
  24 and should be closed with ``rte_pcapng_close``.
  25
  26 The library requires a DPDK mempool to allocate mbufs.
  27 The mbufs need to be able to accommodate additional space
  28 for the pcapng packet format header and trailer information;
  29 the function ``rte_pcapng_mbuf_size`` should be used
  30 to determine the lower bound based on MTU.
  31
  32 Collecting packets is done in two parts.
  33 The function ``rte_pcapng_copy`` is used to format and copy mbuf data
  34 and ``rte_pcapng_write_packets`` writes a burst of packets to the output file.
  35
  36 The function ``rte_pcapng_write_stats`` can be used
  37 to write statistics information into the output file.
  38 The summary statistics information is automatically added
  39 by ``rte_pcapng_close``.
  40
  41 .. _Tcpdump: https://tcpdump.org/
  42 .. _Wireshark: https://wireshark.org/
  43 .. _Pcapng file format: https://github.com/pcapng/pcapng/
  44 .. _Pcapng RFC: https://datatracker.ietf.org/doc/html/draft-tuexen-opsawg-pcapng