NAME

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

SYNOPSIS

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

DESCRIPTION

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.

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

EXAMPLES

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

BUGS

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.