PcapFileEx.Pcap (pcap_file_ex v0.5.5)

View Source

Reader for PCAP (legacy) format files.

Summary

Types

t()

Functions

clear_filter(pcap)

Clears all pre-filters from the reader.

close(pcap)

Closes the PCAP reader and releases resources.

next_packet(reader)

Reads the next packet from the PCAP file.

next_packet(pcap, opts)
open(path)

Opens a PCAP file for reading.

read_all(path)

Reads all packets from the PCAP file into a list.

read_all(path, opts)
set_filter(pcap, filters)

Sets pre-filters on the reader for high-performance filtering in the Rust layer.

Types

t()

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

Functions

clear_filter(pcap)

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

Clears all pre-filters from the reader.

Examples

{:ok, reader} = PcapFileEx.Pcap.open("capture.pcap")
:ok = PcapFileEx.Pcap.set_filter(reader, [...])
:ok = PcapFileEx.Pcap.clear_filter(reader)

close(pcap)

@spec close(t()) :: :ok

Closes the PCAP reader and releases resources.

next_packet(reader)

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

Reads the next packet from the PCAP file.

Returns {:ok, packet} if a packet was read, :eof if the end of file was reached, or {:error, reason} if an error occurred.

Options

  • :hosts_map - Map of IP address strings to hostname strings for endpoint resolution

Examples

{:ok, reader} = PcapFileEx.Pcap.open("capture.pcap")
{:ok, packet} = PcapFileEx.Pcap.next_packet(reader)
IO.inspect(packet.timestamp)

# With hosts mapping
hosts = %{"192.168.1.1" => "gateway", "10.0.0.1" => "server"}
{:ok, packet} = PcapFileEx.Pcap.next_packet(reader, hosts_map: hosts)

next_packet(pcap, opts)

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

open(path)

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

Opens a PCAP file for reading.

Examples

iex> {:ok, reader} = PcapFileEx.Pcap.open("capture.pcap")
iex> reader.header.datalink
"ethernet"

read_all(path)

@spec read_all(Path.t()) :: {:ok, [PcapFileEx.Packet.t()]} | {:error, String.t()}

Reads all packets from the PCAP file into a list.

This loads all packets into memory, so be careful with large files.

Returns {:ok, packets} on success or {:error, reason} if a packet fails to parse. On error, the file is still properly closed.

Options

  • :hosts_map - Map of IP address strings to hostname strings for endpoint resolution

Examples

{:ok, packets} = PcapFileEx.Pcap.read_all("capture.pcap")
Enum.count(packets)

# With hosts mapping
hosts = %{"192.168.1.1" => "gateway"}
{:ok, packets} = PcapFileEx.Pcap.read_all("capture.pcap", hosts_map: hosts)

read_all(path, opts)

@spec read_all(
  Path.t(),
  keyword()
) :: {:ok, [PcapFileEx.Packet.t()]} | {:error, String.t()}

set_filter(pcap, filters)

@spec set_filter(t(), [PcapFileEx.PreFilter.filter()]) :: :ok | {:error, String.t()}

Sets pre-filters on the reader for high-performance filtering in the Rust layer.

Filters are applied before packets are deserialized to Elixir, providing 10-100x performance improvement for selective filtering on large files.

See PcapFileEx.PreFilter for available filter types.

Examples

{:ok, reader} = PcapFileEx.Pcap.open("capture.pcap")

filters = [
  PcapFileEx.PreFilter.protocol("tcp"),
  PcapFileEx.PreFilter.port_dest(80)
]

:ok = PcapFileEx.Pcap.set_filter(reader, filters)

# Now next_packet will only return matching packets
{:ok, packet} = PcapFileEx.Pcap.next_packet(reader)