paclo.pcap — org.clojars.nanto/paclo 1.4.0

breakloop! clj

(breakloop! pcap)

bytes-seq->pcap! clj

(bytes-seq->pcap! packets {:keys [out] :as opts})

Write byte-arrays or packet maps as single-DLT Classic PCAP (microseconds). Validate explicit framing, timestamps and lengths before each record. opts: {:out "out.pcap" :linktype native-DLT :snaplen 65536}. Failure can leave partial output; output is not atomic.

call-with-cleanup clj

(call-with-cleanup body cleanups)

Run body, then every cleanup in order. Preserve the first failure and attach subsequent cleanup failures as suppressed exceptions.

capture->pcap clj

(capture->pcap {:keys [device filter max snaplen promiscuous? timeout-ms
                       max-time-ms idle-max-ms]
                :or {max 100
                     snaplen 65536
                     promiscuous? true
                     timeout-ms 10
                     max-time-ms 10000
                     idle-max-ms 3000}}
               out)

Capture live packets and save them to out.pcap. opts: {:device "en0" :filter "tcp port 80" ; optional :max 100 ; stop when captured count reaches this value :snaplen 65536 :promiscuous? true :timeout-ms 10 ; pcap_next_ex timeout :max-time-ms 10000 ; wall-clock max duration (ms) :idle-max-ms 3000} ; continuous idle max (ms)

capture->seq clj

(capture->seq {:keys [device path filter snaplen promiscuous? timeout-ms
                      buffer-size immediate? max max-time-ms idle-max-ms
                      queue-cap queue-mode on-error error-mode on-ready on-stats
                      on-queue-stats stop?]
               :or {snaplen 65536
                    promiscuous? true
                    timeout-ms 10
                    error-mode :throw
                    queue-mode :blocking}})

High-level API that returns packets as a lazy sequence. opts:

• live: {:device "en1" :filter "tcp" :snaplen 65536 :promiscuous? true :timeout-ms 10} :buffer-size <bytes> ; opt-in pcap_create buffer size :immediate? <boolean> ; opt-in immediate delivery
• offline: {:path "sample.pcap" :filter "..."}
• shared stop conditions (safe defaults when omitted): :max <int> ; max packet count (default 100) :max-time-ms <int> ; max elapsed time (default 10000) :idle-max-ms <int> ; max continuous idle time (default 3000)
• internal queue: :queue-cap <int> ; producer -> consumer buffer (default 1024) :queue-mode :blocking|:dropping ; default :blocking :on-queue-stats (fn [stats]) ; optional final queue counters
• error handling: :on-error (fn [throwable]) ; optional callback on background thread errors :error-mode :throw|:pass ; default :throw, :pass skips background errors
• live diagnostics: :on-ready (fn []) ; optional callback after open/filter setup :on-stats (fn [stats]) ; optional callback with final pcap_stats counters
• stop hook: :stop? (fn [pkt] boolean) ; stop immediately when true (breakloop!)

Returns a lazy seq of packet maps with no close/cancel operation. Abandoning a full blocking queue can retain the producer and native handle indefinitely; count/time/predicate checks cannot interrupt a blocked packet put. Prefer synchronous reduction or the public managed capture for early termination.

capture-stats clj

(capture-stats pcap)

Return portable libpcap counters for a live capture handle.

The counters are cumulative for the handle: :received, :dropped, and :interface-dropped. Throws ex-info when libpcap cannot provide statistics.

close! clj

(close! pcap)

close-after-error! clj

(close-after-error! handle error)

Close an owned handle without masking an earlier failure.

close-dumper! clj

(close-dumper! dumper)

datalink clj

(datalink pcap)

Return the nonnegative DLT for an offline or activated live handle. Throws on native failure; never infers Ethernet. The caller owns the handle.

DLT_EN10MB clj

dump! clj

(dump! dumper hdr data)

flush-dumper! clj

(flush-dumper! dumper)

initialize-handle clj

(initialize-handle handle initialize)

Own a newly acquired handle until initialize returns successfully. On failure close once, retaining the original cause and suppressed cleanup error.

list-devices clj

(list-devices)

Return a simple list of available devices. On macOS, fills missing descriptions using networksetup.

• skips entries with blank names
• applies fallback when description is blank

lookupnet clj

(lookupnet dev)

Resolve network address/mask for device dev. Success: {:net int :mask int} Failure: throws ex-info with :phase :lookupnet.

loop! clj

(loop! pcap handler)

(loop! pcap handler linktype)

Poll pcap_next_ex. handler receives maps with :ts-sec, :ts-usec, :caplen, :len, :bytes, :linktype. Terminates when rc<0 (EOF/error).

loop-for-ms! clj

(loop-for-ms! pcap duration-ms handler)

(loop-for-ms! pcap duration-ms handler {:keys [idle-max-ms timeout-ms]})

Stop after duration-ms elapsed (wall-clock). Options: {:idle-max-ms <ms> :timeout-ms <ms>} Example: (loop-for-ms! h 3000 handler) (loop-for-ms! h 3000 handler {:idle-max-ms 1000 :timeout-ms 50})

loop-n! clj

(loop-n! pcap n handler)

(loop-n! pcap n handler {:keys [idle-max-ms timeout-ms]})

Process up to n packets via pcap_next_ex, then stop. Options: {:idle-max-ms <ms> :timeout-ms <ms>} Example: (loop-n! h 10 handler) ; default behavior (loop-n! h 10 handler {:idle-max-ms 3000 :timeout-ms 100})

loop-n-or-ms! clj

(loop-n-or-ms! pcap
               {:keys [n ms idle-max-ms timeout-ms stop?] :as opts}
               handler)

Stop when either n packets are processed or duration-ms is reached. conf: {:n <long> :ms <long> :idle-max-ms <ms-optional> :timeout-ms <ms-optional> :stop? <fn-optional>}

open-dead clj

(open-dead)

(open-dead linktype snaplen)

Create a dead pcap handle for generation/writing. linktype uses DLT_* constants. Default snaplen is 65536.

open-dumper clj

(open-dumper pcap path)

open-live clj

(open-live {:keys [device snaplen promiscuous? timeout-ms netmask buffer-size
                   immediate?]
            :or {snaplen 65536 promiscuous? true timeout-ms 10}
            :as opts})

open-offline clj

(open-offline path)

(open-offline path opts)

PCAP_ERRBUF_SIZE clj

PCAP_PKTHDR_BYTES clj

rc->status clj

(rc->status rc)

Classify pcap_next_ex return code. 1 => :packet, 0 => :timeout, -2 => :eof, anything else => :error.

rc->status-detail clj

(rc->status-detail rc)

Return a map {:rc rc :status <kw> :summary <string|nil>} that is convenient for logging when pcap_next_ex finishes with EOF (-2) or an error (-1/others).

reduce-capture clj

(reduce-capture opts rf init)

Synchronously reduce live or offline packets without a queue or lazy seq.

This is an internal primitive. It accepts the same source, filtering, stopping, error, and final-statistics options as capture->seq. The reducing function may return reduced for immediate early termination.

reduce-capture-report clj

(reduce-capture-report
  {:keys [device path filter snaplen promiscuous? timeout-ms buffer-size
          immediate? max max-time-ms idle-max-ms on-error error-mode on-ready
          on-stats stop?]
   :or {snaplen 65536 promiscuous? true timeout-ms 10 error-mode :throw}}
  rf
  init)

Synchronously reduce packets and return both the accumulator and execution statistics. This is the internal reporting primitive behind the public paclo.core/reduce-packets-report API.

run-live-for-ms! clj

(run-live-for-ms! opts duration-ms handler)

(run-live-for-ms! {:keys [device filter snaplen promiscuous? timeout-ms]
                   :or {snaplen 65536 promiscuous? true timeout-ms 10}}
                  duration-ms
                  handler
                  {:keys [idle-max-ms]})

Open live capture, optionally apply BPF, process for duration-ms, then close. Additional option: {:idle-max-ms <ms>} Example: (run-live-for-ms! {:device "en1" :timeout-ms 50} 5000 handler {:idle-max-ms 1000})

run-live-for-ms-summary! clj

(run-live-for-ms-summary! opts duration-ms handler)

(run-live-for-ms-summary! opts duration-ms handler loop-opts)

Run run-live-for-ms! and return a summary map. Example: (run-live-for-ms-summary! {:device "en0" :filter "tcp" :timeout-ms 50} 3000 (fn [_]) {:idle-max-ms 1000})

run-live-n! clj

(run-live-n! opts n handler)

(run-live-n! {:keys [device filter snaplen promiscuous? timeout-ms]
              :or {snaplen 65536 promiscuous? true timeout-ms 10}}
             n
             handler
             {:keys [idle-max-ms]})

Open live capture, optionally apply BPF, process n packets, then close. Additional option: :idle-max-ms (:timeout-ms is shared with open-live) Example: (run-live-n! {:device "en1" :filter "tcp" :timeout-ms 100} 50 handler {:idle-max-ms 3000})

run-live-n-summary! clj

(run-live-n-summary! opts n handler)

(run-live-n-summary! opts n handler loop-opts)

Run run-live-n! and return a summary map. Example: (run-live-n-summary! {:device "en0" :filter "udp" :timeout-ms 50} 100 (fn [_]) {:idle-max-ms 3000})

set-bpf! clj

(set-bpf! pcap expr)

Apply BPF with optimize=1 and netmask=0 (unknown). Returns true.

set-bpf-on-device! clj

(set-bpf-on-device! pcap dev expr)

Lookup device netmask for dev and apply BPF via set-bpf-with-netmask!. Returns true.

set-bpf-with-netmask! clj

(set-bpf-with-netmask! pcap expr netmask)

Apply BPF with optimize=1 and explicit netmask. Returns true.

throwable->data clj

(throwable->data error)

vlan-tag->str clj

(vlan-tag->str {:keys [tpid vid pcp dei]})

Render VLAN tag map {:tpid .. :vid .. :pcp .. :dei ..} as a display string.

with-dumper clj macro

(with-dumper [sym open-expr] & body)

Run body owning a dumper; flush and close even when either step fails.

with-live clj macro

(with-live [sym opts] & body)

Example: (with-live [h {:device "en0" :filter "tcp"}] (loop-n! h 10 prn))

with-offline clj macro

(with-offline [sym open-expr] & body)

Example: (with-offline [h (open-offline "dev/resources/fixtures/sample.pcap")] (loop-for-ms! h 2000 prn)) (with-offline [h (open-offline "dev/resources/fixtures/sample.pcap" {:filter "udp"})] (loop-n! h 50 prn))

with-pcap clj macro

(with-pcap [sym open-expr] & body)

Run body owning a handle; close once without masking the body failure.

writer-options clj

(writer-options opts)

Validate explicit single-DLT Classic PCAP options before acquiring resources. DLT-to-savefile support is checked by native pcap_dump_open.