`libnetdude` Manual
Prev |  | Next

# libnd_tpm

## Name

libnd_tpm --

## Synopsis

    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);

## Description

## Details

### enum LND_TPM_NavMode

    typedef enum {
      LND_TPM_SPACE,
      LND_TPM_TIME,
      LND_TPM_ERROR
    } LND_TPM_NavMode;

### libnd_tpm_new ()

    LND_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_free ()

    void        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_packet ()

    gboolean    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_packets ()

    void        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_part ()

    void        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_part ()

    void        libnd_tpm_load_next_part        (LND_TPM *tpm);

`tpm` :

### libnd_tpm_set_output_file ()

    void        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_packets ()

    guint       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_part ()

    void        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_part ()

    void        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_part ()

    gboolean    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_ts ()

    pcapnav_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_fraction ()

    pcapnav_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_loc ()

    gboolean    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_overlap ()

    gboolean    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_offset ()

    off_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_loc ()

    pcapnav_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_timestamp ()

    gboolean    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_loc ()

    pcapnav_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_loc ()

    pcapnav_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_offset ()

    off_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_locs ()

    gboolean    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_fraction ()

    double      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_fraction ()

    double      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_size ()

    double      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_packets ()

    LND_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_sel ()

    LND_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_handler ()

    void        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_parts ()

    void        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.

Prev | Home | Next
libnd_tp | Up | libnd_trace