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 define 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 a 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 Before the library can be used, the function ``rte_pcapng_init``
  24 should be called once to initialize timestamp computation.
  25
  26 The output stream is created with ``rte_pcapng_fdopen``,
  27 and should be closed with ``rte_pcapng_close``.
  28
  29 The library requires a DPDK mempool to allocate mbufs.
  30 The mbufs need to be able to accommodate additional space
  31 for the pcapng packet format header and trailer information;
  32 the function ``rte_pcapng_mbuf_size`` should be used
  33 to determine the lower bound based on MTU.
  34
  35 Collecting packets is done in two parts.
  36 The function ``rte_pcapng_copy`` is used to format and copy mbuf data
  37 and ``rte_pcapng_write_packets`` writes a burst of packets to the output file.
  38
  39 The function ``rte_pcapng_write_stats`` can be used
  40 to write statistics information into the output file.
  41 The summary statistics information is automatically added
  42 by ``rte_pcapng_close``.
  43
  44 .. _Tcpdump: https://tcpdump.org/
  45 .. _Wireshark: https://wireshark.org/
  46 .. _Pcapng file format: https://github.com/pcapng/pcapng/
  47 .. _Pcapng RFC: https://datatracker.ietf.org/doc/html/draft-tuexen-opsawg-pcapng