1LIBSCAMPERFILE(3) BSD Library Functions Manual LIBSCAMPERFILE(3)
2
4 libscamperfile — scamper warts file library
5
7 scamper warts file library (libscamperfile -lscamperfile)
8
10 #include <scamper_file.h>
11 #include <scamper_addr.h>
12 #include <scamper_list.h>
13 #include <scamper_icmpext.h>
14 #include <scamper_trace.h>
15 #include <scamper_ping.h>
16 #include <scamper_tracelb.h>
17 #include <scamper_dealias.h>
18 #include <scamper_neighbourdisc.h>
19 #include <scamper_tbit.h>
20 #include <scamper_sting.h>
21 #include <scamper_sniff.h>
22
24 The libscamperfile library provides the ability to read and write warts
25 files produced by scamper, read arts files produced by CAIDA's Skitter,
26 and write simple text representations of these data. A program that uses
27 libscamperfile to read a warts file (1) allocates a filter defining the
28 types of data contained in the file the program is interested in, (2)
29 opens the file, (3) reads each object from the file until end of file is
30 reached, (4) closes the file and frees the filter. A program that uses
31 libscamperfile is responsible for freeing the data returned.
32
34 scamper_file_t * scamper_file_filter_alloc(uint16_t *types, uint16_t num)
35 Allocate a filter to use with scamper_file_read() that specifies the
36 types of data the program is interested in with the types parameter, and
37 the number of types in the num parameter. When the filter is no longer
38 required, the caller should use scamper_file_filter_free() to free the
39 filter. For each data type specified the caller is subsequently respon‐
40 sible for freeing the data object when it is no longer required. Valid
41 data type values to specify in the types array are:
42 - SCAMPER_FILE_OBJ_LIST
43 - SCAMPER_FILE_OBJ_CYCLE_START
44 - SCAMPER_FILE_OBJ_CYCLE_DEF
45 - SCAMPER_FILE_OBJ_CYCLE_STOP
46 - SCAMPER_FILE_OBJ_ADDR
47 - SCAMPER_FILE_OBJ_TRACE
48 - SCAMPER_FILE_OBJ_PING
49 - SCAMPER_FILE_OBJ_TRACELB
50 - SCAMPER_FILE_OBJ_DEALIAS
51 - SCAMPER_FILE_OBJ_NEIGHBOURDISC
52 - SCAMPER_FILE_OBJ_TBIT
53 - SCAMPER_FILE_OBJ_STING
54 - SCAMPER_FILE_OBJ_SNIFF
55 void scamper_file_filter_free(scamper_file_filter_t *filter)
57 Free a file filter structure.
58 int scamper_file_filter_isset(scamper_file_filter_t *filter, uint16_t
60 type)
61 Determine if a particular data type will be passed by the filter. It
62 returns zero if the type is not set in the filter, and one if it is.
63 scamper_file_t * scamper_file_open(char *name, char mode, char *type)
65 Open the file specified by the name parameter. The mode parameter speci‐
66 fies how the file should be opened. If the mode character `r' is speci‐
67 fied the file is opened read-only. If the mode character `w' is speci‐
68 fied the file is truncated and opened for writing. If the mode character
69 `a' is specified the file is open for writing, but without truncating any
70 existing file. When opening a file for reading, the type parameter is
71 optional as the type of file will be automatically determined. When
72 writing a file, the type parameter allows the caller to define whether
73 the file should be written in "warts" or "text". Note that only "warts"
74 and "arts" can be read by libscamperfile so use of "warts" is highly rec‐
75 ommended.
76 scamper_file_t * scamper_file_openfd(int fd, char *name, char mode, char
78 *type)
79 Allocate a new scamper_file_t structure with the file descriptor passed.
80 The name parameter is an optional parameter giving the scamper_file_t a
81 name. The mode parameter has the same meaning as in the
82 scamper_file_open() function. The type paramater is used to define the
83 type of file to be read. If the file descriptor is a socket and the file
84 is to be read, this parameter is useful as libscamperfile is currently
85 unable to automatically determine the type of file in this scenario.
86 Valid types are "warts", "arts", and "text".
87 scamper_file_t * scamper_file_opennull(void)
89 Allocate a new scamper_file_t that does not write to a file. Use in con‐
90 jection with scamper_file_setwritefunc() to do your own I/O.
91 void scamper_file_close(scamper_file_t *sf)
93 Close the file and free the scamper_file_t.
94 void scamper_file_free(scamper_file_t *sf)
96 Free the scamper_file_t but do not close the underlying file descriptor.
97 This function is useful if the scamper_file_t was created using a file
98 descriptor and scamper_file_openfd().
99 int scamper_file_read(scamper_file_t *sf, scamper_file_filter_t *filter,
101 uint16_t *obj_type, void **obj_data)
102 Read the next data object from the file according to the filter passed
103 in. Returns zero on success, -1 if an error occured. When the end of
104 file is reached, zero is returned and obj_data is set to NULL. The next
105 data object is returned in obj_data, and the type of that object is
106 returned in obj_type. The caller is responsible for freeing the data
107 after it is no longer required; for example, call scamper_trace_free()
108 for trace objects, and scamper_ping_free() for ping objects.
109 void scamper_file_setwritefunc(scamper_file_t *sf, void *param,
111 scamper_file_writefunc_t writefunc)
112 Override the function used to write warts data. The writefunc takes
113 three parameters: the first is the param variable passed to
114 scamper_file_setwritefunc(), the second is a pointer to the data to
115 write, and the third is the length of the data, in bytes. This function
116 is used in conjunction with scamper_file_opennull().
117
119 The following opens the file specified by name, reads all traceroute and
120 ping data until end of file, processes the data, calls the appropriate
121 methods to free the data, and then closes the file.
122 uint16_t types[] = {
124 SCAMPER_FILE_OBJ_TRACE,
125 SCAMPER_FILE_OBJ_PING,
126 };
127 scamper_file_t *in;
128 scamper_file_filter_t *filter;
129 scamper_trace_t *trace;
130 scamper_ping_t *ping;
131 uint16_t type;
132 void *data;
133 if((filter = scamper_file_filter_alloc(types, 2)) == NULL) {
135 fprintf(stderr, "could not allocate filter\n");
136 return -1;
137 }
138 if((in = scamper_file_open(name, 'r', NULL)) == NULL) {
140 fprintf(stderr, "could not open %s: %s\n", name, strerror(errno));
141 return -1;
142 }
143 while(scamper_file_read(in, filter, &type, (void *)&data) == 0) {
145 if(data == NULL)
147 break; /* EOF */
148 switch(type) {
150 case SCAMPER_FILE_OBJ_TRACE:
151 trace = data;
152 process_trace(trace);
153 scamper_trace_free(trace);
154 break;
155 case SCAMPER_FILE_OBJ_PING:
157 ping = data;
158 process_ping(ping);
159 scamper_ping_free(ping);
160 break;
161 }
162 }
163 scamper_file_close(in);
165 scamper_file_filter_free(filter);
166
168 scamper(1), sc_wartsdump(1), sc_warts2text(1),
169 M. Luckie, Scamper: a Scalable and Extensible Packet Prober for Active
171 Measurement of the Internet, Proc. ACM/SIGCOMM Internet Measurement
172 Conference 2010.
173
175 libscamperfile is written by Matthew Luckie <mjl@luckie.org.nz>.
176BSD May 12, 2011 BSD