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 ruby-libtrace program you must create a Trace object using Trace.new, then 'start' the trace using Trace.start; after that you can read Packets from it using Trace.each_packet 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 | |
| new | Trace.new(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, ... Throws a LibtraceError exception a new Trace couldn't be created, e.g. because an invalid URI was specified. |
|
| 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 LibtraceError 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 LibtraceError 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 LibtraceError exception if the conf fails. |
|
| start | Trace.start |
| Starts the capture (from a live inteferace), or opens a trace file for reading. Throws a LibtraceError exception if the start fails. |
|
| pause |
Trace.pause |
| Pauses the capture from a live interface. Throws a LibtraceError 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. Throws a LibtraceError exception if the close fails. |
|
| 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 LibtraceError exception if the read fails. |
|
| each_packet | Trace. each_packet { |pkt| block } |
| Reads Packets from Trace, and passes them (in arrival order) to block to be processed. Does not return anything after the last packet. Throws a LibtraceError exception if a read fails. |
|
| err? | Trace.err? -> true or false |
| Returns true if a libtrace error has occured for Trace. See Error page for more information on libtrace errors. | |
| get_err | Trace.get_err -> anError |
| Returns a ruby-libtrace Error object, describing Trace's error status. Resets Trace's error status to TRACE_NO_ERROR. | |
| packet_drops | Trace.packet_drops -> anInteger |
| Returns the number of packets Trace captured, but that were dropped because of buffer overruns. | |