|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | DESCRIPTION | FILE FORMAT | INSTRUCTION FORMAT | TLV FORMAT | SOFTWARE SUPPORT | SEE ALSO | COLOPHON |
|
|
|
CBPF-SAVEFILE(5) File Formats Manual CBPF-SAVEFILE(5)
cbpf-savefile - cBPF savefile format (work in progress, DRAFT
revision 7)
This man page discusses a file format for cBPF, which is the
"classic" (and for a long time the only) Berkeley Packet Filter.
It does NOT apply to the newer "extended" variety of BPF (eBPF).
The main purpose of this file format is to store BPF bytecode,
most commonly compiled from a BPF filter expression (see
pcap-filter(7) for the filter syntax description) using libpcap.
Besides that, the format allows to encode some information about
the context in which the compilation was done. This meta-data can
make it easier to reproduce the compilation later if required.
cBPF savefile design is based on the file format proposed by C.S.
Peron in 2005.
Unless stated otherwise, in the following specification integer
fields are big-endian unsigned, string fields do not use NUL
character for termination or padding.
A savefile consists of a fixed-size header and a variable-size
body as follows:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 0xA1 | 0xB2 | 0xC3 | 0xCB |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 'c' | 'B' | 'P' | 'F' |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| MajorVer=1 | MinorVer | Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| SnapLen |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| LinkTypeValue | InstructionCount=n |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| instruction 1 |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| instruction 2 |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| instruction n |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| optional trailing TLV space |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The first four octets contain a fixed signature, also known as a
magic number, to make it easy to identify the file type
automatically. The next four octets contain the ASCII string
"cBPF" to provide a hint for manual identification.
MajorVer and MinorVer
Contain the major and the minor version numbers of this format
respectively. The current major version is 1 and the current
minor version is 0. Format changes that do not impact
compatibility (e.g., new TLV types or flags) increment the minor
version only. Other format changes increment the major version
and reset the minor version to 0. All format versions have the
first part of the header up to and including MinorVer identical.
Flags
b15 b14 b13 b12 b11 b10 b09 b08 b07 b06 b05 b04 b03 b02 b01 b00
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| reserved |RND|CPX|COP|XOR|MOD|
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
MOD, XOR, COP, CPX and RND: if set to 1, in this BPF dialect
BPF_MOD, BPF_XOR, BPF_COP, BPF_COPX and BPF_RND respectively are
valid instructions. For the current list of OSes that support
BPF_MOD and BPF_XOR in the kernel see the % and ^ binary operators
in pcap-filter(7). BPF_COP and BPF_COPX are implemented in NetBSD
kernel. BPF_RND is implemented in OpenBSD kernel.
Note that the fact an instruction is valid in a BPF dialect does
not always mean the compiled bytecode in the savefile contains the
instruction. In other words, the purpose of the flags above is
not to provide a digest of the file contents, but to enable
conclusive automatic verification of the bytecode if required by
the use case.
SnapLen
Contains the snapshot length used for the compilation, usually
this is the snaplen input argument to pcap_open_dead(3PCAP) or
pcap_set_snaplen(3PCAP).
LinkTypeValue
Contains the link-layer header type value used for the
compilation, usually this is either the linktype input argument to
pcap_open_dead() or the dlt input argument to
pcap_set_datalink(3PCAP) or the value(s) returned by
pcap_datalink(3PCAP) and pcap_list_datalinks(3PCAP). Although
these functions take and return link-layer header type values via
the int C type, by convention only the low 16 bits are in use.
InstructionCount
This is the last field of the fixed header in major version 1, it
contains the number of bytecode instructions following the header.
By convention, valid BPF bytecode always ends with a ret
instruction, so in a valid savefile this field value is at least
1.
The file format thus far minimizes the overhead for software that
uses the BPF bytecode. If there is any data after the last
instruction, it is the trailing TLV space, which mostly contains
meta-data for human interpretation. It contains TLVs in the
format specified below.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| opcode | jt | jf |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| k |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
This is the traditional encoding of a BPF instruction (a 4-tuple
of integers). Note that usually the endianness depends on the
machine, but in this format it is fixed. Some opcodes interpret k
as a signed integer.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Type | Length=m |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
~ Value (m octets) ~
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
All TLVs are optional. Every TLV may appear in the same savefile
at most once. Length value does not include Type and Length.
Code points for Type and the associated Length constraints are
defined below.
EOF TLV
Allows to mark the end of TLV space (hence of the savefile)
explicitly to make it clear that the file is not truncated. If
this TLV is present in the TLV space, it may appear the last only.
Type is 0, Length is 0, Value is empty.
LinkTypeName TLV
Allows to record the input argument to
pcap_datalink_name_to_val(3PCAP) if the latter was used to
translate a DLT name into LinkTypeValue (the same name can
sometimes produce different values in different contexts).
Type is 1, Length is variable, Value contains an ASCII string.
Filter TLV
Allows to record the filter expression that was compiled into the
bytecode, usually this is the str input argument to
pcap_compile(3PCAP).
Type is 2, Length is variable, Value contains an ASCII string.
OptReq TLV
Allows to record whether optimization was requested for the
compilation or not, usually this is the optimize input argument to
pcap_compile(). Note that some link-layer header types and filter
keywords disable the optimization automatically in libpcap.
Type is 3, Length is 1, Value contains 1 or 0.
Netmask TLV
Allows to record the value of netmask input argument to
pcap_compile().
Type is 4, Length is 4, Value contains a 32-bit IPv4 netmask.
Comment TLV
Allows to record a free-form text, for example, the name and
version of the program that generated the file.
Type is 5, Length is variable, Value contains a UTF-8 string.
Timestamp TLV
Allows to record when the compilation was performed.
Type is 6, Length is 8, Value contains a 64-bit Unix timestamp.
BPF Exam at https://www.tcpdump.org/bpfexam/ can produce a cBPF
savefile from user input.
pcap-savefile(5)
This page is part of the libpcap (packet capture library) project.
Information about the project can be found at
⟨http://www.tcpdump.org/⟩. If you have a bug report for this
manual page, see ⟨http://www.tcpdump.org/#patches⟩. This page was
obtained from the project's upstream Git repository
⟨https://github.com/the-tcpdump-group/libpcap.git⟩ on 2025-08-11.
(At that time, the date of the most recent commit that was found
in the repository was 2025-08-10.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
9 February 2025 CBPF-SAVEFILE(5)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|