libnd_tpm 3 LIBNETDUDE Library libnd_tpm enum LND_TPM_NavMode; LND_TPM* libnd_tpm_new (LND_Trace *trace); void libnd_tpm_free (LND_TPM *tpm); gboolean libnd_tpm_read_packet (LND_TPM *tpm, LND_Packet *packet); void libnd_tpm_load_packets (LND_TPM *tpm); void libnd_tpm_load_prev_part (LND_TPM *tpm); void libnd_tpm_load_next_part (LND_TPM *tpm); void libnd_tpm_set_output_file (LND_TPM *tpm, const char *filename); guint libnd_tpm_num_memory_packets (); void libnd_tpm_clear_current_part (LND_TPM *tpm, gboolean emit_signal); void libnd_tpm_add_part (LND_TPM *tpm, LND_TracePart *tp); gboolean libnd_tpm_remove_part (LND_TPM *tpm, LND_TracePart *tp); pcapnav_result_t libnd_tpm_goto_ts (LND_TPM *tpm, struct bpf_timeval *timestamp); pcapnav_result_t libnd_tpm_goto_fraction (LND_TPM *tpm, double fraction); gboolean libnd_tpm_goto_loc (LND_TPM *tpm, LND_TraceLoc *loc); gboolean libnd_tpm_is_tp_overlap (const LND_TPM *tpm, const LND_TracePart *tp1, const LND_TracePart *tp2); off_t libnd_tpm_map_loc_to_offset (const LND_TPM *tpm, const LND_TraceLoc *loc); pcapnav_result_t libnd_tpm_map_offset_to_loc (const LND_TPM *tpm, off_t offset, LND_TraceLoc *loc); gboolean libnd_tpm_map_loc_to_timestamp (LND_TPM *tpm, LND_TraceLoc *loc, struct bpf_timeval *tv); pcapnav_result_t libnd_tpm_map_fraction_to_loc (const LND_TPM *tpm, double fraction, LND_TraceLoc *loc); pcapnav_result_t libnd_tpm_map_timestamp_to_loc (const LND_TPM *tpm, struct bpf_timeval *timestamp, LND_TraceLoc *loc); off_t libnd_tpm_get_offset (const LND_TPM *tpm); gboolean libnd_tpm_find_locs (const LND_TPM *tpm, LND_TraceArea *area, LND_TraceLoc *start, LND_TraceLoc *end); double libnd_tpm_get_space_fraction (const LND_TPM *tpm, off_t offset); double libnd_tpm_get_time_fraction (const LND_TPM *tpm, const struct bpf_timeval *tv); double libnd_tpm_get_rel_size (const LND_TPM *tpm); LND_Packet* libnd_tpm_get_packets (LND_TPM *tpm); LND_Packet* libnd_tpm_get_sel (LND_TPM *tpm); void libnd_tpm_pcap_read_handler (u_char *data, const struct pcap_pkthdr *h, const u_char *pdata); void libnd_tpm_dump_parts (LND_TPM *tpm); LND_TPM_NavModetypedef enum { LND_TPM_SPACE, LND_TPM_TIME, LND_TPM_ERROR } LND_TPM_NavMode; libnd_tpm_newLND_TPM* libnd_tpm_new (LND_Trace *trace); The function allocates a new trace part manager, sets up basic stuff and returns it. It does not load any packets yet. trace : trace to manage. Returns : new manager. libnd_tpm_freevoid libnd_tpm_free (LND_TPM *tpm); The function shuts down tpm properly and releases any memory occupied. It also takes care of freeing all related trace parts, removing temporary files etc. tpm : trace part manager to free. libnd_tpm_read_packetgboolean libnd_tpm_read_packet (LND_TPM *tpm, LND_Packet *packet); The function tries to read a single packet from the current location in the trace. The resulting packet data is read into packet. NOTE: Upon return, packet is not initialized, and its raw packet data points to volatile storage. If you want to keep the packet around after further calls to this function, you need to libnd_packet_duplicate() the packet! tpm : trace part manager. packet : result pointer. Returns : TRUE if successful, FALSE otherwise. libnd_tpm_load_packetsvoid libnd_tpm_load_packets (LND_TPM *tpm); This function loads as many packets into memory as configured by the user, and fires an LND_TRACE_RELOAD event after the packets have been loaded. tpm : trace part manager. libnd_tpm_load_prev_partvoid libnd_tpm_load_prev_part (LND_TPM *tpm); The function is function loads as many packets into memory as the user has configured, so that the last packet is located before the first one of the current trace part. After the packets are loaded, an LND_TRACE_RELOAD event is fired. tpm : trace part manager. libnd_tpm_load_next_partvoid libnd_tpm_load_next_part (LND_TPM *tpm); tpm : libnd_tpm_set_output_filevoid libnd_tpm_set_output_file (LND_TPM *tpm, const char *filename); The function sets filename as the new base file name to write to. Handle with care, you shouldn't really need this function. It's used e.g. when a trace is saved to cause the packets to be written to the original filename. tpm : trace part manager. filename : new base file name. libnd_tpm_num_memory_packetsguint libnd_tpm_num_memory_packets (); This is a helper function returning the maximum number of packets to keep in memory at any one point, as configured by the user. Returns : maximum number of packets to be kept in memory at any time. libnd_tpm_clear_current_partvoid libnd_tpm_clear_current_part (LND_TPM *tpm, gboolean emit_signal); The function releases tpm's current trace part. If the part got modified, it is added to the layers of trace parts on top of the base file, otherwise it is simply freed. Depending on emit_signal, a LND_TRACE_CLEAR signal is delivered to registered trace observers or not. tpm : trace part manager whose current trace part to clear. emit_signal : whether to emit a LND_TRACE_CLEAR signal or not. libnd_tpm_add_partvoid libnd_tpm_add_part (LND_TPM *tpm, LND_TracePart *tp); The function adds tp to tpm's trace parts. tpm : trace part manager. tp : trace part to add. libnd_tpm_remove_partgboolean libnd_tpm_remove_part (LND_TPM *tpm, LND_TracePart *tp); The function removes tp from tpm's trace parts. This only works when tp is a plateau, that is, when there are no other parts stacked on top of it. tpm : trace part manager. tp : trace part to remove. Returns : TRUE if operation was successful, FALSE otherwise. libnd_tpm_goto_tspcapnav_result_t libnd_tpm_goto_ts (LND_TPM *tpm, struct bpf_timeval *timestamp); The function jumps to the packet whose timestamp has a timestamp closest to timestamp. If the current trace part was previously modified, it is swapped out to disk first. If the jump succeeded, an LND_TRACE_JUMPED event is fired. tpm : trace part manager. timestamp : timestamp to jump to. Returns : result of jump, PCAPNAV_DEFINITELY if it was successful. See pcapnav.h for the other possible outcomes. libnd_tpm_goto_fractionpcapnav_result_t libnd_tpm_goto_fraction (LND_TPM *tpm, double fraction); The function jumps to the packet closest to the given size fraction of the full trace. If the current trace part was previously modified, it is swapped out to disk first. If the jump succeeded, an LND_TRACE_JUMPED event is fired. tpm : trace part manager. fraction : fraction to jump to. Returns : result of jump, PCAPNAV_DEFINITELY if it was successful. See pcapnav.h for the other possible outcomes. libnd_tpm_goto_locgboolean libnd_tpm_goto_loc (LND_TPM *tpm, LND_TraceLoc *loc); The function jumps to the location given by loc. You can calculate a location in three ways: using libnd_tpm_find_offset(), libnd_tpm_find_fraction() and libnd_tpm_find_timestamp(). If the jump succeeded, an LND_TRACE_JUMPED event is fired. tpm : trace part manager. loc : location to jump to. Returns : TRUE if jump was successful, FALSE otherwise. libnd_tpm_is_tp_overlapgboolean libnd_tpm_is_tp_overlap (const LND_TPM *tpm, const LND_TracePart *tp1, const LND_TracePart *tp2); The function tests two trace parts for overlap. tpm : trace part manager. tp1 : first trace part. tp2 : second trace part. Returns : TRUE if tp1 and tp2 overlap, FALSE otherwise. libnd_tpm_map_loc_to_offsetoff_t libnd_tpm_map_loc_to_offset (const LND_TPM *tpm, const LND_TraceLoc *loc); The function takes a trace location as input an calculates the global offset in tpm's trace that corresponds to this location. Opposite to libnd_tpm_map_offset_to_loc(). tpm : trace part manager. loc : trace location. Returns : calculated offset. libnd_tpm_map_offset_to_locpcapnav_result_t libnd_tpm_map_offset_to_loc (const LND_TPM *tpm, off_t offset, LND_TraceLoc *loc); The function takes offset as input and calculates the trace location for the packet closest to offset in tpm's current trace part arrangement. Opposite of libnd_tpm_map_location_to_offset(). The resulting location is reported in loc. tpm : trace part manager. offset : offset to calculate with. loc : result pointer. Returns : success state of operation. libnd_tpm_map_loc_to_timestampgboolean libnd_tpm_map_loc_to_timestamp (LND_TPM *tpm, LND_TraceLoc *loc, struct bpf_timeval *tv); The function takes trace location loc as input and looks up the timestamp of the packet that is closest to this location in tpm's current trace part scenario. tpm : trace part manager. loc : trace location to find timestamp of. tv : result pointer for calculated timestamp. Returns : TRUE of the calculation was successful, FALSE otherwise. libnd_tpm_map_fraction_to_locpcapnav_result_t libnd_tpm_map_fraction_to_loc (const LND_TPM *tpm, double fraction, LND_TraceLoc *loc); This function calculates the location (i.e., trace part and offset within that trace part) of a fractional offset in the trace (for example, 0.5 is the middle of the trace). The resulting trace location is reported in loc upon return. tpm : trace part manager of trace. fraction : fraction to calculate. loc : result pointer, receives calculated location. Returns : the success status of the operation. This is a pcapnav result type as the function relies on pcapnav to perform this operation. libnd_tpm_map_timestamp_to_locpcapnav_result_t libnd_tpm_map_timestamp_to_loc (const LND_TPM *tpm, struct bpf_timeval *timestamp, LND_TraceLoc *loc); This function calculates the location (i.e., trace part and offset within that trace part) of the packet with a timestamp closest to timestamp. The resulting trace location is reported in loc upon return. tpm : trace part manager of trace. timestamp : timestamp to calculate. loc : result pointer, receives calculated location. Returns : the success status of the operation. This is a pcapnav result type as the function relies on pcapnav to perform this operation. libnd_tpm_get_offsetoff_t libnd_tpm_get_offset (const LND_TPM *tpm); tpm : trace part manager. Returns : the absolute offset in bytes from the start of the trace file, in the current trace parts configuration. Does not include the size of the trace file header. libnd_tpm_find_locsgboolean libnd_tpm_find_locs (const LND_TPM *tpm, LND_TraceArea *area, LND_TraceLoc *start, LND_TraceLoc *end); The function takes the trace area pointed to by area as input and calculates the start and end trace locations that the boundaries of this area correspond to in tpm's current trace part arrangement. The results are returned through start and end, respectively. tpm : trace part manager. area : trace area to calculate locations of. start : result pointer for start location. end : result pointer for end location. Returns : TRUE of the calculation was successful, FALSE otherwise. libnd_tpm_get_space_fractiondouble libnd_tpm_get_space_fraction (const LND_TPM *tpm, off_t offset); The function returns the fraction in the trace where offset is located. 0.5 means that we're currently in the middle of the file, 1.0 that we're at the end. tpm : trace part manager. offset : offset to calculate with. Returns : fraction in space. libnd_tpm_get_time_fractiondouble libnd_tpm_get_time_fraction (const LND_TPM *tpm, const struct bpf_timeval *tv); The function returns the fraction in the trace where the packet with timestamp tv is located. 0.5 means that we're currently at the point in trace whose packets are in the middle between the start- and end times of the full trace. tpm : trace part manager. tv : timestamp to calculate with. Returns : fraction in time currently visited. libnd_tpm_get_rel_sizedouble libnd_tpm_get_rel_size (const LND_TPM *tpm); The function compares the size (in bytes) of the trace part that is currently loaded into memory to the size of the entire trace, and returns that ration. tpm : trace part manager. Returns : size of trace part loaded / size of entire trace. libnd_tpm_get_packetsLND_Packet* libnd_tpm_get_packets (LND_TPM *tpm); tpm : trace part manager. Returns : first packet in list of currently loaded packets, if any. Otherwise returned value is NULL. libnd_tpm_get_selLND_Packet* libnd_tpm_get_sel (LND_TPM *tpm); tpm : trace part manager. Returns : first packet in list of selected packets in current trace part, if any. Otherwise the returned value is NULL. libnd_tpm_pcap_read_handlervoid libnd_tpm_pcap_read_handler (u_char *data, const struct pcap_pkthdr *h, const u_char *pdata); This is a pcap read handler that expects the data ptr to be an LND_TracePart *. It adds the passed packet to this trace part. data : an LND_TPM pointer. h : pointer to a pcap packet header pdata : packet data libnd_tpm_dump_partsvoid libnd_tpm_dump_parts (LND_TPM *tpm); This debugging function prints a textual description of the current trace part arrangement to the console. tpm : trace part manager whose trace parts to print.