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,  option-
       ally  compressed	 with the XZ encoding.	If the file is compressed with
       the XZ encoding,	the library will attempt to decompress it before read-
       ing 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  li-
       brary.

       The  interactive	argument to the	bbr_init_fd() or bbr_init_file() func-
       tion 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);
	     }

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 14.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_get_tlh&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help