Module org.jnetpcap

Package org.jnetpcap

Class Pcap

java.lang.Object

org.jnetpcap.Pcap

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

Pcap0_4

public abstract sealed class Pcap
extends Object
implements AutoCloseable
permits Pcap0_4

Entry point and base class for all Pcap API methods provided by jNetPcap library.

Author:

Sly Technologies, repos@slytechs.com

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Pcap.LibraryPolicy	An interface which provides a hook into Pcap initialization process.
static final class	Pcap.Linux	Linux only/specific calls.
static class	Pcap.Unix	Unix only/specific calls.

Field Summary

Fields

Modifier and Type	Field	Description
protected boolean	closed	flag which indicates open/closed status, if true, the pcap address is not longer valid.
protected final PcapHeaderABI	pcapHeaderABI	The pcap header ABI.
protected final MemorySegment	POINTER_TO_POINTER1	The pointer to pointer1.
protected final MemorySegment	POINTER_TO_POINTER2	The pointer to pointer2.
protected final MemorySegment	POINTER_TO_POINTER3	The pointer to pointer3.
static final String	VERSION	The jNetPcap API version.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Pcap(MemorySegment pcapHandle, String name, PcapHeaderABI abi)	Instantiates a new pcap.

Method Summary

Modifier and Type	Method	Description
void	activate()	Activate a capture handle
void	breakloop()	Force a dispatch or loop call to return.
boolean	canSetRfmon()	check whether monitor mode can be set for a not-yet-activated capture handle.
static void	checkPcapVersion(String applicationVersion)	Checks runtime version against application version of the java jNetPcap APIs.
void	close()	Close a capture device or savefile
BpFilter	compile(String str, boolean optimize)	Compile a filter expression without a netmask.
BpFilter	compile(String str, boolean optimize, int netmask)	Compile a filter expression with netmask.
static BpFilter	compileNoPcap(int snaplen, PcapDlt pcapDlt, String str, boolean optimize, int netmask)	Deprecated.
static Pcap	create(String device)	Create a live capture handle.
static Pcap	create(PcapIf device)	Create a live capture handle.
PcapDlt	datalink()	Get the link-layer header type.
PcapDlt	dataLinkExt()	Gets the link-layer header type for the live capture or ``savefile''.
static PcapDlt	datalinkNameToVal(String name)	Translates a link-layer header type name, which is a DLT_ name with the DLT_ removed, to the corresponding link-layer header type value.
static String	datalinkValToDescription(PcapDlt pcapDlt)	link-layer header type.
static String	datalinkValToName(PcapDlt pcapDlt)	Translates a link-layer header type value to the corresponding link-layer header type name, which is the DLT_ name for the link-layer header type value with the DLT_ removed.
<U> int	dispatch(int count, PcapDumper pcapDumper)	Process packets from a live capture or savefile and save them directly to dump file.
int	dispatch(int count, PcapHandler.NativeCallback handler, MemorySegment user)	Process packets from a live capture or savefile and dispatch using low level callback.
<U> int	dispatch(int count, PcapHandler.OfArray<U> handler, U user)	Process packets from a live capture or savefile and copy to a newly allocated array and dispatches to handler.
<U> int	dispatch(int count, PcapHandler.OfMemorySegment<U> handler, U user)	Process packets from a live capture or savefile and dispatch directly to handler.
PcapDumper	dumpOpen(String fname)	Open a file to which to write packets.
static List<PcapIf>	findAllDevs()	Constructs a list of network devices that can be opened with pcap_create(3PCAP) and pcap_activate(3PCAP) or with pcap_open_live(3PCAP).
static List<PcapIf>	findAllDevsEx(String source, PcapSrc type, String username, String password)	Create a list of network devices that can be opened with Pcap#open.
String	geterr()	Get libpcap error message text.
protected String	getErrorString(int error)	Dynamic non-pcap utility method to convert libpcap error code to a string, by various fallback methods with an active pcap handle.
final String	getName()	Gets the name of this pcap handle.
boolean	getNonBlock()	Gets the state of non-blocking mode on a capture device.
protected MemorySegment	getPcapHandle()	Gets the pcap handle's memory address.
PcapHeaderABI	getPcapHeaderABI()	Gets the pcap header ABI (Abstract Binary Interface).
PcapTStampPrecision	getTstampPrecision()	Get the time stamp precision returned in captures.
static void	init(int opts)	Initialize the native libpcap library.
static void	init(PcapOption option)	Initialize the native libpcap library.
final int	inject(byte[] array)	Transmit a packet.
final int	inject(byte[] array, int offset, int length)	Transmit a packet.
int	inject(MemorySegment packet, int length)	Transmit a packet.
final int	inject(ByteBuffer buf)	Transmit a packet.
static boolean	isSupported()	Checks if the Pcap subclass at a specific libpcap API version is natively supported.
boolean	isSwapped()	Find out whether a savefile has the native byte order.
static String	libVersion()	Get the version information for libpcap.
protected static List<PcapIf>	listAllPcapIf(MemorySegment next, Arena scope)	List all pcap if.
List<PcapDlt>	listDataLinks()	Get a list of link-layer header types supported by a capture device.
List<PcapTstampType>	listTstampTypes()	Get a list of time stamp types supported by a capture device.
static boolean	loadNativePcapLibrary()	Checks if native libpcap library is loaded, and if its not,it will attempt to load it.
static String	lookupDev()	Deprecated. use findAllDevs() and use the first device
protected static String	lookupErrorString(int error)	Static non-pcap utility method to convert libpcap error code to a string, by various fallback methods with no pcap handle.
static NetIp4Address	lookupNet(String device)	Find the IPv4 network number and netmask for a device.
static NetIp4Address	lookupNet(PcapIf device)	Find the IPv4 network number and netmask for a device.
<U> int	loop(int count, PcapDumper pcapDumper)	Process packets from a live capture or savefile and save them directly to dump file.
<U> int	loop(int count, PcapHandler.NativeCallback handler, MemorySegment user)	Process packets from a live capture or savefile and dispatch using low level callback.
<U> int	loop(int count, PcapHandler.OfArray<U> handler, U user)	Process packets from a live capture or savefile and copy to a newly allocated array and dispatches to handler.
<U> int	loop(int count, PcapHandler.OfMemorySegment<U> handler, U user)	Process packets from a live capture or savefile and dispatch directly to handler.
int	majorVersion()	Get the version number of a savefile.
int	minorVersion()	Get the version number of a savefile.
protected static Arena	newArena()	New scope.
PcapPacketRef	next()	read the next packet from a handle.
PcapPacketRef	nextEx()	Read the next packet from a pcap handle.
static boolean	offlineFilter(BpFilter bpFilter, MemorySegment pktHdr, MemorySegment pktData)	Check whether a filter matches a packet.
static Pcap	openDead(PcapDlt linktype, int snaplen)	Open a fake pcap_t for compiling filters or opening a capture for output.
static Pcap	openDeadWithTstampPrecision(PcapDlt linktype, int snaplen, PcapTStampPrecision precision)	Open a fake pcap_t for compiling filters or opening a capture for output.
static Pcap	openLive(String device, int snaplen, boolean promisc, long timeout, TimeUnit unit)	Open a device for capturing.
static Pcap	openLive(String device, int snaplen, boolean promisc, Duration timeout)	Open a device for capturing.
static Pcap	openLive(PcapIf device, int snaplen, boolean promisc, long timeout, TimeUnit unit)	Open a device for capturing.
static Pcap	openOffline(File file)	Open a saved capture file for reading.
static Pcap	openOffline(String fname)	Open a saved capture file for reading.
final ByteOrder	order()	Returns the ByteOrder of the current capture based on results from isSwapped() method call.
Pcap	perror(String prefix)	Print libpcap error message text.
final void	sendPacket(byte[] buf)	Transmit a packet.
final void	sendPacket(byte[] buf, int offset, int length)	Transmit a packet.
void	sendPacket(MemorySegment packet, int length)	Transmit a packet.
final void	sendPacket(ByteBuffer buf)	Transmit a packet.
Pcap	setBufferSize(int bufferSize)	Sets the buffer size for a not-yet- activated capture handle.
Pcap	setDatalink(int dlt)	Set the link-layer header type to be used by a capture device .
Pcap	setDatalink(Optional<PcapDlt> dlt)	Set the link-layer header type to be used by a capture device .
Pcap	setDatalink(PcapDlt dlt)	Set the link-layer header type to be used by a capture device .
Pcap	setDirection(int dir)	pcap_setdirection() is used to specify a direction that packets will be captured.
Pcap	setDirection(Optional<PcapDirection> dir)	Set the direction for which packets will be captured.
Pcap	setDirection(PcapDirection dir)	Set the direction for which packets will be captured.
Pcap	setFilter(Optional<BpFilter> bpfProgram)	set the filter.
Pcap	setFilter(BpFilter bpfProgram)	set the filter.
Pcap	setImmediateMode(boolean enable)	Set immediate mode for a not-yet- activated capture handle.
Pcap	setNonBlock(boolean blockMode)	Sets the state of non-blocking mode on a capture device.
Pcap	setPromisc(boolean promiscousMode)	Set promiscuous mode for a not-yet-activated capture handle.
Pcap	setRfmon(boolean rfMonitor)	Set monitor mode for a not-yet-activated capture handle.
Pcap	setSnaplen(int snaplen)	Set the snapshot length for a not-yet-activated capture handle.
Pcap	setTimeout(int timeoutInMillis)	Set the packet buffer timeout for a not-yet-activated capture handle.
Pcap	setTstampPrecision(PcapTStampPrecision precision)	Set the time stamp precision returned in captures.
Pcap	setTstampType(PcapTstampType type)	Set the time stamp type to be used by a capture device.
Pcap	setUncaughtExceptionHandler(Thread.UncaughtExceptionHandler exceptionHandler)	Sets the uncaught exception handler for loop(int, org.jnetpcap.PcapDumper) and dispatch(int, org.jnetpcap.PcapDumper) methods.
Pcap	setUncaughtExceptionHandler(Consumer<? super Throwable> exceptionHandler)	Sets the uncaught exception handler for loop(int, org.jnetpcap.PcapDumper) and dispatch(int, org.jnetpcap.PcapDumper) methods.
int	snapshot()	Get the snapshot length.
PcapStat	stats()	Get capture statistics.
static String	statusToStr(int error)	Convert an error full value to a string.
static String	statusToStr(PcapCode error)	Convert an error full value to a string.
static String	strerror(int code)	Convert an error full value to a string.
String	toString()	Debug info about this pcap handle.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

VERSION

public static final String VERSION

The jNetPcap API version.

See Also:

• Constant Field Values

POINTER_TO_POINTER1

protected final MemorySegment POINTER_TO_POINTER1

The pointer to pointer1.

POINTER_TO_POINTER2

protected final MemorySegment POINTER_TO_POINTER2

The pointer to pointer2.

POINTER_TO_POINTER3

protected final MemorySegment POINTER_TO_POINTER3

The pointer to pointer3.

closed

protected boolean closed

flag which indicates open/closed status, if true, the pcap address is not longer valid.

pcapHeaderABI

protected final PcapHeaderABI pcapHeaderABI

The pcap header ABI.

Constructor Details

Pcap

protected Pcap(MemorySegment pcapHandle,
 String name,
 PcapHeaderABI abi)

Instantiates a new pcap.

Parameters:

pcapHandle - the pcap handle or pcap_t * address.

name - the name of this pcap handle.

abi - the abi

Method Details

checkPcapVersion

public static void checkPcapVersion(String applicationVersion)
                             throws PcapVersionException

Checks runtime version against application version of the java jNetPcap APIs.

For example Pcap.checkPcapVersion(Pcap.VERSION) when compiled, the Pcap.VERSION will be stored in the application full as a constant and then compared to the runtime Pcap.VERSION, also a constant. Both runtime and application constants will be different as they are compiled at different times and against, possibly, different versions of the pcap libarary.

This does not perform version checks against the native libpcap library versions. Only the java jNetPcap API versions.

To check for compatibility with specific native library versions, you can either use libVersion() and do a compare, or try specific PcapX_Y.isSupported() calls to get a boolean weather a particular subclass is supported. Support in version specific classes is done by checking if a very specific to the version, native library symbol is found. A missing symbol indicates that the native library is of lower version, which does not have the symbol defined yet.

Parameters:

applicationVersion - the application version

Throws:

PcapVersionException - the incompatible pcap runtime exception

compileNoPcap

@Deprecated(since="libpcap 1.11.0 API, jNetPcap 2.1.0")
public static BpFilter compileNoPcap(int snaplen,
 PcapDlt pcapDlt,
 String str,
 boolean optimize,
 int netmask)
                              throws PcapException

Deprecated.

Compile a filter expression against a dead handle opened using openDead.

pcap_compile() is used to compile the string str into a filter program. See pcap-filter(7) for the syntax of that string. fp is a pointer to a bpf_program struct and is filled in by pcap_compile(). optimize controls whether optimization on the resulting full is performed. netmask specifies the IPv4 netmask of the network on which packets are being captured; it is used only when checking for IPv4 broadcast addresses in the filter program. If the netmask of the network on which packets are being captured isn't known to the program, or if packets are being captured on the Linux "any" pseudo-interface that can capture on more than one network, a value of PCAP_NETMASK_UNKNOWN can be supplied; tests for IPv4 broadcast addresses will fail to compile, but all other tests in the filter program will be OK.

NOTE: in libpcap 1.8.0 and later, pcap_compile() can be used in multiple threads within a single process. However, in earlier versions of libpcap, it is not safe to use pcap_compile() in multiple threads in a single process without some form of mutual exclusion allowing only one thread to call it at any given time.

Parameters:

snaplen - the snaplen

pcapDlt - the dlt

str - filter expression to be compiled

optimize - controls whether optimization on the resulting full is performed

netmask - specifies the IPv4 netmask of the network on which packets are being captured; it is used only when checking for IPv4 broadcast addresses in the filter program. If the netmask of the network on which packets are being captured isn't known to the program, or if packets are being captured on the Linux "any" pseudo-interface that can capture on more than one network, a value of PCAP_NETMASK_UNKNOWN can be supplied; tests for IPv4 broadcast addresses will fail to compile, but all other tests in the filter program will be OK

Returns:

the compiled filter

Throws:

PcapException - any errors

create

public static Pcap create(PcapIf device)
                   throws PcapException

Create a live capture handle. create is used to create a packet capture handle to look at packets on the network. source is a string that specifies the network device to open; on Linux systems with 2.2 or later kernels, a source argument of "any" or NULL can be used to capture packets from all interfaces. The returned handle must be activated with pcap_activate() before pack' ets can be captured with it; options for the capture, such as promiscu' ous mode, can be set on the handle before activating it.

Parameters:

device - pcap network interface that specifies the network device to open.

Returns:

a new pcap object that needs to be activated using activate() call

Throws:

PcapException - the pcap exception

Since:

libpcap 1.0

create

public static Pcap create(String device)
                   throws PcapException

Create a live capture handle. create is used to create a packet capture handle to look at packets on the network. source is a string that specifies the network device to open; on Linux systems with 2.2 or later kernels, a source argument of "any" or NULL can be used to capture packets from all interfaces. The returned handle must be activated with pcap_activate() before pack' ets can be captured with it; options for the capture, such as promiscu' ous mode, can be set on the handle before activating it.

Parameters:

device - a string that specifies the network device to open; on Linux systems with 2.2 or later kernels, a source argument of "any" or NULL can be used to capture packets from all interfaces.

Returns:

a new pcap object that needs to be activated using activate() call

Throws:

PcapException - the pcap exception

Since:

libpcap 1.0

datalinkNameToVal

public static PcapDlt datalinkNameToVal(String name)

Translates a link-layer header type name, which is a DLT_ name with the DLT_ removed, to the corresponding link-layer header type value. The translation is case-insensitive.

Parameters:

name - link-layer header type name

Returns:

the pcap data link type

Since:

libpcap 0.8

datalinkValToDescription

public static String datalinkValToDescription(PcapDlt pcapDlt)

link-layer header type. NULL is returned if the type value does not correspond to a known DLT_ value..

Parameters:

pcapDlt - link-layer header type

Returns:

short description of that link-layer header type

Since:

libpcap 0.8

datalinkValToName

public static String datalinkValToName(PcapDlt pcapDlt)

Translates a link-layer header type value to the corresponding link-layer header type name, which is the DLT_ name for the link-layer header type value with the DLT_ removed. NULL is returned if the type value does not correspond to a known DLT_ value..

Parameters:

pcapDlt - link-layer header type

Returns:

corresponding link-layer header type name

Since:

libpcap 0.8

findAllDevs

public static List<PcapIf> findAllDevs()
                                throws PcapException

Constructs a list of network devices that can be opened with pcap_create(3PCAP) and pcap_activate(3PCAP) or with pcap_open_live(3PCAP). (Note that there may be network devices that cannot be opened by the process calling pcap_findalldevs(), because, for example, that process does not have sufficient privileges to open them for capturing; if so, those devices will not appear on the list.) If pcap_findalldevs() succeeds, the pointer pointed to by alldevsp is set to point to the first element of the list, or to NULL if no devices were found (this is considered success).

Each element of the list is of type pcap_if_t, and has the following members:

next

if not NULL, a pointer to the next element in the list; NULL for the last element of the list

name

a pointer to a string giving a name for the device to pass to pcap_open_live()

description

if not NULL, a pointer to a string giving a human-readable description of the device

addresses

a pointer to the first element of a list of network addresses for the device, or NULL if the device has no addresses

flags

device flags:

PCAP_IF_LOOPBACK

set if the device is a loopback interface

PCAP_IF_UP

set if the device is up

PCAP_IF_RUNNING

set if the device is running

PCAP_IF_WIRELESS

set if the device is a wireless interface; this includes IrDA as well as radio-based networks such as IEEE 802.15.4 and IEEE 802.11, so it doesn't just mean Wi-Fi

PCAP_IF_CONNECTION_STATUS

a bitmask for an indication of whether the adapter is connected or not; for wireless interfaces, "connected" means "associated with a network"

PCAP_IF_CONNECTION_STATUS_UNKNOWN

it's unknown whether the adapter is connected or not

PCAP_IF_CONNECTION_STATUS_CONNECTED

the adapter is connected

PCAP_IF_CONNECTION_STATUS_DISCONNECTED

the adapter is disconnected

PCAP_IF_CONNECTION_STATUS_NOT_APPLICABLE

the notion of "connected" and "disconnected" don't apply to this interface; for example, it doesn't apply to a loopback device

Each element of the list of addresses is of type pcap_addr_t, and has the following members:

next

if not NULL, a pointer to the next element in the list; NULL for the last element of the list

addr

a pointer to a struct sockaddr containing an address

netmask

if not NULL, a pointer to a struct sockaddr that contains the netmask corresponding to the address pointed to by addr

broadaddr

if not NULL, a pointer to a struct sockaddr that contains the broadcast address corresponding to the address pointed to by addr; may be null if the device doesn't support broadcasts

dstaddr

if not NULL, a pointer to a struct sockaddr that contains the destination address corresponding to the address pointed to by addr; may be null if the device isn't a point-to-point interface

Note that the addresses in the list of addresses might be IPv4 addresses, IPv6 addresses, or some other type of addresses, so you must check the sa_family member of the struct sockaddr before interpreting the contents of the address; do not assume that the addresses are all IPv4 addresses, or even all IPv4 or IPv6 addresses. IPv4 addresses have the value AF_INET, IPv6 addresses have the value AF_INET6 (which older operating systems that don't support IPv6 might not define), and other addresses have other values. Whether other addresses are returned, and what types they might have is platform-dependent. For IPv4 addresses, the struct sockaddr pointer can be interpreted as if it pointed to a struct sockaddr_in; for IPv6 addresses, it can be interpreted as if it pointed to a struct sockaddr_in6.

For example

	List<PcapIf> list = Pcap.findAllDevs()

Returns:

list of network devices

Throws:

PcapException - any pcap errors

Since:

libpcap 0.7

findAllDevsEx

public static List<PcapIf> findAllDevsEx(String source,
 PcapSrc type,
 String username,
 String password)
                                  throws PcapException

Create a list of network devices that can be opened with Pcap#open.

This routine can scan a directory for savefiles, list local capture devices, or list capture devices on a remote machine running an RPCAP server.

For scanning for savefiles, it can be used on both UN*X systems and Windows systems; for each directory entry it sees, it tries to open the file as a savefile using pcap_open_offline(), and only includes it in the list of files if the open succeeds, so it filters out files for which the user doesn't have read permission, as well as files that aren't valid savefiles readable by libpcap.

For listing local capture devices, it's just a wrapper around pcap_findalldevs(); full using pcap_findalldevs() will work on more platforms than full using pcap_findalldevs_ex().

For listing remote capture devices, pcap_findalldevs_ex() is currently the only API available.

Warning:

There may be network devices that cannot be opened with pcap_open() by the process calling pcap_findalldevs(), because, for example, that process might not have sufficient privileges to open them for capturing; if so, those devices will not appear on the list.

Parameters:

source - This source will be examined looking for adapters (local or remote) (e.g. source can be 'rpcap://' for local adapters or 'rpcap://host:port' for adapters on a remote host) or pcap files (e.g. source can be 'file://c:/myfolder/').

type - Type of the authentication required

username - The username that has to be used on the remote machine for authentication

password - The password that has to be used on the remote machine for authentication

Returns:

The list of the devices

Throws:

PcapException - the pcap exception

Since:

libpcap 1.9, early days of WinPcap

init

public static void init(int opts)
                 throws PcapException

Initialize the native libpcap library.

Used to initialize the Packet Capture library. opts specifies options for the library; currently, the options are:

PcapConstants.PCAP_CHAR_ENC_LOCAL

Treat all strings supplied as arguments, and return all strings to the caller, as being in the local character encoding.

PcapConstants.PCAP_CHAR_ENC_UTF_8

Treat all strings supplied as arguments, and return all strings to the caller, as being in UTF-8.

On UNIX-like systems, the local character encoding is assumed to be UTF-8, so no character encoding transformations are done.

On Windows, the local character encoding is the local ANSI full page.

If init(int) is not called, strings are treated as being in the local ANSI full page on Windows, lookupDev() will succeed if there is a device on which to capture, and create(String) makes an attempt to check whether the string passed as an argument is a UTF-16LE string - note that this attempt is unsafe, as it may run past the end of the string - to handle pcap_lookupdev() returning a UTF-16LE string. Programs that don't call init(int) should, on Windows, call native pcap_wsockinit() to initialize Winsock; this is not necessary if init(int) is called, as init(int) will initialize Winsock itself on Windows.

Parameters:

opts - the opts

Throws:

PcapException - the pcap exception

Since:

libpcap 1.9

init

public static void init(PcapOption option)
                 throws PcapException

Initialize the native libpcap library.

Used to initialize the Packet Capture library. opts specifies options for the library; currently, the options are:

PcapConstants.PCAP_CHAR_ENC_LOCAL

Treat all strings supplied as arguments, and return all strings to the caller, as being in the local character encoding.

PcapConstants.PCAP_CHAR_ENC_UTF_8

Treat all strings supplied as arguments, and return all strings to the caller, as being in UTF-8.

On UNIX-like systems, the local character encoding is assumed to be UTF-8, so no character encoding transformations are done.

On Windows, the local character encoding is the local ANSI full page.

If init(int) is not called, strings are treated as being in the local ANSI full page on Windows, lookupDev() will succeed if there is a device on which to capture, and create(String) makes an attempt to check whether the string passed as an argument is a UTF-16LE string - note that this attempt is unsafe, as it may run past the end of the string - to handle pcap_lookupdev() returning a UTF-16LE string. Programs that don't call init(int) should, on Windows, call native pcap_wsockinit() to initialize Winsock; this is not necessary if init(int) is called, as init(int) will initialize Winsock itself on Windows.

Parameters:

option - a pcap init option

Throws:

PcapException - the pcap exception

Since:

libpcap 1.9

isSupported

public static boolean isSupported()

Checks if the Pcap subclass at a specific libpcap API version is natively supported. This is a safe method to use anytime on any platform, weather native library is present or not.

For example, Pcap1_0.isSupported() will accurately ascertain if libpcap API version 1.0 level calls are supported by the system runtime. Also a call such as WinPcap.isSupported() will determine if WinPcap related calls, ie. native WinPcap 4.1.3 or less, are supported and by extension if this is a Microsoft Windows platform.

Due to libpcap API versioning, it is safe to assume that if Pcap1_10.isSupported() returns true, that at least libpcap API version 1.0 is installed on this platform, and that all lower version calls such as libpcap 0.8 and 0.9 are available as well. The subclass hierarchy of jNetPcap module reflects the versioning of libpcap and its derivatives and the public releases of the native libraries. For example Npcap class extends WinPcap class because Npcap project took over the support for WinPcap where it left off.

Implementation notes: The check is performed by verifying that certain, subclass specific native symbols were linked with Pcap full which was introduced at a specific libpcap or related API levels.

Returns:

true, if pcap is supported up to this specific version level, otherwise false

See Also:

• Pcap.LibraryPolicy.setDefault(LibraryPolicy)

libVersion

public static String libVersion()

Get the version information for libpcap.

Returns:

a string giving information about the version of the libpcap library being used; note that it contains more information than just a version number

Since:

libpcap 0.8

listAllPcapIf

protected static List<PcapIf> listAllPcapIf(MemorySegment next,
 Arena scope)

List all pcap if.

Parameters:

next - the next

scope - the scope

Returns:

the list

loadNativePcapLibrary

public static boolean loadNativePcapLibrary()

Checks if native libpcap library is loaded, and if its not,it will attempt to load it. If library loading fails, no error messages are reported but false will be returned.

Returns:

true, if is native library was successfully loaded, otherwise false

See Also:

• PcapForeignInitializer.loadNativePcapLibrary(boolean)

lookupDev

@Deprecated
public static String lookupDev()
                        throws PcapException

Deprecated.

use findAllDevs() and use the first device

Find the default device on which to capture.

Note: We're deprecating pcap_lookupdev() for various reasons (not thread-safe, can behave weirdly with WinPcap). Callers should use pcap_findalldevs() and use the first device.

Returns:

a device name

Throws:

PcapException - the pcap exception

Since:

libpcap 0.4

lookupErrorString

protected static String lookupErrorString(int error)

Static non-pcap utility method to convert libpcap error code to a string, by various fallback methods with no pcap handle.

Parameters:

error - the error

Returns:

the string

lookupNet

public static NetIp4Address lookupNet(PcapIf device)
                               throws PcapException

Find the IPv4 network number and netmask for a device. pcap_lookupnet() is used to determine the IPv4 network number and mask associated with the network device device. Both netp and maskp are bpf_u_int32 pointers.

Parameters:

device - the network device name

Returns:

A netmasked IPv4 address

Throws:

PcapException - any LibpcapApi errors

Since:

libpcap 0.4

lookupNet

public static NetIp4Address lookupNet(String device)
                               throws PcapException

Find the IPv4 network number and netmask for a device. pcap_lookupnet() is used to determine the IPv4 network number and mask associated with the network device device. Both netp and maskp are bpf_u_int32 pointers.

Parameters:

device - the network device name

Returns:

A netmasked IPv4 address

Throws:

PcapException - any LibpcapApi errors

Since:

libpcap 0.4

newArena

protected static Arena newArena()

New scope.

Returns:

the memory session

offlineFilter

public static boolean offlineFilter(BpFilter bpFilter,
 MemorySegment pktHdr,
 MemorySegment pktData)

Check whether a filter matches a packet.

checks whether a filter matches a packet. fp is a pointer to a bpf_program struct, usually the result of a call to pcap_compile(3PCAP). h points to the pcap_pkthdr structure for the packet, and pkt points to the data in the packet.

Parameters:

bpFilter - the BPF program or filter program

pktHdr - the packet header

pktData - the packet data

Returns:

true, if filter matched packet otherwise false

Since:

Pcap 1.0

openDead

public static Pcap openDead(PcapDlt linktype,
 int snaplen)
                     throws PcapException

Open a fake pcap_t for compiling filters or opening a capture for output.

openDead(org.jnetpcap.constant.PcapDlt, int) and pcap_open_dead_with_tstamp_precision() are used for creating a pcap_t structure to use when calling the other functions in libpcap. It is typically used when just using libpcap for compiling BPF full; it can also be used if using pcap_dump_open(3PCAP), pcap_dump(3PCAP), and pcap_dump_close(3PCAP) to write a savefile if there is no pcap_t that supplies the packets to be written.

When pcap_open_dead_with_tstamp_precision(), is used to create a pcap_t for use with pcap_dump_open(), precision specifies the time stamp precision for packets; PCAP_TSTAMP_PRECISION_MICRO should be specified if the packets to be written have time stamps in seconds and microseconds, and PCAP_TSTAMP_PRECISION_NANO should be specified if the packets to be written have time stamps in seconds and nanoseconds. Its value does not affect pcap_compile(3PCAP).

Parameters:

linktype - specifies the link-layer type for the pcap handle

snaplen - specifies the snapshot length for the pcap handle

Returns:

A dead pcap handle

Throws:

PcapException - any errors

Since:

libpcap 0.6

openDeadWithTstampPrecision

public static Pcap openDeadWithTstampPrecision(PcapDlt linktype,
 int snaplen,
 PcapTStampPrecision precision)
                                        throws PcapException

Open a fake pcap_t for compiling filters or opening a capture for output.

openDead(PcapDlt, int) and openDeadWithTstampPrecision(PcapDlt, int, PcapTStampPrecision) are used for creating a pcap_t structure to use when calling the other functions in libpcap. It is typically used when just using libpcap for compiling BPF full; it can also be used if using #dumpOpen(String), PcapDumper.dump(MemorySegment, MemorySegment), and PcapDumper.close() to write a savefile if there is no pcap_t that supplies the packets to be written.

When openDeadWithTstampPrecision(PcapDlt, int, PcapTStampPrecision), is used to create a Pcap handle for use with dumpOpen(String), precision specifies the time stamp precision for packets; PCAP_TSTAMP_PRECISION_MICRO should be specified if the packets to be written have time stamps in seconds and microseconds, and PCAP_TSTAMP_PRECISION_NANO should be specified if the packets to be written have time stamps in seconds and nanoseconds. Its value does not affect pcap_compile(3PCAP).

Parameters:

linktype - specifies the link-layer type for the pcap handle

snaplen - specifies the snapshot length for the pcap handle

precision - the requested timestamp precision

Returns:

A dead pcap handle

Throws:

PcapException - any errors

Since:

libpcap 1.5.1

openLive

public static Pcap openLive(PcapIf device,
 int snaplen,
 boolean promisc,
 long timeout,
 TimeUnit unit)
                     throws PcapException

Open a device for capturing.

openLive is used to obtain a packet capture handle to look at packets on the network. device is a string that specifies the network device to open; on Linux systems with 2.2 or later kernels, a device argument of "any" or NULL can be used to capture packets from all interfaces.

Parameters:

device - the device name

snaplen - specifies the snapshot length to be set on the handle

promisc - specifies whether the interface is to be put into promiscuous mode. If promisc is non-zero, promiscuous mode will be set, otherwise it will not be set

timeout - the packet buffer timeout, as a non-negative value, in units

unit - time timeout unit

Returns:

the pcap handle

Throws:

PcapException - any errors

Since:

libpcap 0.4

openLive

public static Pcap openLive(String device,
 int snaplen,
 boolean promisc,
 long timeout,
 TimeUnit unit)
                     throws PcapException

Open a device for capturing.

openLive is used to obtain a packet capture handle to look at packets on the network. device is a string that specifies the network device to open; on Linux systems with 2.2 or later kernels, a device argument of "any" or NULL can be used to capture packets from all interfaces.

Parameters:

device - the device name

snaplen - specifies the snapshot length to be set on the handle

promisc - specifies whether the interface is to be put into promiscuous mode. If promisc is non-zero, promiscuous mode will be set, otherwise it will not be set

timeout - the packet buffer timeout, as a non-negative value, in units

unit - time timeout unit

Returns:

the pcap handle

Throws:

PcapException - any errors

Since:

libpcap 0.4

openLive

public static Pcap openLive(String device,
 int snaplen,
 boolean promisc,
 Duration timeout)
                     throws PcapException

Open a device for capturing.

openLive is used to obtain a packet capture handle to look at packets on the network. device is a string that specifies the network device to open; on Linux systems with 2.2 or later kernels, a device argument of "any" or NULL can be used to capture packets from all interfaces.

Parameters:

device - the device name

snaplen - specifies the snapshot length to be set on the handle

promisc - specifies whether the interface is to be put into promiscuous mode. If promisc is non-zero, promiscuous mode will be set, otherwise it will not be set

timeout - the packet buffer timeout, as a non-negative duration

Returns:

the pcap handle

Throws:

PcapException - any errors

Since:

libpcap 0.4

openOffline

public static Pcap openOffline(File file)
                        throws PcapException

Open a saved capture file for reading.

pcap_open_offline() and pcap_open_offline_with_tstamp_precision() are called to open a ``savefile'' for reading.

Parameters:

file - the offline capture file

Returns:

the pcap handle

Throws:

PcapException - any errors

Since:

libpcap 0.4

openOffline

public static Pcap openOffline(String fname)
                        throws PcapException

Open a saved capture file for reading.

pcap_open_offline() and pcap_open_offline_with_tstamp_precision() are called to open a ``savefile'' for reading.

Parameters:

fname - specifies the name of the file to open. The file can have the pcap file format as described in pcap-savefile(5), which is the file format used by, among other programs, tcpdump(1) and tcpslice(1), or can have the pcapng file format, although not all pcapng files can be read

Returns:

the pcap handle

Throws:

PcapException - any errors

Since:

libpcap 0.4

statusToStr

public static String statusToStr(int error)

Convert an error full value to a string.

Parameters:

error - the error full to convert to a string

Returns:

the error string for the given full

Since:

libpcap 1.0

statusToStr

public static String statusToStr(PcapCode error)

Convert an error full value to a string.

Parameters:

error - the error full to convert to a string

Returns:

the error string for the given full

Since:

libpcap 1.0

strerror

public static String strerror(int code)

Convert an error full value to a string. This is a POSIX system error full, not pcap related as libpcap simply passes the errornum as a system call see https://linux.die.net/man/3/strerror.

Parameters:

code - the code

Returns:

the error string for the given full

Since:

libpcap 0.4

activate

public void activate()
              throws PcapActivatedException,
PcapException

Activate a capture handle

Is used to activate a packet capture handle to look at packets on the network, with the options that were set on the handle being in effect.

Throws:

PcapActivatedException - thrown if this pcap handle is already activated

PcapException - The possible error values are:

PCAP_ERROR_ACTIVATED

The handle has already been activated

PCAP_ERROR_NO_SUCH_DEVICE

e capture source specified when the handle was created doesn't exist

PCAP_ERROR_PERM_DENIED

The process doesn't have permission to open the capture source

PCAP_ERROR_PROMISC_PERM_DENIED

The process has permission to open the capture source but doesn't have permission to put it into promiscuous mode

PCAP_ERROR_RFMON_NOTSUP

Monitor mode was specified but the capture source doesn't support monitor mode

PCAP_ERROR_IFACE_NOT_UP

The capture source device is not up

PCAP_ERROR

Another error occurred

Since:

libpcap 1.0

See Also:

• int pcap_activate(pcap_t *)

breakloop

public void breakloop()

Force a dispatch or loop call to return.

Sets a flag that will force dispatch or loop to return rather than looping; they will return the number of packets that have been processed so far, or PcapConstants.PCAP_ERROR_BREAK if no packets have been processed so far.

This routine is safe to use inside a signal handler on UNIX or a console control handler on Windows, as it merely sets a flag that is checked within the loop.

The flag is checked in loops reading packets from the OS - a signal by itself will not necessarily terminate those loops - as well as in loops processing a set of packets returned by the OS. Note that if you are catching signals on UNIX systems that support restarting system calls after a signal, and calling breakloop in the signal handler, you must specify, when catching those signals, that system calls should NOT be restarted by that signal. Otherwise, if the signal interrupted a call reading packets in a live capture, when your signal handler returns after calling breakloop, the call will be restarted, and the loop will not terminate until more packets arrive and the call completes.

Note also that, in a multi-threaded application, if one thread is blocked in dispatch, loop, pcap_next(3PCAP), or nextEx, a call to breakloop in a different thread will not unblock that thread. You will need to use whatever mechanism the OS provides for breaking a thread out of blocking calls in order to unblock the thread, such as thread cancellation or thread signalling in systems that support POSIX threads, or SetEvent() on the result of pcap_getevent() on a pcap_t on which the thread is blocked on Windows. Asynchronous procedure calls will not work on Windows, as a thread blocked on a pcap_t will not be in an alertable state.

Note that next and nextEx will, on some platforms, loop reading packets from the OS; that loop will not necessarily be terminated by a signal, so breakloop should be used to terminate packet processing even if next or nextEx is being used.

breakloop does not guarantee that no further packets will be processed by dispatch or loop after it is called; at most one more packet might be processed.

If PcapConstants.PCAP_ERROR_BREAK is returned from dispatch or loop, the flag is cleared, so a subsequent call will resume reading packets. If a positive number is returned, the flag is not cleared, so a subsequent call will return PcapConstants.PCAP_ERROR_BREAK and clear the flag.

Since:

libpcap 0.8

canSetRfmon

public boolean canSetRfmon()
                    throws PcapException

check whether monitor mode can be set for a not-yet-activated capture handle.

Checks whether monitor mode could be set on a capture handle when the handle is activated.

Returns:

true, if rfmon is supported otherwise false

Throws:

PcapException - The possible error values are:

PCAP_ERROR_NO_SUCH_DEVICE - The capture source specified when the handle was created doesn't exist

PCAP_ERROR_PERM_DENIED - The process doesn't have permission to check whether monitor mode could be supported

PCAP_ERROR_ACTIVATED - The capture handle has already been activated

PCAP_ERROR - Another error occurred

Since:

libpcap 1.0

close

public void close()

Close a capture device or savefile

Closes the files associated with p and deallocates resources.

Specified by:

close in interface AutoCloseable

See Also:

• AutoCloseable.close()

compile

public BpFilter compile(String str,
 boolean optimize)
                 throws PcapException

Compile a filter expression without a netmask.

pcap_compile() is used to compile the string str into a filter program. See pcap-filter(7) for the syntax of that string. fp is a pointer to a bpf_program struct and is filled in by pcap_compile(). optimize controls whether optimization on the resulting full is performed. The netmask of the network on which packets are being captured isn't known to the program, or if packets are being captured on the Linux "any" pseudo-interface that can capture on more than one network, a value of PCAP_NETMASK_UNKNOWN can be supplied; tests for IPv4 broadcast addresses will fail to compile, but all other tests in the filter program will be OK.

NOTE: in libpcap 1.8.0 and later, pcap_compile() can be used in multiple threads within a single process. However, in earlier versions of libpcap, it is not safe to use pcap_compile() in multiple threads in a single process without some form of mutual exclusion allowing only one thread to call it at any given time.

Parameters:

str - filter expression to be compiled

optimize - controls whether optimization on the resulting full is performed

Returns:

the compiled filter

Throws:

PcapException - any errors

Since:

Pcap 0.4

compile

public BpFilter compile(String str,
 boolean optimize,
 int netmask)
                 throws PcapException

Compile a filter expression with netmask.

pcap_compile() is used to compile the string str into a filter program. See pcap-filter(7) for the syntax of that string. fp is a pointer to a bpf_program struct and is filled in by pcap_compile(). optimize controls whether optimization on the resulting full is performed. netmask specifies the IPv4 netmask of the network on which packets are being captured; it is used only when checking for IPv4 broadcast addresses in the filter program. If the netmask of the network on which packets are being captured isn't known to the program, or if packets are being captured on the Linux "any" pseudo-interface that can capture on more than one network, a value of PCAP_NETMASK_UNKNOWN can be supplied; tests for IPv4 broadcast addresses will fail to compile, but all other tests in the filter program will be OK.

NOTE: in libpcap 1.8.0 and later, pcap_compile() can be used in multiple threads within a single process. However, in earlier versions of libpcap, it is not safe to use pcap_compile() in multiple threads in a single process without some form of mutual exclusion allowing only one thread to call it at any given time.

Parameters:

str - filter expression to be compiled

optimize - controls whether optimization on the resulting full is performed

netmask - specifies the IPv4 netmask of the network on which packets are being captured; it is used only when checking for IPv4 broadcast addresses in the filter program. If the netmask of the network on which packets are being captured isn't known to the program, or if packets are being captured on the Linux "any" pseudo-interface that can capture on more than one network, a value of PCAP_NETMASK_UNKNOWN can be supplied; tests for IPv4 broadcast addresses will fail to compile, but all other tests in the filter program will be OK

Returns:

the compiled filter

Throws:

PcapException - any errors

Since:

Pcap 0.4

datalink

public PcapDlt datalink()
                 throws PcapException

Get the link-layer header type.

It must not be called on a pcap descriptor created by pcap_create(3PCAP) that has not yet been activated by pcap_activate.

https://www.tcpdump.org/linktypes.html lists the values pcap_datalink() can return and describes the packet formats that correspond to those values.

Do NOT assume that the packets for a given capture or ``savefile`` will have any given link-layer header type, such as DLT_EN10MB for Ethernet. For example, the "any" device on Linux will have a link-layer header type of DLT_LINUX_SLL or DLT_LINUX_SLL2 even if all devices on the system at the time the "any" device is opened have some other data link type, such as DLT_EN10MB for Ethernet.

Returns:

link-layer header type

Throws:

PcapException - any pcap errors

Since:

libpcap 0.4

dataLinkExt

public PcapDlt dataLinkExt()
                    throws PcapException

Gets the link-layer header type for the live capture or ``savefile''.

Returns:

link-layer header type

Throws:

PcapException - the pcap exception

dispatch

public <U> int dispatch(int count,
 PcapDumper pcapDumper)
                 throws PcapException

Process packets from a live capture or savefile and save them directly to dump file.

Processes packets from a live capture or ``savefile'' until cnt packets are processed, the end of the current bufferful of packets is reached when doing a live capture, the end of the ``savefile'' is reached when reading from a ``savefile'', pcap_breakloop() is called, or an error occurs. Thus, when doing a live capture, cnt is the maximum number of packets to process before returning, but is not a minimum number; when reading a live capture, only one bufferful of packets is read at a time, so fewer than cnt packets may be processed. A value of -1 or 0 for cnt causes all the packets received in one buffer to be processed when reading a live capture, and causes all the packets in the file to be processed when reading a ``savefile''.

Note that, when doing a live capture on some platforms, if the read timeout expires when there are no packets available, pcap_dispatch() will return 0, even when not in non-blocking mode, as there are no packets to process. Applications should be prepared for this to happen, but must not rely on it happening.

Callback specifies a pcap_handler routine to be called with three arguments: a u_char pointer which is passed in the user argument to pcap_loop() or pcap_dispatch(), a const struct pcap_pkthdr pointer pointing to the packet time stamp and lengths, and a const u_char pointer to the first caplen (as given in the struct pcap_pkthdr a pointer to which is passed to the callback routine) bytes of data from the packet. The struct pcap_pkthdr and the packet data are not to be freed by the callback routine, and are not guaranteed to be valid after the callback routine returns; if the full needs them to be valid after the callback, it must make a copy of them.

The bytes of data from the packet begin with a link-layer header. The format of the link-layer header is indicated by the return value of the pcap_datalink(3PCAP) routine when handed the pcap_t value also passed to pcap_loop() or pcap_dispatch(). https://www.tcpdump.org/linktypes.html lists the values pcap_datalink() can return and describes the packet formats that correspond to those values. The value it returns will be valid for all packets received unless and until pcap_set_datalink(3PCAP) is called; after a successful call to pcap_set_datalink(), all subsequent packets will have a link-layer header of the type specified by the link-layer header type value passed to pcap_set_datalink().

Do NOT assume that the packets for a given capture or ``savefile`` will have any given link-layer header type, such as DLT_EN10MB for Ethernet. For example, the "any" device on Linux will have a link-layer header type of DLT_LINUX_SLL or DLT_LINUX_SLL2 even if all devices on the system at the time the "any" device is opened have some other data link type, such as DLT_EN10MB for Ethernet.

Type Parameters:

U - the generic type

Parameters:

count - maximum number of packets to process before returning

pcapDumper - the pcap dumper

Returns:

the number of packets processed on success; this can be 0 if no packets were read from a live capture (if, for example, they were discarded because they didn't pass the packet filter, or if, on platforms that support a packet buffer timeout that starts before any packets arrive, the timeout expires before any packets arrive, or if the file descriptor for the capture device is in non-blocking mode and no packets were available to be read) or if no more packets are available in a ``savefile.''

Throws:

PcapException - any pcap exceptions during call setup

Since:

libpcap 0.4

dispatch

public int dispatch(int count,
 PcapHandler.NativeCallback handler,
 MemorySegment user)

Process packets from a live capture or savefile and dispatch using low level callback. The native callback is low level, and is only capable of passing native user objects and not compatible with java user objects.

Processes packets from a live capture or ``savefile'' until cnt packets are processed, the end of the current bufferful of packets is reached when doing a live capture, the end of the ``savefile'' is reached when reading from a ``savefile'', pcap_breakloop() is called, or an error occurs. Thus, when doing a live capture, cnt is the maximum number of packets to process before returning, but is not a minimum number; when reading a live capture, only one bufferful of packets is read at a time, so fewer than cnt packets may be processed. A value of -1 or 0 for cnt causes all the packets received in one buffer to be processed when reading a live capture, and causes all the packets in the file to be processed when reading a ``savefile''.

Note that, when doing a live capture on some platforms, if the read timeout expires when there are no packets available, pcap_dispatch() will return 0, even when not in non-blocking mode, as there are no packets to process. Applications should be prepared for this to happen, but must not rely on it happening.

Callback specifies a pcap_handler routine to be called with three arguments: a u_char pointer which is passed in the user argument to pcap_loop() or pcap_dispatch(), a const struct pcap_pkthdr pointer pointing to the packet time stamp and lengths, and a const u_char pointer to the first caplen (as given in the struct pcap_pkthdr a pointer to which is passed to the callback routine) bytes of data from the packet. The struct pcap_pkthdr and the packet data are not to be freed by the callback routine, and are not guaranteed to be valid after the callback routine returns; if the full needs them to be valid after the callback, it must make a copy of them.

The bytes of data from the packet begin with a link-layer header. The format of the link-layer header is indicated by the return value of the pcap_datalink(3PCAP) routine when handed the pcap_t value also passed to pcap_loop() or pcap_dispatch(). https://www.tcpdump.org/linktypes.html lists the values pcap_datalink() can return and describes the packet formats that correspond to those values. The value it returns will be valid for all packets received unless and until pcap_set_datalink(3PCAP) is called; after a successful call to pcap_set_datalink(), all subsequent packets will have a link-layer header of the type specified by the link-layer header type value passed to pcap_set_datalink().

Do NOT assume that the packets for a given capture or ``savefile`` will have any given link-layer header type, such as DLT_EN10MB for Ethernet. For example, the "any" device on Linux will have a link-layer header type of DLT_LINUX_SLL or DLT_LINUX_SLL2 even if all devices on the system at the time the "any" device is opened have some other data link type, such as DLT_EN10MB for Ethernet.

Parameters:

count - maximum number of packets to process before returning

handler - the handler

user - TODO

Returns:

the number of packets processed on success; this can be 0 if no packets were read from a live capture (if, for example, they were discarded because they didn't pass the packet filter, or if, on platforms that support a packet buffer timeout that starts before any packets arrive, the timeout expires before any packets arrive, or if the file descriptor for the capture device is in non-blocking mode and no packets were available to be read) or if no more packets are available in a ``savefile.''

Since:

libpcap 0.4

dispatch

public <U> int dispatch(int count,
 PcapHandler.OfArray<U> handler,
 U user)
                 throws PcapException

Process packets from a live capture or savefile and copy to a newly allocated array and dispatches to handler.

Processes packets from a live capture or ``savefile'' until cnt packets are processed, the end of the current bufferful of packets is reached when doing a live capture, the end of the ``savefile'' is reached when reading from a ``savefile'', pcap_breakloop() is called, or an error occurs. Thus, when doing a live capture, cnt is the maximum number of packets to process before returning, but is not a minimum number; when reading a live capture, only one bufferful of packets is read at a time, so fewer than cnt packets may be processed. A value of -1 or 0 for cnt causes all the packets received in one buffer to be processed when reading a live capture, and causes all the packets in the file to be processed when reading a ``savefile''.

Note that, when doing a live capture on some platforms, if the read timeout expires when there are no packets available, pcap_dispatch() will return 0, even when not in non-blocking mode, as there are no packets to process. Applications should be prepared for this to happen, but must not rely on it happening.

Callback specifies a pcap_handler routine to be called with three arguments: a u_char pointer which is passed in the user argument to pcap_loop() or pcap_dispatch(), a const struct pcap_pkthdr pointer pointing to the packet time stamp and lengths, and a const u_char pointer to the first caplen (as given in the struct pcap_pkthdr a pointer to which is passed to the callback routine) bytes of data from the packet. The struct pcap_pkthdr and the packet data are not to be freed by the callback routine, and are not guaranteed to be valid after the callback routine returns; if the full needs them to be valid after the callback, it must make a copy of them.

The bytes of data from the packet begin with a link-layer header. The format of the link-layer header is indicated by the return value of the pcap_datalink(3PCAP) routine when handed the pcap_t value also passed to pcap_loop() or pcap_dispatch(). https://www.tcpdump.org/linktypes.html lists the values pcap_datalink() can return and describes the packet formats that correspond to those values. The value it returns will be valid for all packets received unless and until pcap_set_datalink(3PCAP) is called; after a successful call to pcap_set_datalink(), all subsequent packets will have a link-layer header of the type specified by the link-layer header type value passed to pcap_set_datalink().

Do NOT assume that the packets for a given capture or ``savefile`` will have any given link-layer header type, such as DLT_EN10MB for Ethernet. For example, the "any" device on Linux will have a link-layer header type of DLT_LINUX_SLL or DLT_LINUX_SLL2 even if all devices on the system at the time the "any" device is opened have some other data link type, such as DLT_EN10MB for Ethernet.

Type Parameters:

U - the generic type

Parameters:

count - maximum number of packets to process before returning

handler - specifies a handler method to be called

user - the user opaque object

Returns:

the number of packets processed on success; this can be 0 if no packets were read from a live capture (if, for example, they were discarded because they didn't pass the packet filter, or if, on platforms that support a packet buffer timeout that starts before any packets arrive, the timeout expires before any packets arrive, or if the file descriptor for the capture device is in non-blocking mode and no packets were available to be read) or if no more packets are available in a ``savefile.''

Throws:

PcapException - any pcap exceptions during call setup

Since:

libpcap 0.4

dispatch

public <U> int dispatch(int count,
 PcapHandler.OfMemorySegment<U> handler,
 U user)
                 throws PcapException

Process packets from a live capture or savefile and dispatch directly to handler. The scope of each memory segment dispatched by this call is only valid for the duration of the dispatch to handler. After that, the packet memory is reused by libpcap and its contents no longer valid if retained.

Processes packets from a live capture or ``savefile'' until cnt packets are processed, the end of the current bufferful of packets is reached when doing a live capture, the end of the ``savefile'' is reached when reading from a ``savefile'', pcap_breakloop() is called, or an error occurs. Thus, when doing a live capture, cnt is the maximum number of packets to process before returning, but is not a minimum number; when reading a live capture, only one bufferful of packets is read at a time, so fewer than cnt packets may be processed. A value of -1 or 0 for cnt causes all the packets received in one buffer to be processed when reading a live capture, and causes all the packets in the file to be processed when reading a ``savefile''.

Note that, when doing a live capture on some platforms, if the read timeout expires when there are no packets available, pcap_dispatch() will return 0, even when not in non-blocking mode, as there are no packets to process. Applications should be prepared for this to happen, but must not rely on it happening.

Callback specifies a pcap_handler routine to be called with three arguments: a u_char pointer which is passed in the user argument to pcap_loop() or pcap_dispatch(), a const struct pcap_pkthdr pointer pointing to the packet time stamp and lengths, and a const u_char pointer to the first caplen (as given in the struct pcap_pkthdr a pointer to which is passed to the callback routine) bytes of data from the packet. The struct pcap_pkthdr and the packet data are not to be freed by the callback routine, and are not guaranteed to be valid after the callback routine returns; if the full needs them to be valid after the callback, it must make a copy of them.

The bytes of data from the packet begin with a link-layer header. The format of the link-layer header is indicated by the return value of the pcap_datalink(3PCAP) routine when handed the pcap_t value also passed to pcap_loop() or pcap_dispatch(). https://www.tcpdump.org/linktypes.html lists the values pcap_datalink() can return and describes the packet formats that correspond to those values. The value it returns will be valid for all packets received unless and until pcap_set_datalink(3PCAP) is called; after a successful call to pcap_set_datalink(), all subsequent packets will have a link-layer header of the type specified by the link-layer header type value passed to pcap_set_datalink().

Do NOT assume that the packets for a given capture or ``savefile`` will have any given link-layer header type, such as DLT_EN10MB for Ethernet. For example, the "any" device on Linux will have a link-layer header type of DLT_LINUX_SLL or DLT_LINUX_SLL2 even if all devices on the system at the time the "any" device is opened have some other data link type, such as DLT_EN10MB for Ethernet.

Type Parameters:

U - the generic type

Parameters:

count - maximum number of packets to process before returning

handler - specifies a handler method to be called

user - the user opaque object

Returns:

the number of packets processed on success; this can be 0 if no packets were read from a live capture (if, for example, they were discarded because they didn't pass the packet filter, or if, on platforms that support a packet buffer timeout that starts before any packets arrive, the timeout expires before any packets arrive, or if the file descriptor for the capture device is in non-blocking mode and no packets were available to be read) or if no more packets are available in a ``savefile.''

Throws:

PcapException - any pcap exceptions during call setup

Since:

libpcap 0.4

dumpOpen

public PcapDumper dumpOpen(String fname)
                    throws PcapException

Open a file to which to write packets.

pcap_dump_open() is called to open a ``savefile'' for writing. fname specifies the name of the file to open. The file will have the same format as those used by tcpdump(1) and tcpslice(1). If the file does not exist, it will be created; if the file exists, it will be truncated and overwritten. The name "-" is a synonym for stdout. pcap_dump_fopen() is called to write data to an existing open stream fp; this stream will be closed by a subsequent call to pcap_dump_close(3PCAP). The stream is assumed to be at the beginning of a file that has been newly created or truncated, so that writes will start at the beginning of the file. Note that on Windows, that stream should be opened in binary mode.

p is a capture or ``savefile'' handle returned by an earlier call to pcap_create(3PCAP) and activated by an earlier call to pcap_activate(3PCAP), or returned by an earlier call to pcap_open_offline(3PCAP), pcap_open_live(3PCAP), or pcap_open_dead(3PCAP). The time stamp precision, link-layer type, and snapshot length from p are used as the link-layer type and snapshot length of the output file.

pcap_dump_open_append() is like pcap_dump_open() but, if the file already exists, and is a pcap file with the same byte order as the host opening the file, and has the same time stamp precision, link-layer header type, and snapshot length as p, it will write new packets at the end of the file.

Parameters:

fname - the fname

Returns:

the pcap dumper

Throws:

PcapException - the pcap exception

Since:

libpcap 0.4

geterr

public String geterr()

Get libpcap error message text.

Returns:

the error text pertaining to the last pcap library error

Since:

libpcap 0.4

getErrorString

protected String getErrorString(int error)

Dynamic non-pcap utility method to convert libpcap error code to a string, by various fallback methods with an active pcap handle.

Parameters:

error - the code

Returns:

the error string

getName

public final String getName()

Gets the name of this pcap handle. The name by default is the offline filename or network interface name, if specified.

Returns:

the name of this pcap handle

getNonBlock

public boolean getNonBlock()
                    throws PcapException

Gets the state of non-blocking mode on a capture device.

pcap_setnonblock() puts a capture handle into ``non-blocking'' mode, or takes it out of ``non-blocking'' mode, depending on whether the nonblock argument is non-zero or zero. It has no effect on ``savefiles''. If there is an error, PCAP_ERROR is returned and errbuf is filled in with an appropriate error message; otherwise, 0 is returned. In ``non-blocking'' mode, an attempt to read from the capture descriptor with pcap_dispatch(3PCAP) and pcap_next_ex(3PCAP) will, if no packets are currently available to be read, return 0 immediately rather than blocking waiting for packets to arrive.

pcap_loop(3PCAP) will loop forever, consuming CPU time when no packets are currently available; pcap_dispatch() should be used instead. pcap_next(3PCAP) will return NULL if there are no packets currently available to read; this is indistinguishable from an error, so pcap_next_ex() should be used instead.

When first activated with pcap_activate(3PCAP) or opened with pcap_open_live(3PCAP), a capture handle is not in ``non-blocking mode''; a call to pcap_setnonblock() is required in order to put it into ``non-blocking'' mode.

Returns:

the non block

Throws:

PcapException - any pcap errors

Since:

libpcap 0.7

getPcapHandle

protected MemorySegment getPcapHandle()

Gets the pcap handle's memory address.

Returns:

the pcap handle

getTstampPrecision

public PcapTStampPrecision getTstampPrecision()
                                       throws PcapException

Get the time stamp precision returned in captures.

Returns the precision of the time stamp returned in packet captures on the pcap descriptor.

Returns:

returns PCAP_TSTAMP_PRECISION_MICRO or PCAP_TSTAMP_PRECISION_NANO, which indicates that pcap captures contains time stamps in microseconds or nanoseconds respectively

Throws:

PcapException - any pcap errors

Since:

libpcap 1.5

inject

public int inject(MemorySegment packet,
 int length)
           throws PcapException

Transmit a packet.

pcap_inject() sends a raw packet through the network interface; buf points to the data of the packet, including the link-layer header, and size is the number of bytes in the packet. Note that, even if you successfully open the network interface, you might not have permission to send packets on it, or it might not support sending packets; as pcap_open_live(3PCAP) doesn't have a flag to indicate whether to open for capturing, sending, or capturing and sending, you cannot request an open that supports sending and be notified at open time whether sending will be possible. Note also that some devices might not support sending packets.

Note that, on some platforms, the link-layer header of the packet that's sent might not be the same as the link-layer header of the packet supplied to pcap_inject(), as the source link-layer address, if the header contains such an address, might be changed to be the address assigned to the interface on which the packet it sent, if the platform doesn't support sending completely raw and unchanged packets. Even worse, some drivers on some platforms might change the link-layer type field to whatever value libpcap used when attaching to the device, even on platforms that do nominally support sending completely raw and unchanged packets.

pcap_sendpacket() is like pcap_inject(), but it returns 0 on success, rather than returning the number of bytes written. (pcap_inject() comes from OpenBSD; pcap_sendpacket() comes from WinPcap/Npcap. Both are provided for compatibility.)

Parameters:

packet - the packet

length - the packet length

Returns:

number of bytes written

Throws:

PcapException - the pcap exception

Since:

libpcap 0.9

inject

public final int inject(byte[] array)
                 throws PcapException

Transmit a packet.

pcap_inject() sends a raw packet through the network interface; buf points to the data of the packet, including the link-layer header, and size is the number of bytes in the packet. Note that, even if you successfully open the network interface, you might not have permission to send packets on it, or it might not support sending packets; as pcap_open_live(3PCAP) doesn't have a flag to indicate whether to open for capturing, sending, or capturing and sending, you cannot request an open that supports sending and be notified at open time whether sending will be possible. Note also that some devices might not support sending packets.

Note that, on some platforms, the link-layer header of the packet that's sent might not be the same as the link-layer header of the packet supplied to pcap_inject(), as the source link-layer address, if the header contains such an address, might be changed to be the address assigned to the interface on which the packet it sent, if the platform doesn't support sending completely raw and unchanged packets. Even worse, some drivers on some platforms might change the link-layer type field to whatever value libpcap used when attaching to the device, even on platforms that do nominally support sending completely raw and unchanged packets.

pcap_sendpacket() is like pcap_inject(), but it returns 0 on success, rather than returning the number of bytes written. (pcap_inject() comes from OpenBSD; pcap_sendpacket() comes from WinPcap/Npcap. Both are provided for compatibility.)

Parameters:

array - the array containing packet data, including the datalink layer

Returns:

number of bytes written

Throws:

PcapException - the pcap exception

inject

public final int inject(byte[] array,
 int offset,
 int length)
                 throws PcapException

Transmit a packet.

pcap_inject() sends a raw packet through the network interface; buf points to the data of the packet, including the link-layer header, and size is the number of bytes in the packet. Note that, even if you successfully open the network interface, you might not have permission to send packets on it, or it might not support sending packets; as pcap_open_live(3PCAP) doesn't have a flag to indicate whether to open for capturing, sending, or capturing and sending, you cannot request an open that supports sending and be notified at open time whether sending will be possible. Note also that some devices might not support sending packets.

Note that, on some platforms, the link-layer header of the packet that's sent might not be the same as the link-layer header of the packet supplied to pcap_inject(), as the source link-layer address, if the header contains such an address, might be changed to be the address assigned to the interface on which the packet it sent, if the platform doesn't support sending completely raw and unchanged packets. Even worse, some drivers on some platforms might change the link-layer type field to whatever value libpcap used when attaching to the device, even on platforms that do nominally support sending completely raw and unchanged packets.

pcap_sendpacket() is like pcap_inject(), but it returns 0 on success, rather than returning the number of bytes written. (pcap_inject() comes from OpenBSD; pcap_sendpacket() comes from WinPcap/Npcap. Both are provided for compatibility.)

Parameters:

array - the array containing packet data, including the datalink layer

offset - the offset into the byte array

length - the packet length

Returns:

number of bytes written

Throws:

PcapException - the pcap exception

inject

public final int inject(ByteBuffer buf)
                 throws PcapException

Transmit a packet.

pcap_inject() sends a raw packet through the network interface; buf points to the data of the packet, including the link-layer header, and size is the number of bytes in the packet. Note that, even if you successfully open the network interface, you might not have permission to send packets on it, or it might not support sending packets; as pcap_open_live(3PCAP) doesn't have a flag to indicate whether to open for capturing, sending, or capturing and sending, you cannot request an open that supports sending and be notified at open time whether sending will be possible. Note also that some devices might not support sending packets.

Note that, on some platforms, the link-layer header of the packet that's sent might not be the same as the link-layer header of the packet supplied to pcap_inject(), as the source link-layer address, if the header contains such an address, might be changed to be the address assigned to the interface on which the packet it sent, if the platform doesn't support sending completely raw and unchanged packets. Even worse, some drivers on some platforms might change the link-layer type field to whatever value libpcap used when attaching to the device, even on platforms that do nominally support sending completely raw and unchanged packets.

pcap_sendpacket() is like pcap_inject(), but it returns 0 on success, rather than returning the number of bytes written. (pcap_inject() comes from OpenBSD; pcap_sendpacket() comes from WinPcap/Npcap. Both are provided for compatibility.)

Parameters:

buf - The packet starts relative to the buffer's position (inclusive) and ends relative to the buffer's limit (exclusive)

Returns:

number of bytes written

Throws:

PcapException - the pcap exception

isSwapped

public boolean isSwapped()
                  throws PcapException

Find out whether a savefile has the native byte order.

Returns true if pcap refers to a ``savefile'' that uses a different byte order than the current system. For a live capture, it always returns false.

Returns:

true if swapped, otherwise false

Throws:

PcapException - any pcap errors

Since:

libpcap 0.4

See Also:

• order()

listDataLinks

public List<PcapDlt> listDataLinks()
                            throws PcapException

Get a list of link-layer header types supported by a capture device.

Returns:

a list of link-layer header types

Throws:

PcapException - any pcap errors

Since:

libpcap 0.8

listTstampTypes

public List<PcapTstampType> listTstampTypes()
                                     throws PcapException

Get a list of time stamp types supported by a capture device.

pcap_list_tstamp_types() is used to get a list of the supported time stamp types of the interface associated with the pcap descriptor

Returns:

a list of timestamp types

Throws:

PcapException - any pcap errors

Since:

libpcap 1.2

loop

public <U> int loop(int count,
 PcapDumper pcapDumper)
             throws PcapException

Process packets from a live capture or savefile and save them directly to dump file.

pcap_loop() processes packets from a live capture or ``savefile'' until cnt packets are processed, the end of the ``savefile'' is reached when reading from a ``savefile'', pcap_breakloop(3PCAP) is called, or an error occurs. It does not return when live packet buffer timeouts occur. A value of -1 or 0 for cnt is equivalent to infinity, so that packets are processed until another ending condition occurs.

Note that, when doing a live capture on some platforms, if the read timeout expires when there are no packets available, pcap_dispatch() will return 0, even when not in non-blocking mode, as there are no packets to process. Applications should be prepared for this to happen, but must not rely on it happening.

callback specifies a pcap_handler routine to be called with three arguments: a u_char pointer which is passed in the user argument to pcap_loop() or pcap_dispatch(), a const struct pcap_pkthdr pointer pointing to the packet time stamp and lengths, and a const u_char pointer to the first caplen (as given in the struct pcap_pkthdr a pointer to which is passed to the callback routine) bytes of data from the packet. The struct pcap_pkthdr and the packet data are not to be freed by the callback routine, and are not guaranteed to be valid after the callback routine returns; if the full needs them to be valid after the callback, it must make a copy of them.

The bytes of data from the packet begin with a link-layer header. The format of the link-layer header is indicated by the return value of the pcap_datalink(3PCAP) routine when handed the pcap_t value also passed to pcap_loop() or pcap_dispatch(). https://www.tcpdump.org/linktypes.html lists the values pcap_datalink() can return and describes the packet formats that correspond to those values. The value it returns will be valid for all packets received unless and until pcap_set_datalink(3PCAP) is called; after a successful call to pcap_set_datalink(), all subsequent packets will have a link-layer header of the type specified by the link-layer header type value passed to pcap_set_datalink().

Do NOT assume that the packets for a given capture or ``savefile`` will have any given link-layer header type, such as DLT_EN10MB for Ethernet. For example, the "any" device on Linux will have a link-layer header type of DLT_LINUX_SLL or DLT_LINUX_SLL2 even if all devices on the system at the time the "any" device is opened have some other data link type, such as DLT_EN10MB for Ethernet.

Type Parameters:

U - the generic user data type

Parameters:

count - A value of -1 or 0 for count is equivalent to infinity, so that packets are processed until another ending condition occurs

pcapDumper - the pcap dumper

Returns:

returns 0 if count is exhausted or if, when reading from a ``savefile'', no more packets are available. It returns PCAP_ERROR_BREAK if the loop terminated due to a call to pcap_breakloop() before any packets were processed

Throws:

PcapException - any pcap errors

Since:

libpcap 0.4

loop

public <U> int loop(int count,
 PcapHandler.NativeCallback handler,
 MemorySegment user)

Process packets from a live capture or savefile and dispatch using low level callback. The native callback is low level, and is only capable of passing native user objects and not compatible with java user objects.

pcap_loop() processes packets from a live capture or ``savefile'' until cnt packets are processed, the end of the ``savefile'' is reached when reading from a ``savefile'', pcap_breakloop(3PCAP) is called, or an error occurs. It does not return when live packet buffer timeouts occur. A value of -1 or 0 for cnt is equivalent to infinity, so that packets are processed until another ending condition occurs.

Note that, when doing a live capture on some platforms, if the read timeout expires when there are no packets available, pcap_dispatch() will return 0, even when not in non-blocking mode, as there are no packets to process. Applications should be prepared for this to happen, but must not rely on it happening.

callback specifies a pcap_handler routine to be called with three arguments: a u_char pointer which is passed in the user argument to pcap_loop() or pcap_dispatch(), a const struct pcap_pkthdr pointer pointing to the packet time stamp and lengths, and a const u_char pointer to the first caplen (as given in the struct pcap_pkthdr a pointer to which is passed to the callback routine) bytes of data from the packet. The struct pcap_pkthdr and the packet data are not to be freed by the callback routine, and are not guaranteed to be valid after the callback routine returns; if the full needs them to be valid after the callback, it must make a copy of them.

The bytes of data from the packet begin with a link-layer header. The format of the link-layer header is indicated by the return value of the pcap_datalink(3PCAP) routine when handed the pcap_t value also passed to pcap_loop() or pcap_dispatch(). https://www.tcpdump.org/linktypes.html lists the values pcap_datalink() can return and describes the packet formats that correspond to those values. The value it returns will be valid for all packets received unless and until pcap_set_datalink(3PCAP) is called; after a successful call to pcap_set_datalink(), all subsequent packets will have a link-layer header of the type specified by the link-layer header type value passed to pcap_set_datalink().

Do NOT assume that the packets for a given capture or ``savefile`` will have any given link-layer header type, such as DLT_EN10MB for Ethernet. For example, the "any" device on Linux will have a link-layer header type of DLT_LINUX_SLL or DLT_LINUX_SLL2 even if all devices on the system at the time the "any" device is opened have some other data link type, such as DLT_EN10MB for Ethernet.

Type Parameters:

U - the generic user data type

Parameters:

count - A value of -1 or 0 for count is equivalent to infinity, so that packets are processed until another ending condition occurs

handler - the native handler which receives packets

user - native user object

Returns:

returns 0 if count is exhausted or if, when reading from a ``savefile'', no more packets are available. It returns PCAP_ERROR_BREAK if the loop terminated due to a call to pcap_breakloop() before any packets were processed

Since:

libpcap 0.4

loop

public <U> int loop(int count,
 PcapHandler.OfArray<U> handler,
 U user)
             throws PcapException

Process packets from a live capture or savefile and copy to a newly allocated array and dispatches to handler.

pcap_loop() processes packets from a live capture or ``savefile'' until cnt packets are processed, the end of the ``savefile'' is reached when reading from a ``savefile'', pcap_breakloop(3PCAP) is called, or an error occurs. It does not return when live packet buffer timeouts occur. A value of -1 or 0 for cnt is equivalent to infinity, so that packets are processed until another ending condition occurs.

Note that, when doing a live capture on some platforms, if the read timeout expires when there are no packets available, pcap_dispatch() will return 0, even when not in non-blocking mode, as there are no packets to process. Applications should be prepared for this to happen, but must not rely on it happening.

callback specifies a pcap_handler routine to be called with three arguments: a u_char pointer which is passed in the user argument to pcap_loop() or pcap_dispatch(), a const struct pcap_pkthdr pointer pointing to the packet time stamp and lengths, and a const u_char pointer to the first caplen (as given in the struct pcap_pkthdr a pointer to which is passed to the callback routine) bytes of data from the packet. The struct pcap_pkthdr and the packet data are not to be freed by the callback routine, and are not guaranteed to be valid after the callback routine returns; if the full needs them to be valid after the callback, it must make a copy of them.

The bytes of data from the packet begin with a link-layer header. The format of the link-layer header is indicated by the return value of the pcap_datalink(3PCAP) routine when handed the pcap_t value also passed to pcap_loop() or pcap_dispatch(). https://www.tcpdump.org/linktypes.html lists the values pcap_datalink() can return and describes the packet formats that correspond to those values. The value it returns will be valid for all packets received unless and until pcap_set_datalink(3PCAP) is called; after a successful call to pcap_set_datalink(), all subsequent packets will have a link-layer header of the type specified by the link-layer header type value passed to pcap_set_datalink().

Do NOT assume that the packets for a given capture or ``savefile`` will have any given link-layer header type, such as DLT_EN10MB for Ethernet. For example, the "any" device on Linux will have a link-layer header type of DLT_LINUX_SLL or DLT_LINUX_SLL2 even if all devices on the system at the time the "any" device is opened have some other data link type, such as DLT_EN10MB for Ethernet.

Type Parameters:

U - the generic user data type

Parameters:

count - A value of -1 or 0 for count is equivalent to infinity, so that packets are processed until another ending condition occurs

handler - array handler which will receive packets

user - user opaque data to be returned with the callback

Returns:

returns 0 if count is exhausted or if, when reading from a ``savefile'', no more packets are available. It returns PCAP_ERROR_BREAK if the loop terminated due to a call to pcap_breakloop() before any packets were processed

Throws:

PcapException - any pcap errors

Since:

libpcap 0.4

loop

public <U> int loop(int count,
 PcapHandler.OfMemorySegment<U> handler,
 U user)

Process packets from a live capture or savefile and dispatch directly to handler. The scope of each memory segment dispatched by this call is only valid for the duration of the dispatch to handler. After that, the packet memory is reused by libpcap and its contents no longer valid if retained.

pcap_loop() processes packets from a live capture or ``savefile'' until cnt packets are processed, the end of the ``savefile'' is reached when reading from a ``savefile'', pcap_breakloop(3PCAP) is called, or an error occurs. It does not return when live packet buffer timeouts occur. A value of -1 or 0 for cnt is equivalent to infinity, so that packets are processed until another ending condition occurs.

Note that, when doing a live capture on some platforms, if the read timeout expires when there are no packets available, pcap_dispatch() will return 0, even when not in non-blocking mode, as there are no packets to process. Applications should be prepared for this to happen, but must not rely on it happening.

callback specifies a pcap_handler routine to be called with three arguments: a u_char pointer which is passed in the user argument to pcap_loop() or pcap_dispatch(), a const struct pcap_pkthdr pointer pointing to the packet time stamp and lengths, and a const u_char pointer to the first caplen (as given in the struct pcap_pkthdr a pointer to which is passed to the callback routine) bytes of data from the packet. The struct pcap_pkthdr and the packet data are not to be freed by the callback routine, and are not guaranteed to be valid after the callback routine returns; if the full needs them to be valid after the callback, it must make a copy of them.

The bytes of data from the packet begin with a link-layer header. The format of the link-layer header is indicated by the return value of the pcap_datalink(3PCAP) routine when handed the pcap_t value also passed to pcap_loop() or pcap_dispatch(). https://www.tcpdump.org/linktypes.html lists the values pcap_datalink() can return and describes the packet formats that correspond to those values. The value it returns will be valid for all packets received unless and until pcap_set_datalink(3PCAP) is called; after a successful call to pcap_set_datalink(), all subsequent packets will have a link-layer header of the type specified by the link-layer header type value passed to pcap_set_datalink().

Do NOT assume that the packets for a given capture or ``savefile`` will have any given link-layer header type, such as DLT_EN10MB for Ethernet. For example, the "any" device on Linux will have a link-layer header type of DLT_LINUX_SLL or DLT_LINUX_SLL2 even if all devices on the system at the time the "any" device is opened have some other data link type, such as DLT_EN10MB for Ethernet.

Type Parameters:

U - the generic type

Parameters:

count - A value of -1 or 0 for count is equivalent to infinity, so that packets are processed until another ending condition occurs

handler - array handler which will receive packets

user - the user opaque java object

Returns:

returns 0 if count is exhausted or if, when reading from a ``savefile'', no more packets are available. It returns PCAP_ERROR_BREAK if the loop terminated due to a call to pcap_breakloop() before any packets were processed

Since:

libpcap 0.4

majorVersion

public int majorVersion()
                 throws PcapException

Get the version number of a savefile.

If p refers to a ``savefile'', majorVersion returns the major number of the file format of the ``savefile''. The version number is stored in the ``savefile''; note that the meaning of its values depends on the type of ``savefile'' (for example, pcap or pcapng).

If pcap handle refers to a live capture, the values returned by majorVersion and pcap_minor_version() are not meaningful.

Returns:

the major number of the file format of the ``savefile''

Throws:

PcapException - the pcap exception

minorVersion

public int minorVersion()
                 throws PcapException

Get the version number of a savefile.

If p refers to a ``savefile'', minorVersion returns the minor number of the file format of the ``savefile''. The version number is stored in the ``savefile''; note that the meaning of its values depends on the type of ``savefile'' (for example, pcap or pcapng).

If pcap handle refers to a live capture, the values returned by majorVersion and pcap_minor_version() are not meaningful.

Returns:

the minor number of the file format of the ``savefile''

Throws:

PcapException - the pcap exception

next

public PcapPacketRef next()
                   throws PcapException

read the next packet from a handle.

reads the next packet (by calling dispatch with a cnt of 1) and returns a u_char pointer to the data in that packet. The packet data is not to be freed by the caller, and is not guaranteed to be valid after the next call to nextEx, next, loop, or dispatch; if the full needs it to remain valid, it must make a copy of it. The pcap_pkthdr structure pointed to by h is filled in with the appropriate values for the packet.

The bytes of data from the packet begin with a link-layer header. The format of the link-layer header is indicated by the return value of the datalink routine when handed the pcap_t value also passed to loop or dispatch. https://www.tcpdump.org/linktypes.html lists the values datalink can return and describes the packet formats that correspond to those values. The value it returns will be valid for all packets received unless and until setDatalink is called; after a successful call to setDatalink, all subsequent packets will have a link-layer header of the type specified by the link-layer header type value passed to setDatalink.

Do NOT assume that the packets for a given capture or ``savefile`` will have any given link-layer header type, such as DLT_EN10MB for Ethernet. For example, the "any" device on Linux will have a link-layer header type of DLT_LINUX_SLL or DLT_LINUX_SLL2 even if all devices on the system at the time the "any" device is opened have some other data link type, such as DLT_EN10MB for Ethernet.

Returns:

a pointer to the packet data on success, and returns NULL if no packets were read from a live capture (if, for example, they were discarded because they didn't pass the packet filter, or if, on platforms that support a packet buffer timeout that starts before any packets arrive, the timeout expires before any packets arrive, or if the file descriptor for the capture device is in non-blocking mode and no packets were available to be read), or if no more packets are available in a ``savefile.'' Unfortunately, there is no way to determine whether an error occurred or not.

Throws:

PcapException - Unfortunately, there is no way to determine whether an error occurred or not so exception may be due to no packets being captured and not an actual error.

Since:

libpcap 0.4

nextEx

public PcapPacketRef nextEx()
                     throws PcapException,
TimeoutException

Read the next packet from a pcap handle.

reads the next packet and returns a success/failure indication. If the packet was read without problems, the pointer pointed to by the pktHeader argument is set to point to the pcap_pkthdr struct for the packet, and the pointer pointed to by the pktData argument is set to point to the data in the packet. The struct pcap_pkthdr and the packet data are not to be freed by the caller, and are not guaranteed to be valid after the next call to nextEx(), next(), loop(int, org.jnetpcap.PcapDumper), or dispatch(int, org.jnetpcap.PcapDumper); if the full needs them to remain valid, it must make a copy of them. *

The bytes of data from the packet begin with a link-layer header. The format of the link-layer header is indicated by the return value of the datalink routine when handed the pcap_t value also passed to loop or dispatch. https://www.tcpdump.org/linktypes.html lists the values datalink can return and describes the packet formats that correspond to those values. The value it returns will be valid for all packets received unless and until setDatalink is called; after a successful call to setDatalink, all subsequent packets will have a link-layer header of the type specified by the link-layer header type value passed to setDatalink.

Do NOT assume that the packets for a given capture or ``savefile`` will have any given link-layer header type, such as DLT_EN10MB for Ethernet. For example, the "any" device on Linux will have a link-layer header type of DLT_LINUX_SLL or DLT_LINUX_SLL2 even if all devices on the system at the time the "any" device is opened have some other data link type, such as DLT_EN10MB for Ethernet.

Returns:

a native pcap packet reference or null if packets are being read from a ``savefile'' and there are no more packets to read from the savefile.

Throws:

PcapException - any pcap errors such as not activated, etc.

TimeoutException - if packets are being read from a live capture and the packet buffer timeout expired

Since:

Pcap 0.8

order

public final ByteOrder order()
                      throws PcapException

Returns the ByteOrder of the current capture based on results from isSwapped() method call. Calculates the actual byte order of the data. For live captures this will equal the native byte order for capture files, it can be either little or big depending on how the ``savefile'' was saved.

Returns:

the byte order

Throws:

PcapException - the pcap exception

See Also:

• isSwapped()

perror

public Pcap perror(String prefix)

Print libpcap error message text.

prints the text of the last pcap library error on stderr, prefixed by prefix

Parameters:

prefix - the message prefix

Returns:

this pcap handle

sendPacket

public void sendPacket(MemorySegment packet,
 int length)
                throws PcapException

Transmit a packet.

pcap_sendpacket() sends a raw packet through the network interface; buf points to the data of the packet, including the link-layer header, and size is the number of bytes in the packet. Note that, even if you successfully open the network interface, you might not have permission to send packets on it, or it might not support sending packets; as pcap_open_live(3PCAP) doesn't have a flag to indicate whether to open for capturing, sending, or capturing and sending, you cannot request an open that supports sending and be notified at open time whether sending will be possible. Note also that some devices might not support sending packets.

Note that, on some platforms, the link-layer header of the packet that's sent might not be the same as the link-layer header of the packet supplied to pcap_sendpacket(), as the source link-layer address, if the header contains such an address, might be changed to be the address assigned to the interface on which the packet it sent, if the platform doesn't support sending completely raw and unchanged packets. Even worse, some drivers on some platforms might change the link-layer type field to whatever value libpcap used when attaching to the device, even on platforms that do nominally support sending completely raw and unchanged packets.

Parameters:

packet - the packet

length - the length number of bytes to send

Throws:

PcapException - the pcap exception

Since:

libpcap 0.8

sendPacket

public final void sendPacket(byte[] buf)
                      throws PcapException

Transmit a packet.

pcap_sendpacket() sends a raw packet through the network interface; buf points to the data of the packet, including the link-layer header, and size is the number of bytes in the packet. Note that, even if you successfully open the network interface, you might not have permission to send packets on it, or it might not support sending packets; as pcap_open_live(3PCAP) doesn't have a flag to indicate whether to open for capturing, sending, or capturing and sending, you cannot request an open that supports sending and be notified at open time whether sending will be possible. Note also that some devices might not support sending packets.

Note that, on some platforms, the link-layer header of the packet that's sent might not be the same as the link-layer header of the packet supplied to pcap_sendpacket(), as the source link-layer address, if the header contains such an address, might be changed to be the address assigned to the interface on which the packet it sent, if the platform doesn't support sending completely raw and unchanged packets. Even worse, some drivers on some platforms might change the link-layer type field to whatever value libpcap used when attaching to the device, even on platforms that do nominally support sending completely raw and unchanged packets.

Parameters:

buf - the buf

Throws:

PcapException - the pcap exception

Since:

libpcap 0.8

sendPacket

public final void sendPacket(byte[] buf,
 int offset,
 int length)
                      throws PcapException

Transmit a packet.

pcap_sendpacket() sends a raw packet through the network interface; buf points to the data of the packet, including the link-layer header, and size is the number of bytes in the packet. Note that, even if you successfully open the network interface, you might not have permission to send packets on it, or it might not support sending packets; as pcap_open_live(3PCAP) doesn't have a flag to indicate whether to open for capturing, sending, or capturing and sending, you cannot request an open that supports sending and be notified at open time whether sending will be possible. Note also that some devices might not support sending packets.

Note that, on some platforms, the link-layer header of the packet that's sent might not be the same as the link-layer header of the packet supplied to pcap_sendpacket(), as the source link-layer address, if the header contains such an address, might be changed to be the address assigned to the interface on which the packet it sent, if the platform doesn't support sending completely raw and unchanged packets. Even worse, some drivers on some platforms might change the link-layer type field to whatever value libpcap used when attaching to the device, even on platforms that do nominally support sending completely raw and unchanged packets.

Parameters:

buf - array buffer containing packet data to send

offset - the offset into the buf array

length - the length number of bytes to send

Throws:

PcapException - the pcap exception

Since:

libpcap 0.8

sendPacket

public final void sendPacket(ByteBuffer buf)
                      throws PcapException

Transmit a packet.

pcap_sendpacket() sends a raw packet through the network interface; buf points to the data of the packet, including the link-layer header, and size is the number of bytes in the packet. Note that, even if you successfully open the network interface, you might not have permission to send packets on it, or it might not support sending packets; as pcap_open_live(3PCAP) doesn't have a flag to indicate whether to open for capturing, sending, or capturing and sending, you cannot request an open that supports sending and be notified at open time whether sending will be possible. Note also that some devices might not support sending packets.

Note that, on some platforms, the link-layer header of the packet that's sent might not be the same as the link-layer header of the packet supplied to pcap_sendpacket(), as the source link-layer address, if the header contains such an address, might be changed to be the address assigned to the interface on which the packet it sent, if the platform doesn't support sending completely raw and unchanged packets. Even worse, some drivers on some platforms might change the link-layer type field to whatever value libpcap used when attaching to the device, even on platforms that do nominally support sending completely raw and unchanged packets.

Parameters:

buf - The packet starts relative to the buffer's position (inclusive) and ends relative to the buffer's limit (exclusive)

Throws:

PcapException - the pcap exception

Since:

libpcap 0.8

setBufferSize

public Pcap setBufferSize(int bufferSize)
                   throws PcapException

Sets the buffer size for a not-yet- activated capture handle.

sets the buffer size that will be used on a capture handle when the handle is activated to buffer_size, which is in units of bytes

Parameters:

bufferSize - the buffer size in units of bytes

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 1.0

setDatalink

public Pcap setDatalink(int dlt)
                 throws PcapException

Set the link-layer header type to be used by a capture device .

Parameters:

dlt - link-layer header type

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 0.8

setDatalink

public Pcap setDatalink(Optional<PcapDlt> dlt)
                 throws PcapException

Set the link-layer header type to be used by a capture device .

Parameters:

dlt - link-layer header type

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 0.8

setDatalink

public Pcap setDatalink(PcapDlt dlt)
                 throws PcapException

Set the link-layer header type to be used by a capture device .

Parameters:

dlt - link-layer header type

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 0.8

setDirection

public Pcap setDirection(int dir)
                  throws PcapException

pcap_setdirection() is used to specify a direction that packets will be captured. d is one of the constants PCAP_D_IN, PCAP_D_OUT or PCAP_D_INOUT. PCAP_D_IN will only capture packets received by the device, PCAP_D_OUT will only capture packets sent by the device and PCAP_D_INOUT will capture packets received by or sent by the device. PCAP_D_INOUT is the default setting if this function is not called. pcap_setdirection() isn't necessarily fully supported on all platforms; some platforms might return an error for all values, and some other platforms might not support PCAP_D_OUT.

This operation is not supported if a ``savefile'' is being read.

Parameters:

dir - one of the constants PCAP_D_IN, PCAP_D_OUT or PCAP_D_INOUT

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 0.9

setDirection

public Pcap setDirection(Optional<PcapDirection> dir)
                  throws PcapException

Set the direction for which packets will be captured.

pcap_setdirection() is used to specify a direction that packets will be captured. d is one of the constants PCAP_D_IN, PCAP_D_OUT or PCAP_D_INOUT. PCAP_D_IN will only capture packets received by the device, PCAP_D_OUT will only capture packets sent by the device and PCAP_D_INOUT will capture packets received by or sent by the device. PCAP_D_INOUT is the default setting if this function is not called. pcap_setdirection() isn't necessarily fully supported on all platforms; some platforms might return an error for all values, and some other platforms might not support PCAP_D_OUT.

This operation is not supported if a ``savefile'' is being read.

Parameters:

dir - one of the constants PCAP_D_IN, PCAP_D_OUT or PCAP_D_INOUT

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 0.9

setDirection

public Pcap setDirection(PcapDirection dir)
                  throws PcapException

Set the direction for which packets will be captured.

pcap_setdirection() is used to specify a direction that packets will be captured. d is one of the constants PCAP_D_IN, PCAP_D_OUT or PCAP_D_INOUT. PCAP_D_IN will only capture packets received by the device, PCAP_D_OUT will only capture packets sent by the device and PCAP_D_INOUT will capture packets received by or sent by the device. PCAP_D_INOUT is the default setting if this function is not called. pcap_setdirection() isn't necessarily fully supported on all platforms; some platforms might return an error for all values, and some other platforms might not support PCAP_D_OUT.

This operation is not supported if a ``savefile'' is being read.

Parameters:

dir - one of the constants PCAP_D_IN, PCAP_D_OUT or PCAP_D_INOUT

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 0.9

setFilter

public Pcap setFilter(BpFilter bpfProgram)
               throws PcapException

set the filter.

is used to specify a filter program.

Parameters:

bpfProgram - bpf_program struct, usually the result of a call to pcap_compile

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 0.4

setFilter

public Pcap setFilter(Optional<BpFilter> bpfProgram)
               throws PcapException

set the filter.

is used to specify a filter program.

Parameters:

bpfProgram - bpf_program struct, usually the result of a call to pcap_compile

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 0.4

setImmediateMode

public Pcap setImmediateMode(boolean enable)
                      throws PcapException

Set immediate mode for a not-yet- activated capture handle.

sets whether immediate mode should be set on a capture handle when the handle is activated. In immediate mode, packets are always delivered as soon as they arrive, with no buffering. If immediate_mode is non-zero, immediate mode will be set, otherwise it will not be set.

Parameters:

enable - if true, enable immediate mode, otherwise disable

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 1.5

setNonBlock

public Pcap setNonBlock(boolean blockMode)
                 throws PcapException

Sets the state of non-blocking mode on a capture device.

pcap_setnonblock() puts a capture handle into ``non-blocking'' mode, or takes it out of ``non-blocking'' mode, depending on whether the nonblock argument is non-zero or zero. It has no effect on ``savefiles''. If there is an error, PCAP_ERROR is returned and errbuf is filled in with an appropriate error message; otherwise, 0 is returned. In ``non-blocking'' mode, an attempt to read from the capture descriptor with pcap_dispatch(3PCAP) and pcap_next_ex(3PCAP) will, if no packets are currently available to be read, return 0 immediately rather than blocking waiting for packets to arrive.

pcap_loop(3PCAP) will loop forever, consuming CPU time when no packets are currently available; pcap_dispatch() should be used instead. pcap_next(3PCAP) will return NULL if there are no packets currently available to read; this is indistinguishable from an error, so pcap_next_ex() should be used instead.

When first activated with pcap_activate(3PCAP) or opened with pcap_open_live(3PCAP), a capture handle is not in ``non-blocking mode''; a call to pcap_setnonblock() is required in order to put it into ``non-blocking'' mode.

Parameters:

blockMode - if true enable non blocking mode, otherwise block

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 10.7

setPromisc

public Pcap setPromisc(boolean promiscousMode)
                throws PcapException

Set promiscuous mode for a not-yet-activated capture handle.

pcap_set_promisc() sets whether promiscuous mode should be set on a capture handle when the handle is activated. If promisc is non-zero, promiscuous mode will be set, otherwise it will not be set.

Parameters:

promiscousMode - if true enable promiscous mode, otherwise disable it

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 1.0

setRfmon

public Pcap setRfmon(boolean rfMonitor)
              throws PcapException

Set monitor mode for a not-yet-activated capture handle.

Sets whether monitor mode should be set on a capture handle when the handle is activated. If rfmon is true, monitor mode will be set, otherwise it will not be set.

Parameters:

rfMonitor - the enable rfmon

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 1.0

setSnaplen

public Pcap setSnaplen(int snaplen)
                throws PcapException

Set the snapshot length for a not-yet-activated capture handle.

pcap_set_snaplen() sets the snapshot length to be used on a capture handle when the handle is activated to snaplen.

Parameters:

snaplen - the snapshot length

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

setTimeout

public Pcap setTimeout(int timeoutInMillis)
                throws PcapException

Set the packet buffer timeout for a not-yet-activated capture handle.

pcap_set_timeout() sets the packet buffer timeout that will be used on a capture handle when the handle is activated to to_ms, which is in units of milliseconds. (See pcap(3PCAP) for an explanation of the packet buffer timeout.)

The behavior, if the timeout isn't specified, is undefined, as is the behavior if the timeout is set to zero or to a negative value. We recommend always setting the timeout to a non-zero value unless immediate mode is set, in which case the timeout has no effect. *

Parameters:

timeoutInMillis - the timeout in milliseconds

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 1.0

setTstampPrecision

public Pcap setTstampPrecision(PcapTStampPrecision precision)
                        throws PcapException

Set the time stamp precision returned in captures.

pcap_set_tstamp_precision() sets the precision of the time stamp desired for packets captured on the pcap descriptor to the type specified by tstamp_precision. It must be called on a pcap descriptor created by pcap_create(3PCAP) that has not yet been activated by pcap_activate(3PCAP). Two time stamp precisions are supported, microseconds and nanoseconds. One can use options PCAP_TSTAMP_PRECISION_MICRO and PCAP_TSTAMP_PRECISION_NANO to request desired precision. By default, time stamps are in microseconds.

Parameters:

precision - one of the following constants PCAP_TSTAMP_PRECISION_MICRO and PCAP_TSTAMP_PRECISION_NANO

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 1.5

setTstampType

public Pcap setTstampType(PcapTstampType type)
                   throws PcapException

Set the time stamp type to be used by a capture device.

pcap_set_tstamp_type() sets the type of time stamp desired for packets captured on the pcap descriptor to the type specified by tstamp_type. It must be called on a pcap descriptor created by pcap_create(3PCAP) that has not yet been activated by pcap_activate(3PCAP). pcap_list_tstamp_types(3PCAP) will give a list of the time stamp types supported by a given capture device. See pcap-tstamp(7) for a list of all the time stamp types.

Parameters:

type - the type

Returns:

this pcap handle

Throws:

PcapException - the pcap exception

Since:

libpcap 1.2

snapshot

public int snapshot()
             throws PcapException

Get the snapshot length.

snapshot returns the snapshot length specified when setSnaplen(int) or openLive(String, int, boolean, long, TimeUnit) was called, for a live capture, or the snapshot length from the capture file, for a ``savefile''.

Returns:

the snapshot length

Throws:

PcapException - the pcap exception

stats

public PcapStat stats()
               throws PcapException

Get capture statistics.

pcap_stats() fills in the struct pcap_stat pointed to by its second argument. The values represent packet statistics from the start of the run to the time of the call.

pcap_stats() is supported only on live captures, not on ``savefiles''; no statistics are stored in ``savefiles'', so no statistics are available when reading from a ``savefile''.

A struct pcap_stat has the following members:

ps_recv

number of packets received;

ps_drop

number of packets dropped because there was no room in the operating system's buffer when they arrived, because packets weren't being read fast enough;

ps_ifdrop

number of packets dropped by the network interface or its driver.

The statistics do not behave the same way on all platforms. ps_recv might count packets whether they passed any filter set with pcap_setfilter(3PCAP) or not, or it might count only packets that pass the filter. It also might, or might not, count packets dropped because there was no room in the operating system's buffer when they arrived. ps_drop is not available on all platforms; it is zero on platforms where it's not available. If packet filtering is done in libpcap, rather than in the operating system, it would count packets that don't pass the filter. Both ps_recv and ps_drop might, or might not, count packets not yet read from the operating system and thus not yet seen by the application. ps_ifdrop might, or might not, be implemented; if it's zero, that might mean that no packets were dropped by the interface, or it might mean that the statistic is unavailable, so it should not be treated as an indication that the interface did not drop any packets.

Returns:

the pcap stat

Throws:

PcapException - the pcap exception

Since:

libpcap 0.4

toString

public String toString()

Debug info about this pcap handle.

Overrides:

toString in class Object

Returns:

the string

See Also:

• Object.toString()

getPcapHeaderABI

public PcapHeaderABI getPcapHeaderABI()

Gets the pcap header ABI (Abstract Binary Interface). Pcap ABI is used to interpret native structures such as pcap descriptor, correctly on any specific hardware platform. The ABI abstracts how native integers and primitive types are represented by CPU architecture on a specific platform.

Returns:

the ABI of the pcap header for this pcap handle on this CPU architecture

setUncaughtExceptionHandler

public Pcap setUncaughtExceptionHandler(Consumer<? super Throwable> exceptionHandler)

Sets the uncaught exception handler for loop(int, org.jnetpcap.PcapDumper) and dispatch(int, org.jnetpcap.PcapDumper) methods. Any exception thrown within the user callback methods, will be caught and sent to the specified user exception handler.

Parameters:

exceptionHandler - the exception handler

Returns:

this pcap

setUncaughtExceptionHandler

public Pcap setUncaughtExceptionHandler(Thread.UncaughtExceptionHandler exceptionHandler)

Sets the uncaught exception handler for loop(int, org.jnetpcap.PcapDumper) and dispatch(int, org.jnetpcap.PcapDumper) methods. Any exception thrown within the user callback methods, will be caught and sent to the specified user exception handler.

Parameters:

exceptionHandler - the exception handler

Returns:

this pcap