Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the plokami Reference Manual, version 1.5, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 05:52:41 2022 GMT+0.
Next: Systems, Previous: The plokami Reference Manual, Up: The plokami Reference Manual [Contents][Index]
PLOKAMI is a lispy interface to libpcap built on top of a CFFI portability layer. Complete bindings to every function in libpcap are in pcap.lisp and a higher level interface in plokami.lisp. * Features - Realtime network packet capture - Injection - PCAP dumpfile read/write - BPF - Timeouts and operation in non-blocking mode - Full support for Windows through WinPCAP The library has been tested on SBCL (linux/darwin), ClozureCL and LispWorks (darwin/win32) but should work on every platform that CFFI supports. * Performance Minimal overhead over plain libpcap. * License The code comes with a BSD-style license so you can basically do with it whatever you want. * Documentation [[https://atomontage.github.io/plokami]] * Author xristos (AT) sdf (DOT) org
Next: Files, Previous: Introduction, Up: The plokami Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
Common Lisp PCAP interface.
(GIT https://github.com/atomontage/plokami)
BSD
1.5
Next: Packages, Previous: Systems, Up: The plokami Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: plokami/packages.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
plokami (system).
Next: plokami/pcap.lisp, Previous: plokami/plokami.asd, Up: Lisp [Contents][Index]
plokami (system).
Next: plokami/plokami.lisp, Previous: plokami/packages.lisp, Up: Lisp [Contents][Index]
packages.lisp (file).
plokami (system).
*pcap-version* (special variable).
Next: plokami/utils.lisp, Previous: plokami/pcap.lisp, Up: Lisp [Contents][Index]
pcap.lisp (file).
plokami (system).
Previous: plokami/plokami.lisp, Up: Lisp [Contents][Index]
plokami.lisp (file).
plokami (system).
Next: Definitions, Previous: Files, Up: The plokami Reference Manual [Contents][Index]
Packages are listed by definition order.
Next: Indexes, Previous: Packages, Up: The plokami Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Macros, Previous: Public Interface, Up: Public Interface [Contents][Index]
Version of native libpcap library.
Next: Ordinary functions, Previous: Special variables, Up: Public Interface [Contents][Index]
Call ‘MAKE-PCAP-LIVE’ using IFACE, OPTIONS as arguments and store
the resulting instance in LIVE. Forms in body are wrapped in an
‘UNWIND-PROTECT’ form that takes care of deallocating resources on
error and also returns packet capture statistics when possible. A restart
is also automatically invoked when ‘PACKET-FILTER-ERROR’ is signaled,
skipping the filter setup.
Call ‘MAKE-PCAP-READER’ using FILE, OPTIONS as arguments and store the
resulting instance in READER. Forms in body are wrapped in an UNWIND-PROTECT
form that takes care of deallocating resources on error. A restart is also
automatically invoked when ‘PACKET-FILTER-ERROR’ is signaled,
skipping the filter setup.
Call ‘MAKE-PCAP-WRITER’ using FILE, OPTIONS as arguments and store the resulting instance in WRITER. Forms in body are wrapped in an ‘UNWIND-PROTECT’ form that takes care of deallocating resources on error.
Next: Generic functions, Previous: Macros, Up: Public Interface [Contents][Index]
Return a list of all network devices that can be opened for capture.
Result list mirrors layout explained in pcap_findalldevs(3).
NIL is returned when no interfaces are available, possibly due to permission
issues.
Signals ‘NETWORK-INTERFACE-ERROR’ on errors.
Creates and returns a ‘PCAP-LIVE’ instance that is used for live packet
capture from a network interface.
INTERFACE is a string that defines the network interface to use for capture.
PROMISC should be T for promiscuous mode, NIL otherwise.
NBIO should be T when non-blocking operation is required. NIL otherwise
(default).
TIMEOUT should hold read timeout in milliseconds. 0 will wait forever.
Only used when in blocking mode and only in platforms
that support it. No guarantee of actually returning within TIMEOUT is made.
Use non-blocking mode if that is not adequate.
SNAPLEN should contain the number of bytes captured per packet. Default is 68
which should be enough for headers.
‘NETWORK-INTERFACE-ERROR’ or ‘BLOCK-MODE-ERROR’ is signaled on errors.
Creates and returns a ‘PCAP-READER’ instance that is used for reading
packets from a pcap dumpfile.
FILE is the filename (namestring or pathname) to open and read packets from.
SNAPLEN should contain the number of bytes read per packet captured.
Default is 68 which should be enough for headers.
‘CAPTURE-FILE-READ-ERROR’ is signaled on errors.
Creates and returns a ‘PCAP-WRITER’ instance that is used to write packets
to a pcap dumpfile.
FILE is the filename (namestring or pathname) to open and write packets to.
DATALINK should contain a string that represents the datalink protocol of the
network interface used to capture the packets. Default is Ethernet.
SNAPLEN should contain the number of bytes read per packet captured and should
be the same as the one used when capturing/reading the packets.
‘CAPTURE-FILE-WRITE-ERROR’ is signaled on errors.
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
Only works for ‘PCAP-LIVE’ or ‘PCAP-READER’ instances.
Captures and processes maximum number of PACKETS. Minimum is
zero. Return 0 when no packets available (did not pass installed packet filter,
end of file for dumpfiles, read timeout expired before packets arrive,
no packets available at the time of the call if in non-blocking-mode) otherwise
return number of packets processed which can be fewer than the maximum given
in PACKETS (due to internal libpcap buffer).
A count of -1 in PACKETS processes all the packets received so far when live
capturing, or all the packets in a file when reading a pcap dumpfile.
Handler must be a user defined function that accepts five arguments and will
get called once for every packet received. The values passed are SEC, USEC,
CAPLEN, LEN and BUFFER.
SEC and USEC correspond to seconds/microseconds since the UNIX epoch
(timeval structure in C) at the time of capture.
CAPLEN corresponds to the number of bytes captured.
LEN corresponds to the number of bytes originally present in the packet but
not necessarily captured.
BUFFER is a statically allocated byte vector (via ‘CFFI:MAKE-SHAREABLE-BYTE-VECTOR’)
with the contents of the captured packet. This means that successive calls of the
packet handler will overwrite its contents and if packet persistence is required,
contents of BUFFER should be copied somewhere else from within HANDLER.
If an error occurs, ‘PACKET-CAPTURE-ERROR’ is signaled for live
interfaces and ‘CAPTURE-FILE-READ-ERROR’ for pcap dumpfiles (reading).
For more details on callback handling, see CFFI callback ‘PCAP-HANDLER’.
Writes contents of byte vector DATA to ‘PCAP-WRITER’
instance (which corresponds to a pcap dumpfile).
LENGTH is the number of bytes to write and is set to the size of DATA
when omitted.
ORIGLENGTH should be set to the number of bytes originally present in
the packet and is set to LENGTH when omitted.
SEC and USEC should be set to seconds/microseconds since the UNIX epoch
at the time of capture (timeval structure in C).
If you are using your own source buffer (instead of the one used by PLOKAMI), it should be allocated with ‘CFFI:MAKE-SHAREABLE-BYTE-VECTOR’. As LIBPCAP does not return a useful value on pcap_dump(), no PLOKAMI specific conditions, beyond simple assertions of argument checks, are raised by this function.
Injects LENGTH bytes to a live pcap interface
(size of BUFFER if omitted). Return number of bytes injected on success.
For performance reasons BUFFER should be a byte vector allocated with
‘CFFI:MAKE-SHAREABLE-BYTE-VECTOR’. ‘PACKET-INJECT-ERROR’ is signaled on failure.
automatically generated reader method
live.
automatically generated reader method
File (native namestring) to read packets from.
Represents a pathname using the native conventions of the operating system.
file.
Major version of savefile.
Minor version of savefile.
automatically generated reader method
Savefile uses different byte order from host system.
automatically generated reader method
live.
automatically generated reader method
File (native namestring) to write packets to.
Represents a pathname using the native conventions of the operating system.
file.
automatically generated reader method
text.
Sets a packet filter on a ‘PCAP-LIVE’ or ‘PCAP-READER’
instance. The filter should be given as a bpf expression in STRING.
‘PACKET-FILTER-ERROR’ is signaled on failure. A restart, ‘CONTINUE-NO-FILTER’
is installed that can be invoked to continue on error.
Sets non-blocking mode if BLOCK-MODE is T, blocking
mode if NIL. ‘BLOCK-MODE-ERROR’ is signaled on failure and a restart,
‘CONTINUE-BLOCK-MODE’ is installed, that can be invoked to continue.
Returns packet capture statistics from the start of the run
to the time of the call for live interface capture only. Statistics are
returned as multiple values and correspond to packets received,
packets dropped and packets dropped by interface (in this order).
‘NETWORK-INTERFACE-ERROR’ is signaled on failure.
Deallocates resources for ‘PCAP-LIVE’, ‘PCAP-READER’, ‘PCAP-WRITER’ instance.
progn.
:most-specific-first
Next: Conditions, Previous: Generic functions, Up: Public Interface [Contents][Index]
Previous: Standalone methods, Up: Public Interface [Contents][Index]
Signaled on error when changing blocking mode.
Signaled on all pcap readfile errors.
Signaled on all pcap dumpfile errors.
Signaled on all network interface errors.
Signaled on error during live packet capture.
Signaled when a berkeley packet filter could not be established.
Signaled on errors during packet injection.
Generic condition for this package.
error.
:text
This slot is read-only.
Previous: Public Interface, Up: Definitions [Contents][Index]
Next: Ordinary functions, Previous: Special variables, Up: Internals [Contents][Index]
Set FOREIGN-BUFFER to the empty string.
Return FOREIGN-BUFFER as a lisp string.
Free memory held by FOREIGN-BUFFER.
Allocate and return foreign char array to hold error string.
Previous: Ordinary functions, Up: Internals [Contents][Index]
Class for live packet capture.
Interface to capture packets from.
:if
This slot is read-only.
True if capturing in promiscuous mode.
:promisc
This slot is read-only.
True if pcap descriptor is in non-blocking mode.
:nbio
Read timeout in milliseconds. 0 will wait forever.
Only works in blocking mode/platforms that support it. No guarantee of
returning within timeout.
100
:timeout
This slot is read-only.
File descriptor that can be used with epoll/kqueue/select.
This slot is read-only.
This slot is read-only.
This slot is read-only.
:snaplen
This slot is read-only.
Internal class used as a mixin for all classes with pcap functionality.
Internal class, mixed in packet processing (‘PCAP-LIVE’, ‘PCAP-READER’).
Packet buffer to hold captured packets.
Lisp packet handler for capture. Invoked by callback.
Hashtable key for this instance.
Foreign pointer to hashkey, passed in callback.
Class for reading packets from a dumpfile.
File (native namestring) to read packets from.
Represents a pathname using the native conventions of the operating system.
(error "must supply filename to read packets from.")
:file
This slot is read-only.
Savefile uses different byte order from host system.
This slot is read-only.
Major version of savefile.
This slot is read-only.
Minor version of savefile.
This slot is read-only.
This slot is read-only.
This slot is read-only.
:snaplen
This slot is read-only.
Class for writing packets to a dumpfile.
File (native namestring) to write packets to.
Represents a pathname using the native conventions of the operating system.
(error "must supply file to write packets to.")
:file
This slot is read-only.
Foreign packet dumper object.
"en10mb"
:datalink
This slot is read-only.
This slot is read-only.
:snaplen
This slot is read-only.
Previous: Definitions, Up: The plokami Reference Manual [Contents][Index]
| Jump to: | %
C D E F G I M P S W |
|---|
| Jump to: | %
C D E F G I M P S W |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | *
+
B C D F H I L M N P S T |
|---|
| Jump to: | *
+
B C D F H I L M N P S T |
|---|
| Jump to: | B C F N P S T U |
|---|
| Jump to: | B C F N P S T U |
|---|