ddn.lib.pcap.handle

Handle lifecycle management for libpcap.

This module provides the PcapHandle RAII wrapper and functions to open offline captures and dead handles.

Null-handle semantics: most methods return a sentinel value (-1, null, PcapStatus.ERROR, etc.) when the handle is null rather than throwing. Callers should check isNull() after construction or use the openOffline / openDead factory functions which set error output parameters on failure.

Authors

Dejan Lekić

License

BSD-3-Clause

Copyright

© 2026 DDN (D Developer Network) Members
struct PcapHandle
fn create fopenOffline fopenOfflineWithTstampPrecision hopenOffline hopenOfflineWithTstampPrecision init lookupNet openDead openDeadWithTstampPrecision openOffline openOfflineWithTstampPrecision wsockinit

Types 1

structPcapHandle

RAII wrapper for libpcap's pcap_t handle.

This structure ensures that the underlying libpcap handle is closed automatically when the wrapper goes out of scope.

Platform-specific methods: getSelectableFd() and getRequiredSelectTimeout() are available only on POSIX systems. Windows-specific methods (getEvent, setMode, setBuff, setMinToCopy, setUserBuffer, setWait, oidGetRequest, oidSetRequest, liveDump, liveDumpEnded, getAirPcapHandle) are available on all platforms through the vtable but will return sentinel values when the underlying libpcap does not support them.

Fields
private pcap_t * _handle
Methods
void close()Closes the underlying pcap handle. It is safe to call this method multiple times.
pcap_t * handle() @safe pure nothrow @nogcReturns the raw libpcap handle.
bool isNull() const @safe pure nothrow @nogcChecks if the handle is null.
FILE * file()Returns the standard I/O stream associated with the handle.
int fileno()Returns the file descriptor associated with the handle.
string getErr()Returns the last error message for this handle.
int nextEx(out const(pcap_pkthdr) * header, out const(ubyte) * data)Reads the next packet from the handle.
void breakLoop()Terminates a `pcaploop` or `pcapdispatch` call.
int loop(int cnt, void delegate(const(pcap_pkthdr) * header, const(ubyte) * data) callback)Processes packets from a live capture or savefile using a callback.
int dispatch(int cnt, void delegate(const(pcap_pkthdr) * header, const(ubyte) * data) callback)Processes packets available in the current buffer.
int datalink()Returns the link-layer header type for the handle.
int datalinkExt()Returns the link-layer header type for the handle, including extra bits.
int[] listDatalinks()Lists the supported link-layer header types for the handle.
PcapStatus setDatalink(int dlt)Sets the link-layer header type for the handle.
PcapStatus setDirection(int direction)Sets the capture direction.
PcapStatus activate()Activates a pcap handle created with `create`.
int bufsize()Returns the buffer size for the handle.
PcapStatus setSnaplen(int snaplen)Sets the snapshot length for a non-activated handle.
PcapStatus setPromisc(bool promisc)Sets promiscuous mode for a non-activated handle.
PcapStatus setRfmon(bool rfmon)Sets monitor mode for a non-activated handle.
PcapStatus canSetRfmon()Checks if monitor mode can be set for a non-activated handle.
PcapStatus setTimeout(int timeoutMs)Sets the packet buffer timeout for a non-activated handle.
PcapStatus setBufferSize(int bufferSize)Sets the buffer size for a non-activated handle.
PcapStatus setTstampType(int tstampType)Sets the timestamp type for a non-activated handle.
PcapStatus setImmediateMode(bool immediate)Sets immediate mode for a non-activated handle.
PcapStatus setTstampPrecision(int precision)Sets the timestamp precision for a non-activated handle.
PcapStatus setProtocolLinux(int protocol)Sets the protocol for Linux handles. (Linux only)
PcapStatus setSampling(pcap_samp * samp)Sets the sampling parameters for the handle. (RPCAP only)
int getTstampPrecision()Gets the timestamp precision for the handle.
int snapshot()Returns the snapshot length for the handle.
PcapStatus stats(out pcap_stat stat)Returns statistics for the handle.
int isSwapped()Checks if the handle uses a different byte order than the current host.
int majorVersion()Returns the major version number of the pcap file.
int minorVersion()Returns the minor version number of the pcap file.
int inject(const(void)[] buf)Injects a packet into the network.
PcapStatus sendPacket(const(ubyte)[] buf)Sends a packet.
int getNonBlock(out string errBuf)Gets the non-blocking state of the handle.
PcapStatus setNonBlock(bool nonblock, out string errBuf)Sets the non-blocking state of the handle.
void * getEvent()Returns a handle to an event that is signaled when packets are available. (Windows only)
PcapStatus setMode(PcapMode mode)Sets the capture mode for the handle. (Windows only)
PcapStatus setBuff(int dim)Sets the size of the kernel buffer. (Windows only)
PcapStatus setMinToCopy(int nbytes)Sets the minimum amount of data in the kernel buffer that will cause a read to return. (Windows only)
PcapStatus setUserBuffer(int size)Sets the user buffer for the handle. (Windows only)
PcapStatus setWait(int wait)Sets the wait mode for the handle. (Windows only)
PcapStatus oidGetRequest(uint oid, void * data, ref size_t len)Performs an OID get request. (Windows only)
PcapStatus oidSetRequest(uint oid, const(void) * data, ref size_t len)Performs an OID set request. (Windows only)
PcapStatus liveDump(string fname, int maxSize, int maxPackets)Starts a live dump to a file. (Windows only)
int liveDumpEnded(bool sync)Checks if the live dump has ended. (Windows only)
void * getAirPcapHandle()Returns the AirPcap handle for the handle. (Windows only)
Constructors
this(pcap_t * handle)Constructor.
Destructors
~thisDestructor closes the handle if it's open.

Functions 12

fnPcapStatus init(uint opts, out string errBuf)Initializes the libpcap library.
fnint wsockinit()Initializes Winsock for libpcap. (Windows only)
fnPcapHandle create(string device, out string errBuf)Creates a pcap handle for a device.
fnPcapHandle fopenOffline(FILE * fp, out string errBuf)Opens a savefile for reading from a standard I/O stream.
fnPcapHandle fopenOfflineWithTstampPrecision(FILE * fp, u_int precision, out string errBuf)Opens a savefile for reading from a standard I/O stream, with specified timestamp precision.
fnPcapHandle hopenOffline(void * osHandle, out string errBuf)Opens a savefile for reading from an OS handle. (Windows only)
fnPcapHandle hopenOfflineWithTstampPrecision(void * osHandle, u_int precision, out string errBuf)Opens a savefile for reading from an OS handle, with specified timestamp precision. (Windows only)
fnPcapHandle openOffline(string fname, out string errBuf)Opens a savefile for reading.
fnPcapHandle openOfflineWithTstampPrecision(string fname, u_int precision, out string errBuf)Opens a savefile for reading, with specified timestamp precision.
fnPcapHandle openDead(int linktype, int snaplen)Creates a "dead" pcap handle for use with other libpcap functions like `pcap_compile`.
fnPcapHandle openDeadWithTstampPrecision(int linktype, int snaplen, u_int precision)Creates a "dead" pcap handle with specified timestamp precision.
fnPcapStatus lookupNet(string device, out uint net, out uint mask, out string errBuf)Returns the network number and mask for a device.