Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the plokami Reference Manual, version 1.5, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 05:49:26 2022 GMT+0.
• Introduction | What plokami is all about | |
• Systems | The systems documentation | |
• Files | The files documentation | |
• Packages | The packages documentation | |
• Definitions | The symbols documentation | |
• Indexes | Concepts, functions, variables and data types |
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: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The plokami system |
(:git "https://github.com/atomontage/plokami")
BSD
Common Lisp PCAP interface.
1.5
plokami.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files |
• The plokami.asd file | ||
• The plokami/packages.lisp file | ||
• The plokami/pcap.lisp file | ||
• The plokami/plokami.lisp file | ||
• The plokami/utils.lisp file |
Next: The plokami/packages․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
plokami.asd
plokami (system)
Next: The plokami/pcap․lisp file, Previous: The plokami․asd file, Up: Lisp files [Contents][Index]
Next: The plokami/plokami․lisp file, Previous: The plokami/packages․lisp file, Up: Lisp files [Contents][Index]
packages.lisp (file)
plokami (system)
pcap.lisp
*pcap-version* (special variable)
Next: The plokami/utils․lisp file, Previous: The plokami/pcap․lisp file, Up: Lisp files [Contents][Index]
pcap.lisp (file)
plokami (system)
plokami.lisp
Previous: The plokami/plokami․lisp file, Up: Lisp files [Contents][Index]
plokami.lisp (file)
plokami (system)
utils.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The plokami package |
packages.lisp (file)
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions | ||
• Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported special variables | ||
• Exported macros | ||
• Exported functions | ||
• Exported generic functions | ||
• Exported conditions |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Version of native libpcap library.
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [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.
plokami.lisp (file)
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.
plokami.lisp (file)
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.
plokami.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [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.
plokami.lisp (file)
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.
plokami.lisp (file)
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.
plokami.lisp (file)
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.
plokami.lisp (file)
Next: Exported conditions, Previous: Exported functions, Up: Exported definitions [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’.
plokami.lisp (file)
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.
plokami.lisp (file)
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.
plokami.lisp (file)
automatically generated reader method
plokami.lisp (file)
automatically generated reader method
plokami.lisp (file)
File descriptor that can be used with epoll/kqueue/select.
plokami.lisp (file)
Interface to capture packets from.
plokami.lisp (file)
True if capturing in promiscuous mode.
plokami.lisp (file)
automatically generated reader method
plokami.lisp (file)
Read timeout in milliseconds. 0 will wait forever.
Only works in blocking mode/platforms that support it. No guarantee of
returning within timeout.
plokami.lisp (file)
automatically generated reader method
plokami.lisp (file)
automatically generated reader method
plokami.lisp (file)
File (native namestring) to read packets from.
Represents a pathname using the native conventions of the operating system.
plokami.lisp (file)
Major version of savefile.
plokami.lisp (file)
Minor version of savefile.
plokami.lisp (file)
automatically generated reader method
plokami.lisp (file)
Savefile uses different byte order from host system.
plokami.lisp (file)
automatically generated reader method
plokami.lisp (file)
automatically generated reader method
plokami.lisp (file)
File (native namestring) to write packets to.
Represents a pathname using the native conventions of the operating system.
plokami.lisp (file)
automatically generated reader method
plokami.lisp (file)
plokami.lisp (file)
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.
plokami.lisp (file)
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.
plokami.lisp (file)
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.
plokami.lisp (file)
Deallocates resources for ‘PCAP-LIVE’, ‘PCAP-READER’, ‘PCAP-WRITER’ instance.
plokami.lisp (file)
progn (short method combination)
Options: :most-specific-first
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
Signaled on error when changing blocking mode.
plokami.lisp (file)
plokami-error (condition)
Signaled on all pcap readfile errors.
plokami.lisp (file)
plokami-error (condition)
Signaled on all pcap dumpfile errors.
plokami.lisp (file)
plokami-error (condition)
Signaled on all network interface errors.
plokami.lisp (file)
plokami-error (condition)
Signaled on error during live packet capture.
plokami.lisp (file)
plokami-error (condition)
Signaled when a berkeley packet filter could not be established.
plokami.lisp (file)
plokami-error (condition)
Signaled on errors during packet injection.
plokami.lisp (file)
plokami-error (condition)
Generic condition for this package.
plokami.lisp (file)
error (condition)
plokami-error-text (method)
:text
plokami-error-text (generic function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal constants | ||
• Internal special variables | ||
• Internal macros | ||
• Internal functions | ||
• Internal classes |
Next: Internal special variables, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
Next: Internal macros, Previous: Internal constants, Up: Internal definitions [Contents][Index]
plokami.lisp (file)
plokami.lisp (file)
plokami.lisp (file)
plokami.lisp (file)
Next: Internal functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
plokami.lisp (file)
Next: Internal classes, Previous: Internal macros, Up: Internal definitions [Contents][Index]
Set FOREIGN-BUFFER to the empty string.
plokami.lisp (file)
Return FOREIGN-BUFFER as a lisp string.
plokami.lisp (file)
Free memory held by FOREIGN-BUFFER.
plokami.lisp (file)
Allocate and return foreign char array to hold error string.
plokami.lisp (file)
Previous: Internal functions, Up: Internal definitions [Contents][Index]
Class for live packet capture.
plokami.lisp (file)
Interface to capture packets from.
:if
pcap-live-interface (generic function)
True if capturing in promiscuous mode.
:promisc
pcap-live-promisc-p (generic function)
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.
:timeout
100
pcap-live-timeout (generic function)
File descriptor that can be used with epoll/kqueue/select.
pcap-live-descriptor (generic function)
pcap-live-alive-p (generic function)
pcap-live-datalink (generic function)
:snaplen
pcap-live-snaplen (generic function)
Internal class used as a mixin for all classes with pcap functionality.
plokami.lisp (file)
standard-object (class)
stop (method)
Foreign pointer to pcap structure.
Datalink protocol for this device.
How many bytes to capture per packet received.
68
Packet capture object is live.
Internal class, mixed in packet processing (‘PCAP-LIVE’, ‘PCAP-READER’).
plokami.lisp (file)
standard-object (class)
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.
plokami.lisp (file)
File (native namestring) to read packets from.
Represents a pathname using the native conventions of the operating system.
:file
(error "must supply filename to read packets from.")
pcap-reader-file (generic function)
Savefile uses different byte order from host system.
pcap-reader-swapped-p (generic function)
Major version of savefile.
pcap-reader-major (generic function)
Minor version of savefile.
pcap-reader-minor (generic function)
pcap-reader-alive-p (generic function)
pcap-reader-datalink (generic function)
:snaplen
pcap-reader-snaplen (generic function)
Class for writing packets to a dumpfile.
plokami.lisp (file)
pcap-mixin (class)
File (native namestring) to write packets to.
Represents a pathname using the native conventions of the operating system.
:file
(error "must supply file to write packets to.")
pcap-writer-file (generic function)
Foreign packet dumper object.
:datalink
"en10mb"
pcap-writer-datalink (generic function)
pcap-writer-alive-p (generic function)
:snaplen
pcap-writer-snaplen (generic function)
Previous: Definitions, Up: Top [Contents][Index]
• Concept index | ||
• Function index | ||
• Variable index | ||
• Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | F L P |
---|
Jump to: | F L P |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [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 type index, Previous: Function index, 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 |
---|
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | B C N P S T |
---|
Jump to: | B C N P S T |
---|