source: lib/wandio.h @ 8753bb8

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 8753bb8 was f258932, checked in by Shane Alcock <salcock@…>, 10 years ago
  • Bumped default number of IO buffers up to a total of 50 MB
  • Added a LIBTRACEIO option to adjust the number of IO buffers
  • Property mode set to 100644
File size: 9.0 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/** @file
43 *
44 * @brief Header file dealing with the Libtrace IO sub-system
45 *
46 * @author Perry Lorier
47 * @author Shane Alcock
48 *
49 * @version $Id$
50 */
51
52typedef struct io_t io_t; /**< Opaque IO handle structure for reading */
53typedef struct iow_t iow_t; /**< Opaque IO handle structure for writing */
54
55/** Structure defining a supported compression method */
56struct compression_type {
57        /** Name of the compression method */
58        const char *name;
59        /** Extension to add to the filename of files written using this
60         *  method */
61        const char *ext;
62        /** Internal type identifying the compression method */
63        int compress_type;
64};
65
66/** The list of supported compression methods */
67extern struct compression_type compression_type[];
68
69/** Structure defining a libtrace IO reader module */
70typedef struct {
71        /** Module name */
72        const char *name;
73
74        /** Reads from the IO source into the provided buffer.
75         *
76         * @param io            The IO reader
77         * @param buffer        The buffer to read into
78         * @param len           The amount of space available in the buffer
79         * @return The amount of bytes read, 0 if end of file is reached, -1
80         * if an error occurs
81         */
82        off_t (*read)(io_t *io, void *buffer, off_t len);
83
84        /** Reads from the IO source into the provided buffer but does not
85         *  advance the read pointer.
86         *
87         * @param io            The IO reader
88         * @param buffer        The buffer to read into
89         * @param len           The amount of space available in the buffer
90         * @return The amount of bytes read, 0 if end of file is reached, -1
91         * if an error occurs
92         */
93        off_t (*peek)(io_t *io, void *buffer, off_t len);
94
95        /** Returns the current offset of the read pointer for an IO source.
96         *
97         * @param io            The IO reader to get the read offset for
98         * @return The offset of the read pointer, or -1 if an error occurs
99         */
100        off_t (*tell)(io_t *io);
101       
102        /** Moves the read pointer for an IO source.
103         *
104         * @param io            The IO reader to move the read pointer for
105         * @param offset        The new read pointer offset
106         * @param whence        Where to start counting the new offset from.
107         *                      whence can be one of three values: SEEK_SET,
108         *                      SEEK_CUR and SEEK_END. See the lseek(2) manpage
109         *                      for more details as to what these mean.
110         * @return The value of the new read pointer, or -1 if an error occurs
111         */
112        off_t (*seek)(io_t *io, off_t offset, int whence);
113       
114        /** Closes an IO reader. This function should free the IO reader.
115         *
116         * @param io            The IO reader to close
117         */
118        void (*close)(io_t *io);
119} io_source_t;
120
121/** Structure defining a libtrace IO writer module */
122typedef struct {
123        /** The name of the module */
124        const char *name;
125       
126        /** Writes the contents of a buffer using an IO writer.
127         *
128         * @param iow           The IO writer to write the data with
129         * @param buffer        The buffer to be written
130         * @param len           The amount of writable data in the buffer
131         * @return The amount of data written, or -1 if an error occurs
132         */
133        off_t (*write)(iow_t *iow, const char *buffer, off_t len);
134
135        /** Closes an IO writer. This function should free the IO writer.
136         *
137         * @param iow           The IO writer to close
138         */
139        void (*close)(iow_t *iow);
140} iow_source_t;
141
142/** A libtrace IO reader */
143struct io_t {
144        /** The IO module that is used by the reader */
145        io_source_t *source;
146        /** Generic pointer to data required by the IO module */
147        void *data;
148};
149
150/** A libtrace IO writer */
151struct iow_t {
152        /** The IO module that is used by the writer */
153        iow_source_t *source;
154        /** Generic pointer to data required by the IO module */
155        void *data;
156};
157
158/** Enumeration of all supported compression methods */
159enum {
160        /** No compression */
161        WANDIO_COMPRESS_NONE    = 0,
162        /** Zlib compression */
163        WANDIO_COMPRESS_ZLIB    = 1,
164        /** Bzip compression */
165        WANDIO_COMPRESS_BZ2     = 2,
166        /** LZO compression */
167        WANDIO_COMPRESS_LZO     = 3,
168        /** All supported methods - used as a bitmask */
169        WANDIO_COMPRESS_MASK    = 7
170};
171
172/** @name IO open functions
173 *
174 * These functions deal with creating and initialising a new IO reader or
175 * writer.
176 *
177 * @{
178 */
179
180io_t *bz_open(io_t *parent);
181io_t *zlib_open(io_t *parent);
182io_t *thread_open(io_t *parent);
183io_t *peek_open(io_t *parent);
184io_t *stdio_open(const char *filename);
185
186iow_t *zlib_wopen(iow_t *child, int compress_level);
187iow_t *bz_wopen(iow_t *child, int compress_level);
188iow_t *lzo_wopen(iow_t *child, int compress_level);
189iow_t *thread_wopen(iow_t *child);
190iow_t *stdio_wopen(const char *filename, int fileflags);
191
192/* @} */
193
194/**
195 * @name Libtrace IO API functions
196 *
197 * These are the functions that should be called by the format modules to open
198 * and use files with the libtrace IO sub-system.
199 *
200 * @{ */
201
202/** Creates a new libtrace IO reader and opens the provided file for reading.
203 *
204 * @param filename      The name of the file to open
205 * @return A pointer to a new libtrace IO reader, or NULL if an error occurs
206 *
207 * This function will attempt to detect the compression format used for the
208 * given file (if any), provided that libtrace was built with the appropriate
209 * libraries.
210 */
211io_t *wandio_create(const char *filename);
212
213/** Returns the current offset of the read pointer for a libtrace IO reader.
214 *
215 * @param io            The IO reader to get the read offset for
216 * @return The offset of the read pointer, or -1 if an error occurs
217 */
218off_t wandio_tell(io_t *io);
219
220/** Changes the read pointer offset to the specified value for a libtrace IO
221 * reader.
222 *
223 * @param io            The IO reader to adjust the read pointer for
224 * @param offset        The new offset for the read pointer
225 * @param whence        Indicates where to set the read pointer from. Can be
226 *                      one of SEEK_SET, SEEK_CUR or SEEK_END.
227 * @return The new value for the read pointer, or -1 if an error occurs
228 *
229 * The arguments for this function are the same as those for lseek(2). See the
230 * lseek(2) manpage for more details.
231 */
232off_t wandio_seek(io_t *io, off_t offset, int whence);
233
234/** Reads from a libtrace IO reader into the provided buffer.
235 *
236 * @param io            The IO reader to read from
237 * @param buffer        The buffer to read into
238 * @param len           The size of the buffer
239 * @return The amount of bytes read, 0 if EOF is reached, -1 if an error occurs
240 */
241off_t wandio_read(io_t *io, void *buffer, off_t len);
242
243/** Reads from a libtrace IO reader into the provided buffer, but does not
244 * update the read pointer.
245 *
246 * @param io            The IO reader to read from
247 * @param buffer        The buffer to read into
248 * @param len           The size of the buffer
249 * @return The amount of bytes read, 0 if EOF is reached, -1 if an error occurs
250 */
251off_t wandio_peek(io_t *io, void *buffer, off_t len);
252
253/** Destroys a libtrace IO reader, closing the file and freeing the reader
254 * structure.
255 *
256 * @param io            The IO reader to destroy
257 */
258void wandio_destroy(io_t *io);
259
260/** Creates a new libtrace IO writer and opens the provided file for writing.
261 *
262 * @param filename              The name of the file to open
263 * @param compression_type      Compression type
264 * @param compression_level     The compression level to use when writing
265 * @param flags                 Flags to apply when opening the file, e.g.
266 *                              O_CREATE
267 * @return A pointer to the new libtrace IO writer, or NULL if an error occurs
268 */
269iow_t *wandio_wcreate(const char *filename, int compression_type, int compression_level, int flags);
270
271/** Writes the contents of a buffer using a libtrace IO writer.
272 *
273 * @param iow           The IO writer to write the data with
274 * @param buffer        The buffer to write out
275 * @param len           The amount of writable data in the buffer
276 * @return The amount of data written, or -1 if an error occurs
277 */
278off_t wandio_wwrite(iow_t *iow, const void *buffer, off_t len);
279
280/** Destroys a libtrace IO writer, closing the file and freeing the writer
281 * structure.
282 *
283 * @param iow           The IO writer to destroy
284 */
285void wandio_wdestroy(iow_t *iow);
286
287/** @} */
288
289/** @name libtraceio options
290 * @{ */
291extern int force_directio_read;
292extern int force_directio_write;
293extern uint64_t write_waits;
294extern uint64_t read_waits;
295extern unsigned int use_threads;
296extern unsigned int max_buffers;
297/* @} */
298
299#endif
Note: See TracBrowser for help on using the repository browser.