tclPcap(n) 2.0.0 tclPcap "A Tcl interface to the pcap packet capture library"
tclPcap - Interface to the PCAP library
package require Tcl 8.0
package require Pcap 2.0.0
tclPcap is a set of Tcl commands that provide an interface to the pcap packet
capture library, available on a wide variety of platforms. This
extension does this by creating a new channel type called pcap. This allows
for very easy access to the library. All new commands added to the
interpreter are in the pcap:: namespace.
- pcap_open ?-offline? ?-nopromisc? ?-caplength length? ?-filter filter? fileName|deviceName
-
Creates a new channel that can be used to read captured packets. This command
returns the name of the new channel.
- -offline
-
The -offline flag indicates that data will not be captured from a
network device. Instead, a file name will be given that is the name of a
capture file to read. This capture file could have been created by tclpcap or
tcpdump (or any other program that uses libpcap).
- -nopromisc
-
The -nopromisc tells tclpcap not to open the capture device in
promiscuous mode. The option has no effect if -offline is given.
- -caplength length
-
The -caplength option specifies the number of bytes of each frame to
capture. The default value is 1500. If a negative number is given, the
default value will be used.
- -filter filter
-
The -filter specifies a filter string that is to be set for this
capture. The syntax of the filter is as documented in the tcpdump man page.
If no filter is specified, the string "default" is used, which will capture
all packets on the network. If the filter cannot be applied to the capture
device, pcap_open will throw an error.
- fileName|deviceName
-
The last argument is the name of the network device to capture from, unless
-offline has been given. In that case it is the name of a capture file
to read from. The special deviceName of "any" will cause all network
interfaces to be used for captures.
- lookupdev
-
This calls pcap_lookupdev and returns the name of a network device that
can be used with pcap_open. The loopback interface is ignored, and the
lowest numbered unit is the one returned (assuming multiple devices).
- lookupnet deviceName
-
This calls pcap_lookupnet with the supplied network deviceName. The command
returns a list containing the network address as the first element and the
netmask as the second element.
- getPacket pcapChannel
-
This command takes the name of a pcapChannel that was opened with
pcap_open as an argument. It reads the next available packet and returns
that in a list. The first element of the list is a header containing
the timestamp and length of the packet. The next element is the actual data
itself. The data is a binary string, so it is not useful to print it
out. See packetToString and printPacket.
It is possible for getPacket to be unable to read a packet. In this
case, an empty list will be returned. The caller should not interpret this to
mean that an end of file has been reached (if reading offline) or that the
network interface is down. The eof command should be used to detect
this. Am empty list could be returned even if the channel is in blocking
mode.
- packetToString packet
-
This command takes a packet, as returned from getPacket, as an
argument and returns the captured data as a string.
- printPacket packet
-
This command takes a packet, as returned from getPacket, as an argument and
prints the hex values to stdout.
- savefile pcapChannel ?on|off?
-
This turns on or off the dumping of the captured packets to a file. The
name of the capture file is configured through fconfigure with the
-savefile option. If neither on nor off are specified, then the current
state is returned.
- datalink pcapChannel
-
This calls pcap_datalink which returns the link layer type of the
pcapChannel. The return value is a list. The first element of the list is
a string representing the name of the datalink. This corresponds to what is
listed in the pcap man page. E.g., DLT_EN10MB. The second element of the
list is a longer version of the datalink that is more human readable. E.g.,
Ethernet.
- dump_open pcapChannel dumpFileName
-
- dump pcap_dumper packet
-
- dump_close pcap_dumper
-
- version
-
This calls pcap_lib_version which returns a string containing version
information of the pcap library.
The fconfigure command can be used to query and modify several
parameters of the channel created by pcap_open.
- -savefile fileName
-
The -savefile option specifies the name of a file that is to be used to
save dumped packets to. This option does not actually start dumping data to
the file. The savefile command needs to be called to start saving
captured packets.
Attempts to change the -savefile while packets are being dumped will result in
an error.
The value of -savefile defaults to an empty string.
- -filter filter
-
The -filter option allows the filter used by pcap to be changed. This
option corresponds to the -filter option of the pcap_open command.
By default, the filter captures all packets.
tcpdump, pcap(3), fconfigure(n)
Copyright (c) 2001-2005 by Todd J Martin <todd.martin@acm.org>