Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
libbbparse(3)	       FreeBSD Library Functions Manual		 libbbparse(3)

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 up-
     date 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	argu-
     ment 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 ar-
     gument 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 con-
     catenated 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);
	   }

SEE ALSO
     tcplog_dumper(1), xz(1), err(3), exit(3)

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 re-
     turn code.	 Instead, it should probably return meaningful errors and let
     the calling program determine the appropriate way to handle them.

FreeBSD	13.0			 Oct 17, 2017			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | SEE ALSO | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=libbbparse&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help