Struct Capture

pub struct Capture<T: State + ?Sized> { /* private fields */ }

This is a pcap capture handle which is an abstraction over the pcap_t provided by pcap. There are many ways to instantiate and interact with a pcap handle, so phantom types are used to express these behaviors.

Capture<Inactive> is created via Capture::from_device(). This handle is inactive, so you cannot (yet) obtain packets from it. However, you can configure things like the buffer size, snaplen, timeout, and promiscuity before you activate it.

Capture<Active> is created by calling .open() on a Capture<Inactive>. This activates the capture handle, allowing you to get packets with .next() or apply filters with .filter().

Capture<Offline> is created via Capture::from_file(). This allows you to read a pcap format dump file as if you were opening an interface – very useful for testing or analysis.

Capture<Dead> is created via Capture::dead(). This allows you to create a pcap format dump file without needing an active capture.

Example:

let cap = Capture::from_device(Device::lookup().unwrap()) // open the "default" interface
              .unwrap() // assume the device exists and we are authorized to open it
              .open() // activate the handle
              .unwrap(); // assume activation worked

while let Ok(packet) = cap.next() {
    println!("received packet! {:?}", packet);
}

Implementations

impl Capture<Offline>

pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Capture<Offline>, Error>

Opens an offline capture handle from a pcap dump file, given a path.

Examples found in repository

examples/savefile.rs (line 24)

fn main() {
	{
		// open capture from default device
		let mut cap = Capture::from_device(Device::lookup().unwrap()).unwrap().open().unwrap();

		// open savefile using the capture
		let mut savefile = cap.savefile("test.pcap").unwrap();

		// get a packet from the interface
		let p = cap.next().unwrap();

		// print the packet out
		println!("packet received on network: {:?}", p);

		// write the packet to the savefile
		savefile.write(&p);
	}

	// open a new capture from the test.pcap file we wrote to above
	let mut cap = Capture::from_file("test.pcap").unwrap();

	// get a packet
	let p = cap.next().unwrap();

	// print that packet out -- it should be the same as the one we printed above
	println!("packet obtained from file: {:?}", p);
}

pub fn from_file_with_precision<P: AsRef<Path>>( path: P, precision: Precision, ) -> Result<Capture<Offline>, Error>

Opens an offline capture handle from a pcap dump file, given a path. Takes an additional precision argument specifying the time stamp precision desired.

impl Capture<Inactive>

pub fn from_device<D: Into<Device>>( device: D, ) -> Result<Capture<Inactive>, Error>

Opens a capture handle for a device. You can pass a Device or an &str device name here. The handle is inactive, but can be activated via .open().

Examples found in repository

examples/listenlocalhost.rs (line 6)

fn main() {
    // listen on the device named "any", which is only available on Linux. This is only for
    // demonstration purposes.
    let mut cap = pcap::Capture::from_device("any").unwrap().open().unwrap();

    // filter out all packets that don't have 127.0.0.1 as a source or destination.
    cap.filter("host 127.0.0.1").unwrap();

    while let Ok(packet) = cap.next() {
    	println!("got packet! {:?}", packet);
    }
}

examples/savefile.rs (line 8)

fn main() {
	{
		// open capture from default device
		let mut cap = Capture::from_device(Device::lookup().unwrap()).unwrap().open().unwrap();

		// open savefile using the capture
		let mut savefile = cap.savefile("test.pcap").unwrap();

		// get a packet from the interface
		let p = cap.next().unwrap();

		// print the packet out
		println!("packet received on network: {:?}", p);

		// write the packet to the savefile
		savefile.write(&p);
	}

	// open a new capture from the test.pcap file we wrote to above
	let mut cap = Capture::from_file("test.pcap").unwrap();

	// get a packet
	let p = cap.next().unwrap();

	// print that packet out -- it should be the same as the one we printed above
	println!("packet obtained from file: {:?}", p);
}

pub fn open(self) -> Result<Capture<Active>, Error>

Activates an inactive capture created from Capture::from_device() or returns an error.

Examples found in repository

examples/listenlocalhost.rs (line 6)

fn main() {
    // listen on the device named "any", which is only available on Linux. This is only for
    // demonstration purposes.
    let mut cap = pcap::Capture::from_device("any").unwrap().open().unwrap();

    // filter out all packets that don't have 127.0.0.1 as a source or destination.
    cap.filter("host 127.0.0.1").unwrap();

    while let Ok(packet) = cap.next() {
    	println!("got packet! {:?}", packet);
    }
}

examples/savefile.rs (line 8)

fn main() {
	{
		// open capture from default device
		let mut cap = Capture::from_device(Device::lookup().unwrap()).unwrap().open().unwrap();

		// open savefile using the capture
		let mut savefile = cap.savefile("test.pcap").unwrap();

		// get a packet from the interface
		let p = cap.next().unwrap();

		// print the packet out
		println!("packet received on network: {:?}", p);

		// write the packet to the savefile
		savefile.write(&p);
	}

	// open a new capture from the test.pcap file we wrote to above
	let mut cap = Capture::from_file("test.pcap").unwrap();

	// get a packet
	let p = cap.next().unwrap();

	// print that packet out -- it should be the same as the one we printed above
	println!("packet obtained from file: {:?}", p);
}

pub fn timeout(self, ms: i32) -> Capture<Inactive>

Set the read timeout for the Capture. By default, this is 0, so it will block indefinitely.

pub fn tstamp_type(self, t: TstampType) -> Capture<Inactive>

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

pub fn promisc(self, to: bool) -> Capture<Inactive>

Set promiscuous mode on or off. By default, this is off.

pub fn rfmon(self, to: bool) -> Capture<Inactive>

Set rfmon mode on or off. The default is maintained by pcap.

This is not available on Windows.

pub fn buffer_size(self, to: i32) -> Capture<Inactive>

Set the buffer size for incoming packet data.

The default is 1000000. This should always be larger than the snaplen.

pub fn precision(self, precision: Precision) -> Capture<Inactive>

Set the time stamp precision returned in captures.

pub fn snaplen(self, to: i32) -> Capture<Inactive>

Set the snaplen size (the maximum length of a packet captured into the buffer). Useful if you only want certain headers, but not the entire packet.

The default is 65535

impl<T: Activated + ?Sized> Capture<T>

Activated captures include Capture<Active> and Capture<Offline>.

pub fn list_datalinks(&self) -> Result<Vec<Linktype>, Error>

List the datalink types that this captured device supports.

pub fn set_datalink(&mut self, linktype: Linktype) -> Result<(), Error>

Set the datalink type for the current capture handle.

pub fn get_datalink(&self) -> Linktype

Get the current datalink type for this capture handle.

pub fn savefile<P: AsRef<Path>>(&self, path: P) -> Result<Savefile, Error>

Create a Savefile context for recording captured packets using this Capture’s configurations.

Examples found in repository

examples/savefile.rs (line 11)

fn main() {
	{
		// open capture from default device
		let mut cap = Capture::from_device(Device::lookup().unwrap()).unwrap().open().unwrap();

		// open savefile using the capture
		let mut savefile = cap.savefile("test.pcap").unwrap();

		// get a packet from the interface
		let p = cap.next().unwrap();

		// print the packet out
		println!("packet received on network: {:?}", p);

		// write the packet to the savefile
		savefile.write(&p);
	}

	// open a new capture from the test.pcap file we wrote to above
	let mut cap = Capture::from_file("test.pcap").unwrap();

	// get a packet
	let p = cap.next().unwrap();

	// print that packet out -- it should be the same as the one we printed above
	println!("packet obtained from file: {:?}", p);
}

pub fn direction(&self, direction: Direction) -> Result<(), Error>

Set the direction of the capture

pub fn next<'a>(&'a mut self) -> Result<Packet<'a>, Error>

Blocks until a packet is returned from the capture handle or an error occurs.

pcap captures packets and places them into a buffer which this function reads from. This buffer has a finite length, so if the buffer fills completely new packets will be discarded temporarily. This means that in realtime situations, you probably want to minimize the time between calls of this next() method.

Examples found in repository

examples/easylisten.rs (line 8)

fn main() {
    // get the default Device
    let mut cap = pcap::Device::lookup().unwrap().open().unwrap();

    // get a packet and print its bytes
    println!("{:?}", cap.next());
}

examples/getstatistics.rs (line 9)

fn main() {
    // get the default Device
    let mut cap = pcap::Device::lookup().unwrap().open().unwrap();

    // get 10 packets
    for _ in 0..10 {
      cap.next().ok();
    }
    let stats = cap.stats().unwrap();
    println!("Received: {}, dropped: {}, if_dropped: {}", stats.received, stats.dropped, stats.if_dropped);
}

examples/getdevices.rs (line 12)

fn main() {
    // list all of the devices pcap tells us are available
    for device in pcap::Device::list().unwrap() {
        println!("Found device! {:?}", device);

        // now you can create a Capture with this Device if you want.
        let mut cap = device.open().unwrap();

        // get a packet from this capture
        let packet = cap.next();

        println!("got a packet! {:?}", packet);
    }
}

examples/listenlocalhost.rs (line 11)

fn main() {
    // listen on the device named "any", which is only available on Linux. This is only for
    // demonstration purposes.
    let mut cap = pcap::Capture::from_device("any").unwrap().open().unwrap();

    // filter out all packets that don't have 127.0.0.1 as a source or destination.
    cap.filter("host 127.0.0.1").unwrap();

    while let Ok(packet) = cap.next() {
    	println!("got packet! {:?}", packet);
    }
}

examples/savefile.rs (line 14)

fn main() {
	{
		// open capture from default device
		let mut cap = Capture::from_device(Device::lookup().unwrap()).unwrap().open().unwrap();

		// open savefile using the capture
		let mut savefile = cap.savefile("test.pcap").unwrap();

		// get a packet from the interface
		let p = cap.next().unwrap();

		// print the packet out
		println!("packet received on network: {:?}", p);

		// write the packet to the savefile
		savefile.write(&p);
	}

	// open a new capture from the test.pcap file we wrote to above
	let mut cap = Capture::from_file("test.pcap").unwrap();

	// get a packet
	let p = cap.next().unwrap();

	// print that packet out -- it should be the same as the one we printed above
	println!("packet obtained from file: {:?}", p);
}

pub fn filter(&mut self, program: &str) -> Result<(), Error>

Adds a filter to the capture using the given BPF program string. Internally this is compiled using pcap_compile().

See http://biot.com/capstats/bpf.html for more information about this syntax.

Examples found in repository

examples/listenlocalhost.rs (line 9)

fn main() {
    // listen on the device named "any", which is only available on Linux. This is only for
    // demonstration purposes.
    let mut cap = pcap::Capture::from_device("any").unwrap().open().unwrap();

    // filter out all packets that don't have 127.0.0.1 as a source or destination.
    cap.filter("host 127.0.0.1").unwrap();

    while let Ok(packet) = cap.next() {
    	println!("got packet! {:?}", packet);
    }
}

pub fn stats(&mut self) -> Result<Stat, Error>

Examples found in repository

examples/getstatistics.rs (line 11)

fn main() {
    // get the default Device
    let mut cap = pcap::Device::lookup().unwrap().open().unwrap();

    // get 10 packets
    for _ in 0..10 {
      cap.next().ok();
    }
    let stats = cap.stats().unwrap();
    println!("Received: {}, dropped: {}, if_dropped: {}", stats.received, stats.dropped, stats.if_dropped);
}

impl Capture<Active>

pub fn sendpacket<'a>(&mut self, buf: &'a [u8]) -> Result<(), Error>

Sends a packet over this capture handle’s interface.

impl Capture<Dead>

pub fn dead(linktype: Linktype) -> Result<Capture<Dead>, Error>

Creates a “fake” capture handle for the given link type.

Trait Implementations

impl AsRawFd for Capture<Active>

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl<T: State + ?Sized> Drop for Capture<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: Activated> From<Capture<T>> for Capture<dyn Activated>

fn from(cap: Capture<T>) -> Capture<dyn Activated>

Converts to this type from the input type.