Updated 2014-12-23 07:30:16 by dkf ▲

tclPcap 2.0.0 tclPcap A Tcl interface to the pcap packet capture library

Interface to the PCAP library

SYNOPSIS

package require Tcl 8.0

package require Pcap 2.0.0

  • pcap_open ?-offline? ?-nopromisc? ?-caplength length? ?-filter filter? fileName|deviceName
  • lookupdev
  • lookupnet deviceName
  • getPacket pcapChannel
  • packetToString packet
  • printPacket packet
  • savefile pcapChannel ?on|off?
  • datalink pcapChannel
  • dump_open pcapChannel dumpFileName
  • dump pcap_dumper packet
  • dump_close pcap_dumper
  • version

DESCRIPTION

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 to pcap_open 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 option to pcap_open 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 to pcap_open 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 option pcap_open 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 to pcap_open 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. An 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.

CONFIGURATION OPTIONS

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.

EXAMPLE

LIMITATIONS

SEE ALSO

tcpdump, pcap(3), fconfigure(n)

COPYRIGHT
 Copyright (c) 2001-2005 by Todd J Martin <todd.martin@acm.org>

Category Documentation