pcap
Note: This is taken from the Chicken Wiki, where a more recent version could be available.
Interface to the portable packet-capture library.
Category 5
You need to have the pcap library installed.
The pcap extension provides the ability to capture and process network packets live from an active interface or offline from a savefile. The core functionality is provided by libpcap, the portable C packet-capture library. You should be familiar with existing libpcap documentation (see tcpdump.org) as this extension follows the C API very closely.
<procedure>(pcap-lookupdev)</procedure>
Returns a string suitable for the DEVICE argument to pcap-open-live based on an available network interface (e.g. "eth0"), or #f if an error occurs.
<procedure>(pcap-lookupnet DEVICE)</procedure>
Returns two values: the 32-bit network address and mask associated with DEVICE, a string specifying the network interface.
<procedure>(pcap-open-live DEVICE SNAPLEN PROMISC? TIMEOUT ERRBUF)</procedure>
Opens an active network interface for packet capturing. DEVICE is a string that should name a network interface (e.g. "eth0"). SNAPLEN is the maximum number of bytes of each packet to capture. PROMISC? is a boolean that specifies whether the interface should be set to promiscuous mode. TIMEOUT is the read timeout in milliseconds. ERRBUF is #f or a non-immediate string to which a diagnostic message will be written if an error occurs.
Returns a pcap object on success or #f if an error occurs.
<procedure>(pcap-open-offline FILENAME)</procedure>
Opens a savefile as a packet source rather than a live interface, such as one created with the pcap-dump procedures.
Returns a pcap object on success or #f if an error occurs.
<procedure>(pcap-dump-open PCAP FILENAME)</procedure>
Opens a savefile for writing packet data. PCAP should be a pcap object returned by one of the pcap-open procedures. FILENAME is a string specifying the name of the savefile.
Returns a pcap dumper object or #f if an error occurs.
<procedure>(pcap-close PCAP)</procedure>
Closes open files and deallocates resources associated with the active pcap object PCAP. The return value is unspecified.
<procedure>(pcap-dump-close PCAP-DUMP)</procedure>
Closes the savefile associated with the pcap dumper object PCAP-DUMP returned from an earlier call to pcap-dump-open. The return value is unspecified.
<procedure>(pcap-next PCAP)</procedure>
Returns three values: the next packet available for reading from the device associated with the pcap object PCAP (a string), and the second and microsecond components of the timestamp indicating when the packet was received.
<procedure>(pcap-dispatch PCAP N CALLBACK-PROC)</procedure> <procedure>(pcap-loop PCAP N CALLBACK-PROC)</procedure>
Repeatedly calls the procedure CALLBACK-PROC for every packet received with four arguments: the packet data (a string), the packet length in bytes, and the second and microsecond components of the timestamp indicating when the packet was received. The integer N specifies how many packets to process; if it is 0, packets will be processed until an error occurs (or EOF is reached).
Returns the number of packets processed. A return value of 0 indicates that EOF was reached while reading a savefile. A return value of -1 indicates that an error occurred.
Regarding the difference between these two procedures, the libpcap documentation states (rather unclearly):
pcap_loop() is similar to pcap_dispatch() except it keeps reading packets until cnt packets are processed or an error occurs. A negative cnt causes pcap_loop() to loop forever (or at least until an error occurs).
<procedure>(pcap-dispatch/dump PCAP N)</procedure> <procedure>(pcap-loop/dump PCAP N)</procedure>
These procedures execute a pcap-dispatch or pcap-loop and save each packet received to the savefile opened earlier with pcap-dump-open.
<procedure>(pcap-stats PCAP)</procedure>
Returns two values: the number of packets received (and possibly filtered), and the number of packets dropped.
<procedure>(pcap-compile PCAP FILTERSPEC NETMASK)</procedure>
Compiles the BPF filter specification in the string FILTERSPEC to an internal representation suitable for use with pcap-setfilter. See the tcpdump documentation for details on the format of FILTERSPEC. The NETMASK argument is the 32-bit netmask of the network interface as returned, for example, by pcap-lookupnet.
Returns a BPF object or #f if an error occurs.
<procedure>(pcap-setfilter PCAP BPF)</procedure>
Sets the packet filter associated with the pcap object PCAP to the one specified by the BPF object BPF.
Returns 0 on success or -1 if an error occurs.
<procedure>(pcap-datalink PCAP)</procedure>
Returns an integer indicating the datalink type associated with the pcap object PCAP. See <net/dlt.h> for a list of types.
<procedure>(pcap-snapshot PCAP)</procedure>
Returns the snapshot length associated with the pcap object PCAP as specified when pcap-open-live was called.
<procedure>(pcap-swapped? PCAP)</procedure>
Returns #t if the current savefile uses a byte order that differs from that of the host system, and #f otherwise.
<procedure>(pcap-major-version PCAP)</procedure> <procedure>(pcap-minor-version PCAP)</procedure>
These procedures return the major and minor version numbers of the pcap used to write the savefile.
<procedure>(pcap-geterr PCAP)</procedure>
Returns a string providing diagnostic information about the last error returned from an operation on the active pcap object PCAP.
WARNING: These procedures are closely tied to their C counterparts and do not generally check their arguments for validity. Passing, e.g., a PCAP object that has been closed to procedures such as pcap-next and pcap-loop may result in corrupted data or your program dumping core.
<example> <init>(require 'pcap)</init> <expr> (let* ((dev (pcap-lookupdev))
(p (pcap-open-live dev 1024 0 -1 #f)))
(pcap-setfilter p
(pcap-compile p "src host 192.168.100.1"
(nth-value 1 (pcap-lookupnet dev))))
(pcap-loop p 10
(lambda (d l s u)
(print s ":" u " - " l " bytes")))
(receive (recv drop) (pcap-stats p)
(print recv " packets received, " drop " packets dropped."))
(pcap-close p))</expr> </example>
Now we initiate a ping to 192.168.100.1. The output is:
1080736263:129802 - 102 bytes 1080736264:132519 - 102 bytes 1080736265:142925 - 102 bytes 1080736266:330037 - 102 bytes 1080736267:133752 - 102 bytes 1080736268:144147 - 102 bytes 1080736269:144555 - 102 bytes 1080736270:144944 - 102 bytes 1080736271:145400 - 102 bytes 1080736272:332302 - 102 bytes 288 packets received, 0 packets dropped.
Copyright (c) 2004, Category 5 All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.