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

FreeBSD Manual Pages

  
 
  

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

NAME
     libscamperfile -- scamper warts file library

LIBRARY
     scamper warts file	library	(libscamperfile	-lscamperfile)

SYNOPSIS
     #include <scamper_file.h>
     #include <scamper_addr.h>
     #include <scamper_list.h>
     #include <scamper_icmpext.h>
     #include <scamper_trace.h>
     #include <scamper_ping.h>
     #include <scamper_tracelb.h>
     #include <scamper_dealias.h>
     #include <scamper_neighbourdisc.h>
     #include <scamper_tbit.h>
     #include <scamper_sting.h>
     #include <scamper_sniff.h>

DESCRIPTION
     The libscamperfile	library	provides the ability to	read and write warts
     files produced by scamper,	read arts files	produced by CAIDA's Skitter,
     and write simple text representations of these data.  A program that uses
     libscamperfile to read a warts file (1) allocates a filter	defining the
     types of data contained in	the file the program is	interested in, (2)
     opens the file, (3) reads each object from	the file until end of file is
     reached, (4) closes the file and frees the	filter.	 A program that	uses
     libscamperfile is responsible for freeing the data	returned.

ROUTINES
     scamper_file_t * scamper_file_filter_alloc(uint16_t *types, uint16_t num)
     Allocate a	filter to use with scamper_file_read() that specifies the
     types of data the program is interested in	with the types parameter, and
     the number	of types in the	num parameter.	When the filter	is no longer
     required, the caller should use scamper_file_filter_free()	to free	the
     filter.  For each data type specified the caller is subsequently respon-
     sible for freeing the data	object when it is no longer required.  Valid
     data type values to specify in the	types array are:
       -  SCAMPER_FILE_OBJ_LIST
       -  SCAMPER_FILE_OBJ_CYCLE_START
       -  SCAMPER_FILE_OBJ_CYCLE_DEF
       -  SCAMPER_FILE_OBJ_CYCLE_STOP
       -  SCAMPER_FILE_OBJ_ADDR
       -  SCAMPER_FILE_OBJ_TRACE
       -  SCAMPER_FILE_OBJ_PING
       -  SCAMPER_FILE_OBJ_TRACELB
       -  SCAMPER_FILE_OBJ_DEALIAS
       -  SCAMPER_FILE_OBJ_NEIGHBOURDISC
       -  SCAMPER_FILE_OBJ_TBIT
       -  SCAMPER_FILE_OBJ_STING
       -  SCAMPER_FILE_OBJ_SNIFF

     void scamper_file_filter_free(scamper_file_filter_t *filter)
     Free a file filter	structure.

     int scamper_file_filter_isset(scamper_file_filter_t *filter, uint16_t
     type)
     Determine if a particular data type will be passed	by the filter.	It re-
     turns zero	if the type is not set in the filter, and one if it is.

     scamper_file_t * scamper_file_open(char *name, char mode, char *type)
     Open the file specified by	the name parameter.  The mode parameter	speci-
     fies how the file should be opened.  If the mode character	`r' is speci-
     fied the file is opened read-only.	 If the	mode character `w' is speci-
     fied the file is truncated	and opened for writing.	 If the	mode character
     `a' is specified the file is open for writing, but	without	truncating any
     existing file.  When opening a file for reading, the type parameter is
     optional as the type of file will be automatically	determined.  When
     writing a file, the type parameter	allows the caller to define whether
     the file should be	written	in "warts" or "text".  Note that only "warts"
     and "arts"	can be read by libscamperfile so use of	"warts"	is highly rec-
     ommended.

     scamper_file_t * scamper_file_openfd(int fd, char *name, char mode, char
     *type)
     Allocate a	new scamper_file_t structure with the file descriptor passed.
     The name parameter	is an optional parameter giving	the scamper_file_t a
     name.  The	mode parameter has the same meaning as in the
     scamper_file_open() function.  The	type paramater is used to define the
     type of file to be	read.  If the file descriptor is a socket and the file
     is	to be read, this parameter is useful as	libscamperfile is currently
     unable to automatically determine the type	of file	in this	scenario.
     Valid types are "warts", "arts", and "text".

     scamper_file_t * scamper_file_opennull(void)
     Allocate a	new scamper_file_t that	does not write to a file.  Use in con-
     jection with scamper_file_setwritefunc() to do your own I/O.

     void scamper_file_close(scamper_file_t *sf)
     Close the file and	free the scamper_file_t.

     void scamper_file_free(scamper_file_t *sf)
     Free the scamper_file_t but do not	close the underlying file descriptor.
     This function is useful if	the scamper_file_t was created using a file
     descriptor	and scamper_file_openfd().

     int scamper_file_read(scamper_file_t *sf, scamper_file_filter_t *filter,
     uint16_t *obj_type, void **obj_data)
     Read the next data	object from the	file according to the filter passed
     in.  Returns zero on success, -1 if an error occured.  When the end of
     file is reached, zero is returned and obj_data is set to NULL.  The next
     data object is returned in	obj_data, and the type of that object is re-
     turned in obj_type.  The caller is	responsible for	freeing	the data after
     it	is no longer required; for example, call scamper_trace_free() for
     trace objects, and	scamper_ping_free() for	ping objects.

     void scamper_file_setwritefunc(scamper_file_t *sf,	void *param,
     scamper_file_writefunc_t writefunc)
     Override the function used	to write warts data.  The writefunc takes
     three parameters: the first is the	param variable passed to
     scamper_file_setwritefunc(), the second is	a pointer to the data to
     write, and	the third is the length	of the data, in	bytes.	This function
     is	used in	conjunction with scamper_file_opennull().

EXAMPLE
     The following opens the file specified by name, reads all traceroute and
     ping data until end of file, processes the	data, calls the	appropriate
     methods to	free the data, and then	closes the file.

	   uint16_t types[] = {
	     SCAMPER_FILE_OBJ_TRACE,
	     SCAMPER_FILE_OBJ_PING,
	   };
	   scamper_file_t *in;
	   scamper_file_filter_t *filter;
	   scamper_trace_t *trace;
	   scamper_ping_t *ping;
	   uint16_t type;
	   void	*data;

	   if((filter =	scamper_file_filter_alloc(types, 2)) ==	NULL) {
	     fprintf(stderr, "could not	allocate filter\n");
	     return -1;
	   }

	   if((in = scamper_file_open(name, 'r', NULL))	== NULL) {
	     fprintf(stderr, "could not	open %s: %s\n",	name, strerror(errno));
	     return -1;
	   }

	   while(scamper_file_read(in, filter, &type, (void *)&data) ==	0) {

	     if(data ==	NULL)
	       break; /* EOF */

	     switch(type) {
	       case SCAMPER_FILE_OBJ_TRACE:
		  trace	= data;
		  process_trace(trace);
		  scamper_trace_free(trace);
		  break;

	       case SCAMPER_FILE_OBJ_PING:
		  ping = data;
		  process_ping(ping);
		  scamper_ping_free(ping);
		  break;
	     }
	   }

	   scamper_file_close(in);
	   scamper_file_filter_free(filter);

SEE ALSO
     scamper(1), sc_wartsdump(1), sc_warts2text(1),

     M.	Luckie,	Scamper: a Scalable and	Extensible Packet Prober for Active
     Measurement of the	Internet, Proc.	ACM/SIGCOMM Internet Measurement
     Conference	2010.

AUTHORS
     libscamperfile was	written	by Matthew Luckie <mjl@luckie.org.nz>.

FreeBSD	13.0			 May 12, 2011			  FreeBSD 13.0

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | ROUTINES | EXAMPLE | SEE ALSO | AUTHORS

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

home | help