write

Write protocol packet data to PCAP or PCAPNG file

Since R2020b

Syntax

write(pcapObj,packet,timestamp)

write(pcapngObj,packet,timestamp,interfaceID)

write(___,Name,Value)

Description

write(pcapObj,packet,timestamp) writes the protocol packet data to the PCAP file specified in the PCAP file writer object, pcapObj. Input packet specifies the protocol packet and input timestamp specifies the packet arrival time.

write(pcapngObj,packet,timestamp,interfaceID) writes protocol packet data to a PCAPNG file specified in the PCAPNG file writer object, pcapngObj. Input packet, timestamp, and interfaceID specifies the protocol packet, packet arrival time, and interface identifier, respectively.

write(___,Name,Value) specifies options using one or more name-value pair arguments in addition to the input argument combinations from any of the previous syntaxes. For example, 'PacketFormat','bits' sets the format of the protocol packets to bits.

Examples

Write 5G NR Packet Data to PCAP File

Create a PCAP file writer object, specifying the name of the PCAP file.

pcapObj = pcapWriter('FileName','write5GNRpacket');
timestamp = 300;                                           % Timestamp

5G NR packets do not have a valid link type. As per Tcpdump, if a valid link type is not present, specify the link type of SLL packet.

linkType = 113;

Write a global header to the PCAP file.

writeGlobalHeader(pcapObj,linkType);

5G NR packets are not directly supported by Wireshark. To enable Wireshark to parse 5G NR packets, add encapsulation and metadata to the 5G NR packet.

payload = [59; 205];                                       % MAC subPDU (contains truncated buffer status report (BSR) control element)
radioType = 1;                                             % Frequency division duplexing
linkDir = 0;                                               % Uplink packet
rntiType = 3;                                              % Cell-RNTI
startString = [109; 97; 99; 45; 110; 114];                 % Tag to indicate start of NR MAC signature
payloadTag = 1;                                            % Payload tag for NR packets
signature = [startString; radioType; linkDir; rntiType];
macNRInfoPacket = [signature; payloadTag; payload];

Construct a user datagram protocol (UDP) header.

udpPacketLength = 8 + length(macNRInfoPacket);             % Length of header (8 bytes) and payload
udpHeader = [163; 76;                                      % Source port number
    39; 15;                                                % Destination port number
    fix(udpPacketLength/256); mod(udpPacketLength,256);    % Total length of UDP packet
    0; 0];                                                 % Checksum

Construct an IPv4 header.

ipPacketLength = 20 + udpPacketLength;                     % Length of header (20 bytes) and payload
ipHeader = [69;                                            % Version of IP protocol and priority or traffic class
    0;                                                     % Type of service
    fix(ipPacketLength/256); mod(ipPacketLength,256);      % Total length of the IPv4 packet
    0; 1;                                                  % Identification
    0; 0;                                                  % Flags and fragmentation offset
    64;                                                    % Time to live in seconds
    17;                                                    % UDP protocol number
    0; 0;                                                  % Header checksum
    127; 0; 0; 1;                                          % Source IP address
    127; 0; 0; 1];                                         % Destination IP address

Construct an SLL header.

sllHeader = [0; 0;                                         % Packet type
    3; 4;                                                  % Address resolution protocol hardware (ARPHRD) type
    0; 0;                                                  % Link layer address length
    0; 0; 0; 0; 0; 0; 0; 0;                                % Link layer address
    8; 0];                                                 % Protocol type

Construct an 5G NR packet by adding encapsulation and metadata.

packet = [sllHeader; ipHeader; udpHeader; macNRInfoPacket];

Write the 5G NR packet data to the PCAP file.

write(pcapObj,packet,timestamp);

Write 5G NR Packet Data to PCAPNG File

Create a PCAPNG file writer object, specifying the name of the PCAPNG file.

pcapngObj = pcapngWriter('FileName','write5GNRpacket');

Write the interface block for 5G New Radio (NR). 5G NR packets do not have a valid link type. As per Tcpdump, if a valid link type is not present, specify the link type of SLL packet.

interface = '5GNR';                                        % Interface name
linkType = 113;                                            % Link type of SLL packet
timestamp = 300;                                           % Timestamp
interfaceID = writeInterfaceDescriptionBlock(pcapngObj,linkType,interface);

5G NR packets are not directly supported by Wireshark. To enable Wireshark to parse 5G NR packets, add encapsulation and metadata to the 5G NR packet.

payload = [59; 205];                                       % MAC subPDU (contains short truncated buffer status report (BSR) control element)
radioType = 1;                                             % Frequency division duplexing
linkDir = 0;                                               % Uplink packet
rntiType = 3;                                              % Cell-RNTI
startString = [109; 97; 99; 45; 110; 114];                 % Tag to indicate the start of NR MAC signature
payloadTag = 1;                                            % Payload tag for NR packets
signature = [startString; radioType; linkDir; rntiType];
macNRInfoPacket = [signature; payloadTag; payload];

Construct a UDP header.

udpPacketLength = 8 + length(macNRInfoPacket);             % Length of header (8 bytes) and payload
udpHeader = [163; 76;                                      % Source port number
    39; 15;                                                % Destination port number
    fix(udpPacketLength/256); mod(udpPacketLength,256);    % Total length of UDP packet
    0; 0];                                                 % Checksum

Construct an IPv4 header.

ipPacketLength = 20 + udpPacketLength;                     % Length of header (20 bytes) and payload
ipHeader = [69;                                            % Version of IP protocol and Priority or Traffic Class
    0;                                                     % Type of service
    fix(ipPacketLength/256);mod(ipPacketLength,256);       % Total length of the IPv4 packet
    0; 1;                                                  % Identification
    0; 0;                                                  % Flags and fragmentation offset
    64;                                                    % Time to live in seconds
    17;                                                    % UDP protocol number
    0; 0;                                                  % Header checksum
    127; 0; 0; 1;                                          % Source IP address
    127; 0; 0; 1];                                         % Destination IP address

Construct an SLL header.

sllHeader = [0;0;                                          % Packet type
    3; 4;                                                  % Address resolution protocol hardware (ARPHRD) type
    0; 0;                                                  % Link layer address length
    0; 0; 0; 0; 0; 0; 0; 0;                                % Link layer address
    8; 0];                                                 % Protocol type

Construct an 5G NR packet by adding encapsulation and metadata.

packet = [sllHeader; ipHeader; udpHeader; macNRInfoPacket];

Write the 5G NR packet data to the PCAPNG file.

packetComment = 'This is 5G NR MAC packet';                % Packet comment
write(pcapngObj,packet,timestamp,interfaceID,'PacketComment',packetComment);

Input Arguments

Note

The pcapWriter and pcapngWriter objects do not overwrite the existing PCAP or PCAPNG files, respectively. Each time when you create these objects, specify a unique PCAP or PCAPNG file name.

pcapObj — PCAP file writer object

pcapWriter object

PCAP file writer object, specified as a pcapWriter object.

packet — Protocol packet

binary-valued vector | character vector | string scalar | numeric vector | n-by-2 character array

Protocol packet, specified as one of these values.

• Binary-valued vector – This value represents bits.

• Character vector – This value represents octets in hexadecimal format.

• String scalar – This value represents octets in hexadecimal format.

• Numeric vector with each element in the range [0, 255] – This value represents octets in decimal format.

• n-by-2 character array – In this value, each row represents an octet in hexadecimal format.

Data Types: char | string | double

timestamp — Packet arrival time

nonnegative integer

Packet arrival time, specified as a nonnegative integer. The units are in POSIX^® microseconds or nanoseconds elapsed since January 1, 1970. In the case of a PCAP file writer object, the unit of timestamp depends on the timeResolution argument of the writeGlobalHeader function. For a PCAPNG file writer object, the unit of timestamp depends on the timeResolution argument of the writeInterfaceDescriptionBlock function.

Data Types: double

pcapngObj — PCAPNG file writer object

pcapngWriter object

PCAPNG file writer object, specified as a pcapngWriter object.

interfaceID — Unique identifier for an interface

nonnegative scalar

Unique identifier for an interface, specified as a nonnegative scalar.

Data Types: double

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'PacketFormat','bits' specifies the format of the protocol packet as bits.

PacketFormat — Format of the protocol packet

'octets' (default) | 'bits'

Format of the protocol packet, specified as the comma-separated pair consisting of PacketFormat and 'octets' or 'bits'. If this value is specified as 'octets', packet is specified as one of these values.

• Binary-valued vector – This value represents bits.

• Character vector – This value represents octets in hexadecimal format.

• String scalar – This value represents octets in hexadecimal format.

• Numeric vector with each element in the range [0, 255] – This value represents octets in decimal format.

• n-by-2 character array – In this value, each row represents an octet in hexadecimal format.

Data Types: char | string | double

PacketComment — Comment for protocol packet

'' (default) | character vector | string scalar

Comment for the protocol packet, specified as the comma-separated pair consisting of PacketComment and a character vector or a string scalar.

Dependencies

To enable this name-value pair argument, specify the pcapngObj input argument.

Data Types: char | string

References

[1] Tuexen, M. “PCAP Next Generation (Pcapng) Capture File Format.” 2020. https://www.ietf.org/.

[2] Group, The Tcpdump. “Tcpdump/Libpcap Public Repository.” Accessed May 20, 2020. https://www.tcpdump.org.

[3] “Development/LibpcapFileFormat - The Wireshark Wiki.” Accessed May 20, 2020. https://www.wireshark.org.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2020b