Main Content

write

Write protocol packet data to PCAP or PCAPNG file

Since R2020b

collapse all in page

    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.

    example

    Examples

    collapse all

    Open Live Script

    Create a PCAP file writer object, specifying the name of the PCAP file. Specify the Bluetooth low energy (LE) link type.

    pcapObj = pcapWriter('FileName','writeBluetoothLEpacket');
bleLinkType = 251;

    Write a global header to the PCAP file.

    writeGlobalHeader(pcapObj,bleLinkType);

    Specify the Bluetooth LE link layer (LL) packet.

    llpacket = '42BC13E206120E00050014010A001F0040001700170000007D47C0';

    Write Bluetooth LE LL packet to the PCAP file.

    timestamp = 129100;                 % Packet arrival time in POSIX® microseconds elapsed since 1/1/1970
write(pcapObj,llpacket,timestamp);
    Open Live Script

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

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

    Write an interface description block for Bluetooth LE.

    interfaceName = 'Bluetooth LE interface';
bleLinkType = 251;
interfaceId = writeInterfaceDescriptionBlock(pcapngObj,bleLinkType, ...
    interfaceName);

    Specify the Bluetooth LE LL packet.

    llpacket = '42BC13E206120E00050014010A001F0040001700170000007D47C0';

    Write Bluetooth LE LL packet to the PCAPNG format file.

    timestamp = 0;                                  % Packet arrival time in POSIX® microseconds elapsed since 1/1/1970
packetComment = 'This is Bluetooth LE packet';
write(pcapngObj, llpacket,timestamp,interfaceId,'PacketComment', ...
    packetComment);

    Input Arguments

    collapse all

    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.

    PCAP file writer object, specified as a pcapWriter object.

    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

    Packet arrival time in POSIX® microseconds elapsed since 1/1/1970, specified as a nonnegative integer.

    Data Types: double

    PCAPNG file writer object, specified as a pcapngWriter object.

    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' sets the format of the protocol packets to 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

    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

    See Also

    Functions

    Objects