source: lib/libtrace.h @ 72429bd

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 72429bd was c5a22ec, checked in by Daniel Lawson <dlawson@…>, 17 years ago

changed bpf routines to use an opaque pointer to a filter datastructure

  • Property mode set to 100644
File size: 12.0 KB
Line 
1#ifndef _LIBTRACE_H_
2#define _LIBTRACE_H_
3/** @file
4 *
5 * @brief Trace file processing library header
6 *
7 * @author Daniel Lawson
8 * @author Perry Lorier
9 *
10 * @version $Id$
11 *
12 * This library provides a per packet interface into a trace file, or a live
13 * captures.  It supports ERF, DAG cards, WAG cards, WAG's event format,
14 * pcap etc.
15 *
16 * @par Usage
17 * <ol>
18 * <li> include "libtrace.h" (found in /usr/local/wand/include
19 * on voodoo and chasm).
20 * <li> call create_trace with the uri of the trace you're interested in.<br>
21 * This is usually passed in as argv[1] to your program.
22 * <li> call libtrace_read_packet(), passing in the libtrace_t returned from
23 * create trace and a buffer (and the buffer length)
24 * <li> call getIP() on the buffer, and do whatever you need
25 * <li> loop back to step 3, until libtrace_read_packet() returns -1
26 * </ol>
27 * @par Linking
28 * To use this library you need to link against -ltrace, -lpcapl and -lzl
29 * which are the versions of these libraries that support >2G files.  (grr!)
30 * These can be found in /usr/local/wand/lib on voodoo and chasm.
31 *
32 *
33 */
34
35#define COLLECTOR_PORT 3435
36
37/** Opaque structure holding information about a trace */
38struct libtrace_t;
39       
40/** Opaque structure holding information about a bpf filter */
41
42struct libtrace_filter_t;
43/** Structure for dealing with IP packets */
44struct libtrace_ip
45  {
46#if __BYTE_ORDER == __LITTLE_ENDIAN
47    unsigned int ip_hl:4;               /**< header length */
48    unsigned int ip_v:4;                /**< version */
49#endif
50#if __BYTE_ORDER == __BIG_ENDIAN
51    unsigned int ip_v:4;                /**< version */
52    unsigned int ip_hl:4;               /**< header length */
53#endif
54    u_int8_t ip_tos;                    /**< type of service */
55    u_short ip_len;                     /**< total length */
56    u_short ip_id;                      /**< identification */
57    u_short ip_off;                     /**< fragment offset field */
58#define IP_RF 0x8000                    /**< reserved fragment flag */
59#define IP_DF 0x4000                    /**< dont fragment flag */
60#define IP_MF 0x2000                    /**< more fragments flag */
61#define IP_OFFMASK 0x1fff               /**< mask for fragmenting bits */
62    u_int8_t ip_ttl;                    /**< time to live */
63    u_int8_t ip_p;                      /**< protocol */
64    u_short ip_sum;                     /**< checksum */
65    struct in_addr ip_src, ip_dst;      /**< source and dest address */
66  };
67
68/** Structure for dealing with TCP packets */
69struct libtrace_tcp
70  {
71    u_int16_t source;           /**< Source Port */
72    u_int16_t dest;             /**< Destination port */
73    u_int32_t seq;              /**< Sequence number */
74    u_int32_t ack_seq;          /**< Acknowledgement Number */
75#  if __BYTE_ORDER == __LITTLE_ENDIAN
76    u_int16_t res1:4;           /**< Reserved bits */
77    u_int16_t doff:4;           
78    u_int16_t fin:1;            /**< FIN */
79    u_int16_t syn:1;            /**< SYN flag */
80    u_int16_t rst:1;            /**< RST flag */
81    u_int16_t psh:1;            /**< PuSH flag */
82    u_int16_t ack:1;            /**< ACK flag */
83    u_int16_t urg:1;            /**< URG flag */
84    u_int16_t res2:2;           /**< Reserved */
85#  elif __BYTE_ORDER == __BIG_ENDIAN
86    u_int16_t doff:4;           
87    u_int16_t res1:4;
88    u_int16_t res2:2;
89    u_int16_t urg:1;
90    u_int16_t ack:1;
91    u_int16_t psh:1;
92    u_int16_t rst:1;
93    u_int16_t syn:1;
94    u_int16_t fin:1;
95#  else
96#   error "Adjust your <bits/endian.h> defines"
97#  endif
98    u_int16_t window;           /**< Window Size */
99    u_int16_t check;            /**< Checksum */
100    u_int16_t urg_ptr;          /**< Urgent Pointer */
101};
102
103/** UDP Header for dealing with UDP packets */
104struct libtrace_udp {
105  u_int16_t     source;         /**< Source port */
106  u_int16_t     dest;           /**< Destination port */
107  u_int16_t     len;            /**< Length */
108  u_int16_t     check;          /**< Checksum */
109};
110
111/** ICMP Header for dealing with icmp packets */
112struct libtrace_icmp
113{
114  u_int8_t type;                /* message type */
115  u_int8_t code;                /* type sub-code */
116  u_int16_t checksum;
117  union
118  {
119    struct
120    {
121      u_int16_t id;
122      u_int16_t sequence;
123    } echo;                     /* echo datagram */
124    u_int32_t   gateway;        /* gateway address */
125    struct
126    {
127      u_int16_t __unused;
128      u_int16_t mtu;
129    } frag;                     /* path mtu discovery */
130  } un;
131};
132
133
134
135
136/** Create a trace file from a URI
137 *
138 * @returns opaque pointer to a libtrace_t
139 *
140 * Valid URI's are:
141 *  - erf:/path/to/erf/file
142 *  - erf:/path/to/erf/file.gz
143 *  - erf:/path/to/rtclient/socket
144 *  - erf:-  (stdin)
145 *  - dag:/dev/dagcard                  (implementd?)
146 *  - pcap:pcapinterface                (eg: pcap:eth0)
147 *  - pcap:/path/to/pcap/file
148 *  - pcap:/path/to/pcap/file.gz
149 *  - pcap:/path/to/pcap/socket         (implemented?)
150 *  - pcap:-
151 *  - rtclient:hostname
152 *  - rtclient:hostname:port
153 *  - wag:/path/to/wag/file
154 *  - wag:/path/to/wag/file.gz
155 *  - wag:/path/to/wag/socket
156 *  - wag:/dev/device
157 *
158 *  If an error occured why attempting to open the trace file, NULL is returned
159 *  and an error is output to stdout.
160 */
161struct libtrace_t *create_trace(char *uri);
162
163/** Close a trace file, freeing up any resources it may have been using
164 *
165 */
166void destroy_trace(struct libtrace_t *rtclient);
167
168/** Read one packet from the trace into buffer
169 *
170 * @param libtrace      the trace to read from
171 * @param buffer        the buffer to read into
172 * @param len           the length of the buffer
173 * @param status        status of the trace (only used for RTClients)
174 * @returns number of bytes copied, -1 on error, or 0 at EOF
175 *
176 * @note the buffer must be at least as large as the largest packet (plus
177 * link layer, and trace packet metadata overhead)
178 */
179int libtrace_read_packet(struct libtrace_t *rtclient, void *buffer, size_t len, int *status);
180
181/** get a pointer to the link layer
182 * @param libtrace      a pointer to the trace object returned from gettrace
183 * @param buffer        a pointer to a filled in buffer
184 * @param buflen        a pointer to the size of the buffer
185 *
186 * @returns a pointer to the link layer, or NULL if there is no link layer
187 *
188 * @note you should call getLinkType() to find out what type of link layer
189 * this is
190 */
191void *get_link(struct libtrace_t *libtrace, void *buffer, int buflen);
192
193/** get a pointer to the IP header (if any)
194 * @param libtrace      a pointer to the trace object returned from gettrace
195 * @param buffer        a pointer to a filled in buffer
196 * @param buflen        a pointer to the size of the buffer
197 *
198 * @returns a pointer to the IP header, or NULL if there is not an IP packet
199 */
200struct libtrace_ip *get_ip(struct libtrace_t *libtrace, void *buffer, int buflen);
201
202/** get a pointer to the TCP header (if any)
203 * @param libtrace      a pointer to the trace object returned from gettrace
204 * @param buffer        a pointer to a filled in buffer
205 * @param buflen        a pointer to the size of the buffer
206 *
207 * @returns a pointer to the TCP header, or NULL if there is not a TCP packet
208 */
209struct libtrace_tcp *get_tcp(struct libtrace_t *libtrace, void *buffer, int buflen);
210
211/** get a pointer to the UDP header (if any)
212 * @param libtrace      a pointer to the trace object returned from gettrace
213 * @param buffer        a pointer to a filled in buffer
214 * @param buflen        a pointer to the size of the buffer
215 *
216 * @returns a pointer to the UDP header, or NULL if this is not a UDP packet
217 */
218struct libtrace_udp *get_udp(struct libtrace_t *libtrace, void *buffer, int buflen);
219
220/** get a pointer to the ICMP header (if any)
221 * @param libtrace      a pointer to the trace object returned from gettrace
222 * @param buffer        a pointer to a filled in buffer
223 * @param buflen        a pointer to the size of the buffer
224 *
225 * @returns a pointer to the ICMP header, or NULL if this is not a ICMP packet
226 */
227struct libtrace_icmp *get_icmp(struct libtrace_t *libtrace, void *buffer, int buflen);
228
229/** Get the current time in DAG time format
230 * @param libtrace the libtrace opaque pointer
231 * @param buffer a pointer to a filled in buffer
232 * @param buflen the length of the buffer
233 * @returns a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
234 * past 1970-01-01, the lower 32bits are partial seconds)
235 * @author Daniel Lawson
236 */
237uint64_t get_erf_timestamp(struct libtrace_t *libtrace, void *buffer, int buflen);
238
239/** Get the current time in struct timeval
240 * @param libtrace the libtrace opaque pointer
241 * @param buffer a pointer to a filled in buffer
242 * @param buflen the length of the buffer
243 * @returns time that this packet was seen in a struct timeval
244 * @author Daniel Lawson
245 * @author Perry Lorier
246 */ 
247
248struct timeval get_timeval(struct libtrace_t *libtrace, void *buffer, int buflen);
249
250/** Get the current time in floating point seconds
251 * @param libtrace the libtrace opaque pointer
252 * @param buffer a pointer to a filled in buffer
253 * @param buflen the length of the buffer
254 * @returns time that this packet was seen in 64bit floating point seconds
255 * @author Perry Lorier
256 */
257double get_seconds(struct libtrace_t *libtrace, void *buffer, int buflen);
258
259/** Get the size of the packet in the trace
260 * @param libtrace the libtrace opaque pointer
261 * @param buffer a pointer to a filled in buffer
262 * @param buflen the length of the buffer
263 * @returns the size of the packet in the trace
264 * @author Perry Lorier
265 * @note Due to this being a header capture, or anonymisation, this may not
266 * be the same size as the original packet.  See get_wire_length() for the original
267 * size of the packet.
268 * @note This can (and often is) different for different packets in a trace!
269 * @par
270 *  This is sometimes called the "snaplen".
271 */
272
273int get_capture_length(struct libtrace_t *libtrace, void *buffer, int buflen);
274
275/** Get the size of the packet as it was seen on the wire.
276 * @param libtrace the libtrace opaque pointer
277 * @param buffer a pointer to a filled in buffer
278 * @param buflen the length of the buffer
279 * @returns the size of the packet as it was on the wire.
280 * @author Perry Lorier
281 * @author Daniel Lawson
282 * @note Due to the trace being a header capture, or anonymisation this may
283 * not be the same as the Capture Len.
284 */ 
285
286int get_wire_length(struct libtrace_t *libtrace, void *buffer, int buflen);
287
288/** Link layer types
289 */
290typedef enum { 
291       TRACE_TYPE_LEGACY, 
292       TRACE_TYPE_HDLC_POS, 
293       TRACE_TYPE_ETH,
294       TRACE_TYPE_ATM,
295       TRACE_TYPE_80211,
296     } libtrace_linktype_t;
297
298/** Get the type of the link layer
299 * @param libtrace the libtrace opaque pointer
300 * @param buffer a pointer to a filled in buffer
301 * @param buflen the length of the buffer
302 * @returns libtrace_linktype_t
303 * @author Perry Lorier
304 * @author Daniel Lawson
305 */
306
307inline libtrace_linktype_t get_link_type(
308                struct libtrace_t *libtrace,
309                void *buffer,
310                int buflen);   
311
312/** Get the destination MAC addres
313 * @param libtrace the libtrace opaque pointer
314 * @param buffer a pointer to a filled in buffer
315 * @param buflen the length of the buffer
316 * @returns a pointer to the destination mac, (or NULL if there is no
317 * destination MAC)
318 * @author Perry Lorier
319 */
320uint8_t *get_destination_mac(struct libtrace_t *libtrace,
321                        void *buffer,
322                        int buflen);
323
324/** Get the source MAC addres
325 * @param libtrace the libtrace opaque pointer
326 * @param buffer a pointer to a filled in buffer
327 * @param buflen the length of the buffer
328 * @returns a pointer to the source mac, (or NULL if there is no source MAC)
329 * @author Perry Lorier
330 */
331uint8_t *get_source_mac(struct libtrace_t *libtrace,
332                        void *buffer,
333                        int buflen);
334
335/** Event types */
336typedef enum {
337        TRACE_EVENT_IOWAIT,
338        TRACE_EVENT_SLEEP,
339        TRACE_EVENT_PACKET
340} libtrace_event_t;
341
342/** process a libtrace event
343 * @returns
344 *  TRACE_EVENT_IOWAIT  Waiting on I/O on <fd>
345 *  TRACE_EVENT_SLEEP   Next event in <seconds>
346 *  TRACE_EVENT_PACKET  Packet arrived in <buffer> with size <size>
347 */
348libtrace_event_t libtrace_event(struct libtrace_t *trace,
349                        int *fd,double *seconds,
350                        void *buffer, int *size);
351
352/** setup a BPF filter
353 * @param filterstring a char * containing the bpf filter string
354 * @returns opaque pointer pointer to a libtrace_filter_t object
355 * @author Daniel Lawson
356 */
357struct libtrace_filter_t *libtrace_bpf_setfilter(const char *filterstring);
358
359/** apply a BPF filter
360 * @param libtrace the libtrace opaque pointer
361 * @param filter the filter opaque pointer
362 * @param buffer a pointer to a filled buffer
363 * @param buflen the length of the buffer
364 * @returns the return value from bpf_filter
365 * @author Daniel Lawson
366 */
367int libtrace_bpf_filter(struct libtrace_t *trace,
368                        struct libtrace_filter_t *filter,
369                        void *buffer, 
370                        int buflen);
371
372
373#endif // _LIBTRACE_H_
Note: See TracBrowser for help on using the repository browser.