PcapFileEx.PcapWriter (pcap_file_ex v0.5.5)

View Source

PCAP file writer module.

Provides functions to create PCAP files and write packets to them.

Examples

# Create a new PCAP file
header = %PcapFileEx.Header{
  version_major: 2,
  version_minor: 4,
  snaplen: 65535,
  datalink: "ethernet",
  ts_resolution: "microsecond",
  endianness: "little"
}

{:ok, writer} = PcapFileEx.PcapWriter.open("output.pcap", header)

# Write packets
:ok = PcapFileEx.PcapWriter.write_packet(writer, packet)

# Close when done
:ok = PcapFileEx.PcapWriter.close(writer)

Limitations

  • Append mode not supported: The underlying pcap-file crate does not support appending to existing PCAP files. Use PcapNgWriter for append support (future).
  • Thread safety: Each writer instance should be used from a single process.

For batch writes, see write_all/3.

Summary

Types

t()

Functions

append(path)

Opens an existing PCAP file for appending (NOT SUPPORTED).

close(pcap_writer)

Closes the PCAP writer and flushes any buffered data.

open(path, header)

Opens a new PCAP file for writing.

open!(path, header)

Opens a new PCAP file for writing, raising on error.

write_all(path, header, packets)

Writes all packets from an enumerable to a new PCAP file.

write_packet(pcap_writer, packet)

Writes a single packet to the PCAP file.

Types

t()

@type t() :: %PcapFileEx.PcapWriter{
  header: PcapFileEx.Header.t(),
  path: String.t(),
  reference: reference()
}

Functions

append(path)

@spec append(Path.t()) :: {:error, String.t()}

Opens an existing PCAP file for appending (NOT SUPPORTED).

PCAP append mode is not supported by the pcap-file crate. This function always returns an error. Create a new file instead, or use PCAPNG format which will support append in a future version.

Returns

  • {:error, reason} - Always returns error explaining limitation

close(pcap_writer)

@spec close(t()) :: :ok | {:error, String.t()}

Closes the PCAP writer and flushes any buffered data.

After calling this function, the writer handle should not be used again.

Parameters

  • writer - Writer handle from open/2

Returns

  • :ok - Writer closed successfully
  • {:error, reason} - Close failed

Examples

:ok = PcapFileEx.PcapWriter.close(writer)

open(path, header)

@spec open(Path.t(), PcapFileEx.Header.t()) :: {:ok, t()} | {:error, String.t()}

Opens a new PCAP file for writing.

Creates the file and writes the PCAP header. Returns a writer handle.

Parameters

  • path - Path to the PCAP file to create
  • header - PCAP header configuration

Returns

  • {:ok, writer} - Writer handle for subsequent operations
  • {:error, reason} - File creation failed

Examples

header = %PcapFileEx.Header{
  version_major: 2,
  version_minor: 4,
  snaplen: 65535,
  datalink: "ethernet",
  ts_resolution: "microsecond",
  endianness: "little"
}

{:ok, writer} = PcapFileEx.PcapWriter.open("output.pcap", header)

open!(path, header)

@spec open!(Path.t(), PcapFileEx.Header.t()) :: t()

Opens a new PCAP file for writing, raising on error.

See open/2 for details.

Examples

header = %PcapFileEx.Header{...}
writer = PcapFileEx.PcapWriter.open!("output.pcap", header)

write_all(path, header, packets)

@spec write_all(Path.t(), PcapFileEx.Header.t(), Enumerable.t()) ::
  {:ok, non_neg_integer()} | {:error, String.t()}

Writes all packets from an enumerable to a new PCAP file.

Convenience function that opens a file, writes all packets, and closes it.

Parameters

  • path - Path to the PCAP file to create
  • header - PCAP header configuration
  • packets - Enumerable of Packet structs

Returns

  • {:ok, count} - Number of packets written
  • {:error, reason} - Operation failed

Examples

header = %PcapFileEx.Header{...}
packets = [packet1, packet2, packet3]

{:ok, 3} = PcapFileEx.PcapWriter.write_all("output.pcap", header, packets)

write_packet(pcap_writer, packet)

@spec write_packet(t(), PcapFileEx.Packet.t()) :: :ok | {:error, String.t()}

Writes a single packet to the PCAP file.

The packet must have been created with the same datalink type as the header's datalink.

Parameters

  • writer - Writer handle from open/2
  • packet - Packet struct to write

Returns

  • :ok - Packet written successfully
  • {:error, reason} - Write failed

Examples

:ok = PcapFileEx.PcapWriter.write_packet(writer, packet)