## Trace Management

### What is a libtrace 'trace?'

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 Trace

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.

Nevil Brownlee
Mon, 19 Feb 2018 (NZDT)