pcapnav

bpf_timeval

#define bpf_timeval timeval

enum pcapnav_result_t

typedef enum {
  PCAPNAV_ERROR,
  PCAPNAV_NONE,
  PCAPNAV_CLASH,
  PCAPNAV_PERHAPS,
  PCAPNAV_DEFINITELY
} pcapnav_result_t;

enum pcapnav_cmp_t

typedef enum {
  PCAPNAV_CMP_LEQ, /* less than or equal */
  PCAPNAV_CMP_GEQ, /* greater than or equal */
  PCAPNAV_CMP_ANY  /* anything */
} pcapnav_cmp_t;

enum pcapnav_dumpmode_t

typedef enum {
  PCAPNAV_DUMP_TRUNC,
  PCAPNAV_DUMP_APPEND_SAFE,
  PCAPNAV_DUMP_APPEND_FAST
} pcapnav_dumpmode_t;

pcapnav_init ()

void        pcapnav_init                    (void);

The function initializes the static options of the library, such as debugging switches etc.

pcapnav_open_offline ()

pcapnav_t*  pcapnav_open_offline            (const char *filename);

The function opens the trace file with name filename, allocates a handle for the file, and returns it. When you're done, get rid of the handle using pcapnav_close().

pcapnav_close ()

void        pcapnav_close                   (pcapnav_t *pn);

The function closes the trace handled through pcap and cleans file and cleans up pcap.

pcapnav_pcap ()

pcap_t*     pcapnav_pcap                    (pcapnav_t *pn);

Use this function for interaction with libpcap. It returns the pcap handler for the given pcapnav handler. Do *not* mess with this unless you have to -- do not close the pcap handler etc behind pcapnav's back ...

pcapnav_get_pkthdr_size ()

int         pcapnav_get_pkthdr_size         (pcapnav_t *pn);

The function returns the actual bytesize of the packet header structures in the trace for pn.

pcapnav_get_offset ()

off_t       pcapnav_get_offset              (pcapnav_t *pn);

pcapnav_get_timestamp ()

void        pcapnav_get_timestamp           (pcapnav_t *pn,
                                             struct bpf_timeval *tv);

The function returns the timestamp of next packet to be read in tv, without modifying the read marker.

pcapnav_set_offset ()

int         pcapnav_set_offset              (pcapnav_t *pn,
                                             off_t offset);

You can use this function to set the file offset for the given pcapnav handle to an offset relative to the start of the file. You can use this to quickly jump to a known valid offset in a trace. Caution: this function does take into account the trace file header, so a jump to offset 0 really jumps to offset sizeof(struct pcap_file_header).

pcapnav_get_current_timestamp ()

int         pcapnav_get_current_timestamp   (pcapnav_t *pn,
                                             struct bpf_timeval *tv);

The function returns the timestamp of the packet at the current position in the file. It assumes that the handle currently points to a valid pcap packet header. The stream position is unchanged when the function returns.

pcapnav_loop ()

int         pcapnav_loop                    (pcapnav_t *pn,
                                             int num_packets,
                                             pcap_handler handler,
                                             u_char *user_data);

The function reads up to num_packets from the trace handled by pcap and calls handler for each packet read. As in pcap, a negative value for num_packets will cause the function to loop until the end of file is hit, or an error occurs.

pcapnav_dispatch ()

int         pcapnav_dispatch                (pcapnav_t *pn,
                                             int num_packets,
                                             pcap_handler handler,
                                             u_char *user_data);

This function is like pcapnav_loop(), except it used pcap_dispatch() internally. There shouldn't be any real difference for trace files; the function is just here to anticipate changes in the pcap implementation in the future. See the pcap documentation for the remaining details.

pcapnav_next ()

const u_char* pcapnav_next                  (pcapnav_t *pn,
                                             struct pcap_pkthdr *header);

The function reads a single packet into the internal buffer and returns the packet's parameters through header. The packet data is returned. If you need to keep the packet data around, you need to allocate a chunk of data of size header->caplen and memcpy() the data over. If no more packets can be read, NULL is returned. You don't need to pass header if you don't want to.

pcapnav_has_next ()

int         pcapnav_has_next                (pcapnav_t *pn);

The function checks whether more packets can be read from the trace, from the current file position. The position is not changed after the function returns.

pcapnav_goto_timestamp ()

pcapnav_result_t pcapnav_goto_timestamp     (pcapnav_t *pn,
                                             struct bpf_timeval *timestamp);

The function tries to jump to the packet in the trace whose timestamp is as close as possible to timestamp.

pcapnav_goto_fraction ()

pcapnav_result_t pcapnav_goto_fraction      (pcapnav_t *pn,
                                             double fraction);

The function tries to jump as closely as possible to a given fraction in the file, passed through fraction as a percentage value between 0.0 and 1.0 (thus 0.5 means middle of file). Values of fraction outside the [0.0, 1.0] interval are adjusted to 0.0 or 1.0, respectively.

pcapnav_goto_offset ()

pcapnav_result_t pcapnav_goto_offset        (pcapnav_t *pn,
                                             off_t offset,
                                             pcapnav_cmp_t boundary);

The function tries to jump as closely as possible to a valid offset in the file near offset. The difference to pcapnav_set_offset() is that the latter simply modifies the file stream position, trusting that you know what you're doing. An offset of 0 is the first packet in the trace (i.e., the trace file header is not included). Using &boundary, you can limit the result to packets below, beyond, or anywhere around the requested offset.

pcapnav_get_timespan ()

int         pcapnav_get_timespan            (pcapnav_t *pn,
                                             struct bpf_timeval *start,
                                             struct bpf_timeval *end);

pcapnav_get_span ()

off_t       pcapnav_get_span                (pcapnav_t *pn);

pcapnav_get_size ()

off_t       pcapnav_get_size                (pcapnav_t *pn);

pcapnav_timeval_cmp ()

int         pcapnav_timeval_cmp             (const struct bpf_timeval *tv1,
                                             const struct bpf_timeval *tv2);

The function compares the timevals in tv1 and tv2.

pcapnav_timeval_sub ()

void        pcapnav_timeval_sub             (const struct bpf_timeval *tv1,
                                             const struct bpf_timeval *tv2,
                                             struct bpf_timeval *tv_out);

The function subtracts tv2 from tv1 in the timeval pointed to by tv_out. If tv1 represents an earlier time than tv2, then the result is a zero timestamp.

pcapnav_timeval_add ()

void        pcapnav_timeval_add             (const struct bpf_timeval *tv1,
                                             const struct bpf_timeval *tv2,
                                             struct bpf_timeval *tv_out);

The function adds tv2 to tv1 and returns the result in the timeval pointed to by tv_out.

pcapnav_get_time_fraction ()

double      pcapnav_get_time_fraction       (pcapnav_t *pn,
                                             const struct bpf_timeval *tv);

The function returns the fraction of the trace's timespan that a timestamp is at. If tv is NULL, the timestamp at the current file offset is used, tv otherwise. If tv is out of range, 0 or 1 is returned.

pcapnav_get_space_fraction ()

double      pcapnav_get_space_fraction      (pcapnav_t *pn,
                                             off_t offset);

The function returns the fraction of the trace's size that an offset is at. If offset is out of range, 0 or 1 is returned.

pcapnav_geterr ()

char*       pcapnav_geterr                  (pcapnav_t *pn);

The function returns a string describing any errors that may have occured. It's not your memory, so get your hands off or strdup() when you want to keep it around.

pcapnav_dump_open ()

pcap_dumper_t* pcapnav_dump_open            (pcap_t *pcap,
                                             const char *filename,
                                             pcapnav_dumpmode_t mode);

The function returns a pcap dumper for the file specified in filename. When mode is PCAPNAV_DUMP_TRUNC, the file is truncated if it exists, otherwise created. When mode is PCAPNAV_DUMP_APPEND_FAST or PCAPNAV_DUMP_APPEND_SAFE, packets are appended at the end of the file. The latter mode checks for truncated packets at the end of trace files, whereas the former simply starts appending at the end of the file. The mode is meaningless when filename is "-" and the output stream is standard output. In case of appending to a file, the snaplen of the existing file is updated in case the one for pcap is larger than the existing one.