source: lib/libtrace.h @ 27615e9

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

minor fixes

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