function pcapFile
pcapFile(endianness?: PcapEndianness | undefined): Coder<PcapFile<PcapGlobalHeader, PcapRecord>>

Creates a coder for a complete pcap capture file.

The returned coder pairs pcapGlobalHeader with pcapRecord via pcapFileWith. Records are read greedily until the buffer no longer holds a full 16-byte record header. For custom record handling — for example, refining the payload into a parsed link-layer frame — use pcapFileWith directly with your own coders.

Byte order

Called with an endianness, the coder is fixed to that byte order for both directions — identical to every earlier release.

Called without one, the coder resolves the byte order per operation:

  • On decode it reads the file's own magic number via detectPcapMagic and decodes the header and every record in the byte order that magic implies. Little- and big-endian captures therefore both round-trip through the same coder, with no configuration. A buffer whose first four bytes are not a recognised pcap magic is decoded as PCAP_DEFAULT_ENDIANNESS.
  • On encode there is no file to inspect, so the coder writes PCAP_DEFAULT_ENDIANNESS. Note that the magic field is a logical value: writing PCAP_MAGIC_MICROS produces the correct on-disk byte sequence for whichever order is in effect.

Examples

Encode an empty capture

import { assertEquals } from "@std/assert";
import {
  pcapFile,
  PCAP_MAGIC_MICROS,
  LINKTYPE,
} from "@binstruct/pcap";

const coder = pcapFile("le");
const buffer = new Uint8Array(24);
const written = coder.encode({
  header: {
    magic: PCAP_MAGIC_MICROS,
    versionMajor: 2,
    versionMinor: 4,
    thisZone: 0,
    sigFigs: 0,
    snapLen: 65535,
    network: LINKTYPE.ETHERNET,
  },
  records: [],
}, buffer);

assertEquals(written, 24);

One zero-argument coder reads captures of either byte order

import { assertEquals } from "@std/assert";
import {
  LINKTYPE,
  PCAP_MAGIC_MICROS,
  pcapFile,
} from "@binstruct/pcap";

const capture = {
  header: {
    magic: PCAP_MAGIC_MICROS,
    versionMajor: 2,
    versionMinor: 4,
    thisZone: 0,
    sigFigs: 0,
    snapLen: 65535,
    network: LINKTYPE.ETHERNET,
  },
  records: [{
    tsSec: 1_700_000_000,
    tsUsec: 250_000,
    inclLen: 4,
    origLen: 1500,
    data: new Uint8Array([0xde, 0xad, 0xbe, 0xef]),
  }],
};

const little = new Uint8Array(64);
const big = new Uint8Array(64);
const leWritten = pcapFile("le").encode(capture, little);
const beWritten = pcapFile("be").encode(capture, big);

const auto = pcapFile();
const [fromLe] = auto.decode(little.subarray(0, leWritten));
const [fromBe] = auto.decode(big.subarray(0, beWritten));

assertEquals(fromLe, capture);
assertEquals(fromBe, capture);

Zero-argument round trip writes the default byte order

import { assertEquals } from "@std/assert";
import {
  detectPcapMagic,
  LINKTYPE,
  PCAP_DEFAULT_ENDIANNESS,
  PCAP_MAGIC_NANOS,
  pcapFile,
} from "@binstruct/pcap";

const coder = pcapFile();
const capture = {
  header: {
    magic: PCAP_MAGIC_NANOS,
    versionMajor: 2,
    versionMinor: 4,
    thisZone: 0,
    sigFigs: 0,
    snapLen: 1500,
    network: LINKTYPE.RAW,
  },
  records: [],
};

const buffer = new Uint8Array(24);
const written = coder.encode(capture, buffer);
const [decoded, read] = coder.decode(buffer.subarray(0, written));

assertEquals(written, 24);
assertEquals(read, 24);
assertEquals(decoded, capture);
assertEquals(detectPcapMagic(buffer), {
  endianness: PCAP_DEFAULT_ENDIANNESS,
  nanos: true,
});

Parameters

optional
endianness: PcapEndianness | undefined = undefined

Byte order matching the file's magic. Omit it to sniff the magic on decode and use PCAP_DEFAULT_ENDIANNESS on encode.

Return Type

A coder for a PcapFile of PcapGlobalHeader and PcapRecord.

Usage

import { pcapFile } from ".";