source: lib/wandio.h @ bd6576d

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since bd6576d was bd6576d, checked in by Shane Alcock <salcock@…>, 10 years ago
  • Export the wandio functions - they might come in handy for users and we're installing wandio.h anyway...
  • Property mode set to 100644
File size: 9.2 KB
Line 
1/*
2 * This file is part of libtrace
3 *
4 * Copyright (c) 2007,2008,2009,2010 The University of Waikato, Hamilton,
5 * New Zealand.
6 *
7 * Authors: Daniel Lawson
8 *          Perry Lorier
9 *          Shane Alcock
10 *         
11 * All rights reserved.
12 *
13 * This code has been developed by the University of Waikato WAND
14 * research group. For further information please see http://www.wand.net.nz/
15 *
16 * libtrace is free software; you can redistribute it and/or modify
17 * it under the terms of the GNU General Public License as published by
18 * the Free Software Foundation; either version 2 of the License, or
19 * (at your option) any later version.
20 *
21 * libtrace is distributed in the hope that it will be useful,
22 * but WITHOUT ANY WARRANTY; without even the implied warranty of
23 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
24 * GNU General Public License for more details.
25 *
26 * You should have received a copy of the GNU General Public License
27 * along with libtrace; if not, write to the Free Software
28 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
29 *
30 * $Id$
31 *
32 */
33
34#ifndef IO_H
35#define IO_H 1 /**< Guard Define */
36#include "config.h"
37#include <sys/types.h>
38#include <stdio.h>
39#include <inttypes.h>
40#include <stdbool.h>
41
42#if __GNUC__ >= 4
43        #ifdef LT_BUILDING_DLL
44                #define DLLEXPORT __attribute__ ((visibility("default")))
45                #define DLLLOCAL __attribute__ ((visibility("hidden")))
46        #else
47                #define DLLEXPORT
48                #define DLLLOCAL
49        #endif
50#else
51        #define DLLEXPORT
52        #define DLLLOCAL
53#endif
54
55
56
57/** @file
58 *
59 * @brief Header file dealing with the Libtrace IO sub-system
60 *
61 * @author Perry Lorier
62 * @author Shane Alcock
63 *
64 * @version $Id$
65 */
66
67typedef struct io_t io_t; /**< Opaque IO handle structure for reading */
68typedef struct iow_t iow_t; /**< Opaque IO handle structure for writing */
69
70/** Structure defining a supported compression method */
71struct compression_type {
72        /** Name of the compression method */
73        const char *name;
74        /** Extension to add to the filename of files written using this
75         *  method */
76        const char *ext;
77        /** Internal type identifying the compression method */
78        int compress_type;
79};
80
81/** The list of supported compression methods */
82extern struct compression_type compression_type[];
83
84/** Structure defining a libtrace IO reader module */
85typedef struct {
86        /** Module name */
87        const char *name;
88
89        /** Reads from the IO source into the provided buffer.
90         *
91         * @param io            The IO reader
92         * @param buffer        The buffer to read into
93         * @param len           The amount of space available in the buffer
94         * @return The amount of bytes read, 0 if end of file is reached, -1
95         * if an error occurs
96         */
97        off_t (*read)(io_t *io, void *buffer, off_t len);
98
99        /** Reads from the IO source into the provided buffer but does not
100         *  advance the read pointer.
101         *
102         * @param io            The IO reader
103         * @param buffer        The buffer to read into
104         * @param len           The amount of space available in the buffer
105         * @return The amount of bytes read, 0 if end of file is reached, -1
106         * if an error occurs
107         */
108        off_t (*peek)(io_t *io, void *buffer, off_t len);
109
110        /** Returns the current offset of the read pointer for an IO source.
111         *
112         * @param io            The IO reader to get the read offset for
113         * @return The offset of the read pointer, or -1 if an error occurs
114         */
115        off_t (*tell)(io_t *io);
116       
117        /** Moves the read pointer for an IO source.
118         *
119         * @param io            The IO reader to move the read pointer for
120         * @param offset        The new read pointer offset
121         * @param whence        Where to start counting the new offset from.
122         *                      whence can be one of three values: SEEK_SET,
123         *                      SEEK_CUR and SEEK_END. See the lseek(2) manpage
124         *                      for more details as to what these mean.
125         * @return The value of the new read pointer, or -1 if an error occurs
126         */
127        off_t (*seek)(io_t *io, off_t offset, int whence);
128       
129        /** Closes an IO reader. This function should free the IO reader.
130         *
131         * @param io            The IO reader to close
132         */
133        void (*close)(io_t *io);
134} io_source_t;
135
136/** Structure defining a libtrace IO writer module */
137typedef struct {
138        /** The name of the module */
139        const char *name;
140       
141        /** Writes the contents of a buffer using an IO writer.
142         *
143         * @param iow           The IO writer to write the data with
144         * @param buffer        The buffer to be written
145         * @param len           The amount of writable data in the buffer
146         * @return The amount of data written, or -1 if an error occurs
147         */
148        off_t (*write)(iow_t *iow, const char *buffer, off_t len);
149
150        /** Closes an IO writer. This function should free the IO writer.
151         *
152         * @param iow           The IO writer to close
153         */
154        void (*close)(iow_t *iow);
155} iow_source_t;
156
157/** A libtrace IO reader */
158struct io_t {
159        /** The IO module that is used by the reader */
160        io_source_t *source;
161        /** Generic pointer to data required by the IO module */
162        void *data;
163};
164
165/** A libtrace IO writer */
166struct iow_t {
167        /** The IO module that is used by the writer */
168        iow_source_t *source;
169        /** Generic pointer to data required by the IO module */
170        void *data;
171};
172
173/** Enumeration of all supported compression methods */
174enum {
175        /** No compression */
176        WANDIO_COMPRESS_NONE    = 0,
177        /** Zlib compression */
178        WANDIO_COMPRESS_ZLIB    = 1,
179        /** Bzip compression */
180        WANDIO_COMPRESS_BZ2     = 2,
181        /** LZO compression */
182        WANDIO_COMPRESS_LZO     = 3,
183        /** All supported methods - used as a bitmask */
184        WANDIO_COMPRESS_MASK    = 7
185};
186
187/** @name IO open functions
188 *
189 * These functions deal with creating and initialising a new IO reader or
190 * writer.
191 *
192 * @{
193 */
194
195io_t *bz_open(io_t *parent);
196io_t *zlib_open(io_t *parent);
197io_t *thread_open(io_t *parent);
198io_t *peek_open(io_t *parent);
199io_t *stdio_open(const char *filename);
200
201iow_t *zlib_wopen(iow_t *child, int compress_level);
202iow_t *bz_wopen(iow_t *child, int compress_level);
203iow_t *lzo_wopen(iow_t *child, int compress_level);
204iow_t *thread_wopen(iow_t *child);
205iow_t *stdio_wopen(const char *filename, int fileflags);
206
207/* @} */
208
209/**
210 * @name Libtrace IO API functions
211 *
212 * These are the functions that should be called by the format modules to open
213 * and use files with the libtrace IO sub-system.
214 *
215 * @{ */
216
217/** Creates a new libtrace IO reader and opens the provided file for reading.
218 *
219 * @param filename      The name of the file to open
220 * @return A pointer to a new libtrace IO reader, or NULL if an error occurs
221 *
222 * This function will attempt to detect the compression format used for the
223 * given file (if any), provided that libtrace was built with the appropriate
224 * libraries.
225 */
226io_t *wandio_create(const char *filename);
227
228/** Returns the current offset of the read pointer for a libtrace IO reader.
229 *
230 * @param io            The IO reader to get the read offset for
231 * @return The offset of the read pointer, or -1 if an error occurs
232 */
233off_t wandio_tell(io_t *io);
234
235/** Changes the read pointer offset to the specified value for a libtrace IO
236 * reader.
237 *
238 * @param io            The IO reader to adjust the read pointer for
239 * @param offset        The new offset for the read pointer
240 * @param whence        Indicates where to set the read pointer from. Can be
241 *                      one of SEEK_SET, SEEK_CUR or SEEK_END.
242 * @return The new value for the read pointer, or -1 if an error occurs
243 *
244 * The arguments for this function are the same as those for lseek(2). See the
245 * lseek(2) manpage for more details.
246 */
247off_t wandio_seek(io_t *io, off_t offset, int whence);
248
249/** Reads from a libtrace IO reader into the provided buffer.
250 *
251 * @param io            The IO reader to read from
252 * @param buffer        The buffer to read into
253 * @param len           The size of the buffer
254 * @return The amount of bytes read, 0 if EOF is reached, -1 if an error occurs
255 */
256off_t wandio_read(io_t *io, void *buffer, off_t len);
257
258/** Reads from a libtrace IO reader into the provided buffer, but does not
259 * update the read pointer.
260 *
261 * @param io            The IO reader to read from
262 * @param buffer        The buffer to read into
263 * @param len           The size of the buffer
264 * @return The amount of bytes read, 0 if EOF is reached, -1 if an error occurs
265 */
266off_t wandio_peek(io_t *io, void *buffer, off_t len);
267
268/** Destroys a libtrace IO reader, closing the file and freeing the reader
269 * structure.
270 *
271 * @param io            The IO reader to destroy
272 */
273void wandio_destroy(io_t *io);
274
275/** Creates a new libtrace IO writer and opens the provided file for writing.
276 *
277 * @param filename              The name of the file to open
278 * @param compression_type      Compression type
279 * @param compression_level     The compression level to use when writing
280 * @param flags                 Flags to apply when opening the file, e.g.
281 *                              O_CREATE
282 * @return A pointer to the new libtrace IO writer, or NULL if an error occurs
283 */
284iow_t *wandio_wcreate(const char *filename, int compression_type, int compression_level, int flags);
285
286/** Writes the contents of a buffer using a libtrace IO writer.
287 *
288 * @param iow           The IO writer to write the data with
289 * @param buffer        The buffer to write out
290 * @param len           The amount of writable data in the buffer
291 * @return The amount of data written, or -1 if an error occurs
292 */
293off_t wandio_wwrite(iow_t *iow, const void *buffer, off_t len);
294
295/** Destroys a libtrace IO writer, closing the file and freeing the writer
296 * structure.
297 *
298 * @param iow           The IO writer to destroy
299 */
300void wandio_wdestroy(iow_t *iow);
301
302/** @} */
303
304/** @name libtraceio options
305 * @{ */
306extern int force_directio_read;
307extern int force_directio_write;
308extern uint64_t write_waits;
309extern uint64_t read_waits;
310extern unsigned int use_threads;
311extern unsigned int max_buffers;
312/* @} */
313
314#endif
Note: See TracBrowser for help on using the repository browser.