libbbparse
,
bbr_init_fd
, bbr_init_file
,
bbr_fini
, bbr_get_next
,
bbr_get_stackname
,
bbr_get_tlh
— Parse a PCAPng
file with black box records
#include
<bbparse.h>
void *
bbr_init_fd
(int
fd, int
interactive);
void *
bbr_init_file
(const
char *filename, int
interactive);
void
bbr_fini
(void
*ctx);
int
bbr_get_next
(void
*ctx, const struct
tcp_log_buffer **tlb,
const struct tcphdr
**th);
const char *
bbr_get_stackname
(void
*ctx, uint8_t
stack_id);
const struct tcp_log_header *
bbr_get_tlh
(void
*ctx);
This library parses a PCAPng file which contains black box
records, such as the PCAPng files produced by the
tcplog_dumper(1)
utility.
A program initiates parsing by calling the
bbr_init_fd
()
or
bbr_init_file
()
functions. The file should be a PCAPng file, optionally compressed with the
XZ encoding. If the file is compressed with the XZ encoding, the library
will attempt to decompress it before reading it. If the file is opened
successfully, the bbr_init_fd
() or
bbr_init_file
() function will return a pointer to a
parsing context. The program should use this as the
ctx argument for calls to other functions in the
library.
Once a program has obtained a parsing context,
it can use the
bbr_get_next
()
function to obtain the next black box record in the file. The
ctx argument is a pointer to a parsing context. The
library will update the tlb and
th arguments with pointers to the next (struct
tcp_log_buffer) in the file and the associated TCP header, if any.
The
bbr_get_stackname
()
function returns the name associated with a stack ID in the file currently
being parsed.
The
bbr_get_tlh
()
function returns the current log header associated with the parsing
context.
When the program is finished with a file, it should
call the
bbr_fini
()
function to close the file and/or release resources used by the library.
The interactive argument
to the
bbr_init_fd
()
or
bbr_init_file
()
function controls the way the library handles errors and warnings. If the
interactive argument is non-zero, the library will
call
exit(3)
or err(3)
for errors, and will print warnings to stderr. If the
interactive argument is zero, the library will
suppress warnings and signal errors through return values.
The bbr_init_fd
() and
bbr_init_file
() functions return a pointer to a
parsing context. If the interactive argument is
non-zero, they always succeed. (If they would fail, they print an error and
call
exit(3).)
If the interactive argument is zero, they return NULL
on failure.
The bbr_get_next
() function returns 0 on
success or 1 if it has reached the end of the file. If the context was
created with the interactive argument set to zero, the
bbr_get_next
() function will return -1 if it has
encountered a fatal error.
The bbr_get_stackname
() function returns
the name associated with the stack ID. If the stack ID is unrecognized, the
function returns the string "unknown". Note that the stack name
can change on any call to bbr_get_next
().
(Primarily, this would occur if multiple files were concatenated together.)
Therfore, programs should not cache the return value of
bbr_get_tlh
() across calls to
bbr_get_next
().
The bbr_get_tlh
() function returns the
current log header associated with the parsing context. Note that the log
header can change on any call to bbr_get_next
().
Therfore, programs should not cache the return value of
bbr_get_tlh
() across calls to
bbr_get_next
().
To parse a file:
#include <bbparse.h>
void
parsefile(cont char *filename)
{
struct tcp_log_buffer *tlb;
struct tcphdr *th;
void *ctx;
ctx = bbr_init_file(filename, 1);
while(bbr_get_next(ctx, &lbufp, &th) == 0) {
/* Parse lbufp and th */
}
bbr_fini(ctx);
}
In interactive mode, the library will declare a fatal error and
call
exit(3)
or err(3)
when it encounters many errors parsing a file. In non-interactive mode, the
library will signal all errors using the same return code. Instead, it
should probably return meaningful errors and let the calling program
determine the appropriate way to handle them.