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

FreeBSD Manual Pages

  
 
  

home | help 
libbbparse(3)		     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  li-
     brary  will  attempt  to  decompress  it before reading it.  If the file is
     opened successfully, the bbr_init_fd() or bbr_init_file() function will re-
     turn 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 argument
     is  zero,	the library will suppress warnings and signal errors through re-
     turn values.

RETURN VALUES
     The bbr_init_fd() and bbr_init_file() functions return a pointer to a pars-
     ing 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  encoun-
     tered 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 "un-
     known".  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);
	   }

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

FreeBSD ports 15.quarterly	  Oct 17, 2017			   libbbparse(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=bbr_init_fd&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help