LIBSCAMPERFILE(3) BSD Library Functions Manual LIBSCAMPERFILE(3)NAMElibscamperfile — 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
returns 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
returned 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 ALSOscamper(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.
AUTHORSlibscamperfile is written by Matthew Luckie <mjl@luckie.org.nz>.
BSD May 12, 2011 BSD
