`libpcapnav` Manual
Prev |  | Next

# pcapnav

## Name

pcapnav --

## Synopsis

    #define     bpf_timeval
    enum        pcapnav_result_t;
    enum        pcapnav_cmp_t;
    enum        pcapnav_dumpmode_t;
    void        pcapnav_init                    (void);
    pcapnav_t*  pcapnav_open_offline            (const char *filename);
    void        pcapnav_close                   (pcapnav_t *pn);
    pcap_t*     pcapnav_pcap                    (pcapnav_t *pn);
    int         pcapnav_get_pkthdr_size         (pcapnav_t *pn);
    off_t       pcapnav_get_offset              (pcapnav_t *pn);
    void        pcapnav_get_timestamp           (pcapnav_t *pn,
                                                 struct bpf_timeval *tv);
    int         pcapnav_set_offset              (pcapnav_t *pn,
                                                 off_t offset);
    int         pcapnav_get_current_timestamp   (pcapnav_t *pn,
                                                 struct bpf_timeval *tv);
    int         pcapnav_loop                    (pcapnav_t *pn,
                                                 int num_packets,
                                                 pcap_handler handler,
                                                 u_char *user_data);
    int         pcapnav_dispatch                (pcapnav_t *pn,
                                                 int num_packets,
                                                 pcap_handler handler,
                                                 u_char *user_data);
    const u_char* pcapnav_next                  (pcapnav_t *pn,
                                                 struct pcap_pkthdr *header);
    int         pcapnav_has_next                (pcapnav_t *pn);
    pcapnav_result_t pcapnav_goto_timestamp     (pcapnav_t *pn,
                                                 struct bpf_timeval *timestamp);
    pcapnav_result_t pcapnav_goto_fraction      (pcapnav_t *pn,
                                                 double fraction);
    pcapnav_result_t pcapnav_goto_offset        (pcapnav_t *pn,
                                                 off_t offset,
                                                 pcapnav_cmp_t boundary);
    int         pcapnav_get_timespan            (pcapnav_t *pn,
                                                 struct bpf_timeval *start,
                                                 struct bpf_timeval *end);
    off_t       pcapnav_get_span                (pcapnav_t *pn);
    off_t       pcapnav_get_size                (pcapnav_t *pn);
    int         pcapnav_timeval_cmp             (const struct bpf_timeval *tv1,
                                                 const struct bpf_timeval *tv2);
    void        pcapnav_timeval_sub             (const struct bpf_timeval *tv1,
                                                 const struct bpf_timeval *tv2,
                                                 struct bpf_timeval *tv_out);
    void        pcapnav_timeval_add             (const struct bpf_timeval *tv1,
                                                 const struct bpf_timeval *tv2,
                                                 struct bpf_timeval *tv_out);
    double      pcapnav_get_time_fraction       (pcapnav_t *pn,
                                                 const struct bpf_timeval *tv);
    double      pcapnav_get_space_fraction      (pcapnav_t *pn,
                                                 off_t offset);
    char*       pcapnav_geterr                  (pcapnav_t *pn);
    pcap_dumper_t* pcapnav_dump_open            (pcap_t *pcap,
                                                 const char *filename,
                                                 pcapnav_dumpmode_t mode);

## Description

## Details

### 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()`.

`filename` :

  name of trace to open.

Returns :

  handle for trace, or NULL when an error occured (such as invalid file type, file not readable etc). In that case check errno to see what went wrong.

### pcapnav_close ()

    void        pcapnav_close                   (pcapnav_t *pn);

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

`pn` :

  pcapnav handle.

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

`pn` :

  pcapnav handler.

Returns :

  pcap handler, or NULL on invalid input.

### 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`.

`pn` :

  pcapnav handle

Returns :

  size in bytes.

### pcapnav_get_offset ()

    off_t       pcapnav_get_offset              (pcapnav_t *pn);

`pn` :

  pcapnav handler.

Returns :

  offset, or 0 on invalid input.

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

`pn` :

  pcapnav handler.

`tv` :

  result value.

### 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).

`pn` :

  pcapnav handler.

`offset` :

  new offset.

Returns :

  0 if successful, negative value otherwise. On error, errno is set accordingly.

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

`pn` :

  pcapnav handle.

`tv` :

  pointer to timestamp receiving result

Returns :

  0 on error, value > 0 on success, and timestamp in `ts`

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

`pn` :

  pcapnav handle.

`num_packets` :

  number of packets to read.

`handler` :

  callback for each packet.

`user_data` :

  arbitrary user data passed through.

Returns :

  number of packets read, or 0 when there are no more packets to be read, or a negative value when there was an error.

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

`pn` :

  pcapnav handle.

`num_packets` :

  number of packets to read.

`handler` :

  callback for each packet.

`user_data` :

  arbitrary user data passed through.

Returns :

  number of packets read, or 0 when there are no more packets to be read, or a negative value when there was an error.

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

`pn` :

  pcapnav handle.

`header` :

  pointer to allocated pcapnav packet header.

Returns :

  packet data, and pcap packet header through `header`.

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

`pn` :

  pcapnav handle.

Returns :

  0 if no more packets are readable, value > 0 otherwise.

### 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`.

`pn` :

  pcapnav handle.

`timestamp` :

  timestamp to jump to.

Returns :

  success state.

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

`pn` :

  pcapnav handle.

`fraction` :

  position to jump to.

Returns :

  success state.

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

`pn` :

  pcapnav handle.

`offset` :

  position to jump to.

`boundary` :

  where around the offset to jump to.

Returns :

  success state.

### pcapnav_get_timespan ()

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

`pn` :

`start` :

`end` :

Returns :

### pcapnav_get_span ()

    off_t       pcapnav_get_span                (pcapnav_t *pn);

`pn` :

  pcapnav handle.

Returns :

  the offset of the last packet in the trace.

### pcapnav_get_size ()

    off_t       pcapnav_get_size                (pcapnav_t *pn);

`pn` :

  pcapnav handle.

Returns :

  the size of the trace minus the file header size.

### 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`.

`tv1` :

  pointer to input timeval.

`tv2` :

  pointer to input timeval.

Returns :

  negative value if `tv1` is smaller than `tv2`, 0 if they're identical, and 1 if `tv1` is greater than `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.

`tv1` :

  pointer to input timeval.

`tv2` :

  pointer to input timeval.

`tv_out` :

  pointer to result interval.

### 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`.

`tv1` :

  pointer to input timeval.

`tv2` :

  pointer to input timeval.

`tv_out` :

  pointer to result interval.

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

`pn` :

  pcapnav handle.

`tv` :

  timestamp to calculate with.

Returns :

  value in [0, 1].

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

`pn` :

  pcapnav handle.

`offset` :

  offset to calculate with.

Returns :

  value in [0, 1].

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

`pn` :

  pcapnav handle.

Returns :

  string containing error message

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

`pcap` :

  pcap handle

`filename` :

  name of the output file.

`mode` :

  the output file mode.

Returns :

  a pcap dumper, or NULL if something went wrong, in which case you'll find the reason in the error buffer in the `pcap` handle.

Prev | Home | Next
`libpcapnav` API Reference | Up | pcapnav_timestamp