source: lib/libtrace.h @ 2c060e3

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

Initial revision

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