A trace is an object, either a live interface or a trace file, identified by a URI, of the form format:name, e.g. pacpfile:sample.bpf for a pcap file, int:eth0 for a live interface.
In a python-libtrace program you must create a Trace object using trace(), then 'start' the trace using trace.start(); after that you can read Packets from it using tfor packet in trace: or trace.read_packet().If you need to configure a live trace, you must specify its snap length, any input Filter it should use, and whether or not it should capture in promiscuous mode, using the Trace.conf_ methods. Furthermore, you must configure the trace before you start it.
| Class Methods | |
| trace() |
trace(uri) -> aNewTrace |
| Returns a
libtrace Trace object. The object's name is given by a
string containing its URI, e.g. pcapfile:xxx.bpf,
int:eth0, ... |
|
| conf_filter() | trace.conf_filter(filter) |
| Specifies that the Trace will filter its packets
using the BPF filter supplied as its argument. See the Filter page for details of how to create a filter object. Throws a plt_exc_libtrace exception if the conf fails. |
|
| conf_snaplen() | trace.conf_snaplen(integer) |
| Sets snaplen
for a live-interface Trace; at most the first snaplen bytes of each packet will be recorded for each
packet. Throws a plt_exc_libtrace exception if the conf fails. |
|
| conf_promisc() | trace.promisc(arg) |
| Specifices that a live-interface Trace should capture
all (if arg is
true) packets, oherwise it should
only capture packets intended for the Trace's interface. Throws a plt_exc_libtrace exception if the conf fails. |
|
| conf_timeout() | trace.promisc(integer) |
| Specifies the maximum time (in seconds)
libtrace should wait for an incoming packet from this Trace.
Intended for use with interfaces, e.g. with URIs that start with int: or bsd:. Throws a plt_exc_libtrace exception if the Trace times out; that will happen if no packets were seen, perhaps because its interface was not configured up when the trace was started. |
|
| start() | trace.start () |
| Starts the capture (from a live inteferace), or opens a trace file for reading. Throws a plt_exc_libtrace exception if the start fails. |
|
| pause() |
trace.pause() |
| Pauses the capture from a live interface. Throws a plt_exc_libtrace exception if the pause fails. Note: if you can pause() a trace, you may change its configuration, then start() it again. |
|
| close() | trace.close() |
| Shuts down a live interface, or closes a trace file. |
|
| read_packet() | trace.read_packet(aPacket) -> True or False |
| Gets a packet from Trace, and returns it in a Packet. Returns true if a packet was read, false at End-Of-File. Throws a plt_exc_libtrace exception if the read fails. |
|
| trace iterator |
for packet in trace: block |
| Reads Packets from trace, and passes them (in arrival order) to the indented block to be processed. Does not return anything after the last packet. Throws a plt_exc_libtrace exception if a read fails. |
|
| pkt_drops() | Trace.packet_drops -> anInteger |
| Returns the number of packets Trace captured, but that were dropped because of buffer overruns. | |
| pkt_accepts() | Trace.accepted_packets -> anInteger |
| Returns the number of packets Trace captured, and that were successfully read from it. | |