source: libwandio/wandio.h @ 0acfd1e

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 0acfd1e was 0acfd1e, checked in by Shane Alcock <salcock@…>, 8 years ago
  • Added a wandio_create_uncompressed function to the libwandio API. It's there for people who are running into problems with the compression autodetection incorrectly thinking their uncompressed files are actually compressed. Hopefully, this should be very very rare, but it can't hurt to have it right?
  • Property mode set to 100644
File size: 10.4 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#if __GNUC__ >= 3
56#  define DEPRECATED __attribute__((deprecated))
57#  define SIMPLE_FUNCTION __attribute__((pure))
58#  define UNUSED __attribute__((unused))
59#  define PACKED __attribute__((packed))
60#  define PRINTF(formatpos,argpos) __attribute__((format(printf,formatpos,argpos)))
61#else
62#  define DEPRECATED
63#  define SIMPLE_FUNCTION
64#  define UNUSED
65#  define PACKED
66#  define PRINTF(formatpos,argpos)
67#endif
68
69
70/** @file
71 *
72 * @brief Header file dealing with the Libtrace IO sub-system
73 *
74 * @author Perry Lorier
75 * @author Shane Alcock
76 *
77 * @version $Id$
78 */
79
80typedef struct io_t io_t; /**< Opaque IO handle structure for reading */
81typedef struct iow_t iow_t; /**< Opaque IO handle structure for writing */
82
83/** Structure defining a supported compression method */
84struct compression_type {
85        /** Name of the compression method */
86        const char *name;
87        /** Extension to add to the filename of files written using this
88         *  method */
89        const char *ext;
90        /** Internal type identifying the compression method */
91        int compress_type;
92};
93
94/** The list of supported compression methods */
95extern struct compression_type compression_type[];
96
97/** Structure defining a libtrace IO reader module */
98typedef struct {
99        /** Module name */
100        const char *name;
101
102        /** Reads from the IO source into the provided buffer.
103         *
104         * @param io            The IO reader
105         * @param buffer        The buffer to read into
106         * @param len           The amount of space available in the buffer
107         * @return The amount of bytes read, 0 if end of file is reached, -1
108         * if an error occurs
109         */
110        off_t (*read)(io_t *io, void *buffer, off_t len);
111
112        /** Reads from the IO source into the provided buffer but does not
113         *  advance the read pointer.
114         *
115         * @param io            The IO reader
116         * @param buffer        The buffer to read into
117         * @param len           The amount of space available in the buffer
118         * @return The amount of bytes read, 0 if end of file is reached, -1
119         * if an error occurs
120         */
121        off_t (*peek)(io_t *io, void *buffer, off_t len);
122
123        /** Returns the current offset of the read pointer for an IO source.
124         *
125         * @param io            The IO reader to get the read offset for
126         * @return The offset of the read pointer, or -1 if an error occurs
127         */
128        off_t (*tell)(io_t *io);
129       
130        /** Moves the read pointer for an IO source.
131         *
132         * @param io            The IO reader to move the read pointer for
133         * @param offset        The new read pointer offset
134         * @param whence        Where to start counting the new offset from.
135         *                      whence can be one of three values: SEEK_SET,
136         *                      SEEK_CUR and SEEK_END. See the lseek(2) manpage
137         *                      for more details as to what these mean.
138         * @return The value of the new read pointer, or -1 if an error occurs
139         */
140        off_t (*seek)(io_t *io, off_t offset, int whence);
141       
142        /** Closes an IO reader. This function should free the IO reader.
143         *
144         * @param io            The IO reader to close
145         */
146        void (*close)(io_t *io);
147} io_source_t;
148
149/** Structure defining a libtrace IO writer module */
150typedef struct {
151        /** The name of the module */
152        const char *name;
153       
154        /** Writes the contents of a buffer using an IO writer.
155         *
156         * @param iow           The IO writer to write the data with
157         * @param buffer        The buffer to be written
158         * @param len           The amount of writable data in the buffer
159         * @return The amount of data written, or -1 if an error occurs
160         */
161        off_t (*write)(iow_t *iow, const char *buffer, off_t len);
162
163        /** Closes an IO writer. This function should free the IO writer.
164         *
165         * @param iow           The IO writer to close
166         */
167        void (*close)(iow_t *iow);
168} iow_source_t;
169
170/** A libtrace IO reader */
171struct io_t {
172        /** The IO module that is used by the reader */
173        io_source_t *source;
174        /** Generic pointer to data required by the IO module */
175        void *data;
176};
177
178/** A libtrace IO writer */
179struct iow_t {
180        /** The IO module that is used by the writer */
181        iow_source_t *source;
182        /** Generic pointer to data required by the IO module */
183        void *data;
184};
185
186/** Enumeration of all supported compression methods */
187enum {
188        /** No compression */
189        WANDIO_COMPRESS_NONE    = 0,
190        /** Zlib compression */
191        WANDIO_COMPRESS_ZLIB    = 1,
192        /** Bzip compression */
193        WANDIO_COMPRESS_BZ2     = 2,
194        /** LZO compression */
195        WANDIO_COMPRESS_LZO     = 3,
196        /** All supported methods - used as a bitmask */
197        WANDIO_COMPRESS_MASK    = 7
198};
199
200/** @name IO open functions
201 *
202 * These functions deal with creating and initialising a new IO reader or
203 * writer.
204 *
205 * @{
206 */
207
208io_t *bz_open(io_t *parent);
209io_t *zlib_open(io_t *parent);
210io_t *thread_open(io_t *parent);
211io_t *peek_open(io_t *parent);
212io_t *stdio_open(const char *filename);
213
214iow_t *zlib_wopen(iow_t *child, int compress_level);
215iow_t *bz_wopen(iow_t *child, int compress_level);
216iow_t *lzo_wopen(iow_t *child, int compress_level);
217iow_t *thread_wopen(iow_t *child);
218iow_t *stdio_wopen(const char *filename, int fileflags);
219
220/* @} */
221
222/**
223 * @name Libtrace IO API functions
224 *
225 * These are the functions that should be called by the format modules to open
226 * and use files with the libtrace IO sub-system.
227 *
228 * @{ */
229
230/** Creates a new libtrace IO reader and opens the provided file for reading.
231 *
232 * @param filename      The name of the file to open
233 * @return A pointer to a new libtrace IO reader, or NULL if an error occurs
234 *
235 * The compression format will be determined automatically by peeking at the
236 * first few bytes of the file and comparing them against known compression
237 * file header formats. If no formats match, the file will be assumed to be
238 * uncompressed.
239 */
240io_t *wandio_create(const char *filename);
241
242/** Creates a new libtrace IO reader and opens the provided file for reading.
243 *
244 * @param filename      The name of the file to open
245 * @return A pointer to a new libtrace IO reader, or NULL if an error occurs
246 *
247 * Unlike wandio_create, this function will always assume the file is
248 * uncompressed and therefore not run the compression autodetection algorithm.
249 *
250 * Use this function if you are only working with uncompressed files and are
251 * running into problems with the start of your files resembling compression
252 * format headers. Otherwise, you should really be using wandio_create.
253 */
254io_t *wandio_create_uncompressed(const char *filename);
255
256/** Returns the current offset of the read pointer for a libtrace IO reader.
257 *
258 * @param io            The IO reader to get the read offset for
259 * @return The offset of the read pointer, or -1 if an error occurs
260 */
261off_t wandio_tell(io_t *io);
262
263/** Changes the read pointer offset to the specified value for a libtrace IO
264 * reader.
265 *
266 * @param io            The IO reader to adjust the read pointer for
267 * @param offset        The new offset for the read pointer
268 * @param whence        Indicates where to set the read pointer from. Can be
269 *                      one of SEEK_SET, SEEK_CUR or SEEK_END.
270 * @return The new value for the read pointer, or -1 if an error occurs
271 *
272 * The arguments for this function are the same as those for lseek(2). See the
273 * lseek(2) manpage for more details.
274 */
275off_t wandio_seek(io_t *io, off_t offset, int whence);
276
277/** Reads from a libtrace IO reader into the provided buffer.
278 *
279 * @param io            The IO reader to read from
280 * @param buffer        The buffer to read into
281 * @param len           The size of the buffer
282 * @return The amount of bytes read, 0 if EOF is reached, -1 if an error occurs
283 */
284off_t wandio_read(io_t *io, void *buffer, off_t len);
285
286/** Reads from a libtrace IO reader into the provided buffer, but does not
287 * update the read pointer.
288 *
289 * @param io            The IO reader to read from
290 * @param buffer        The buffer to read into
291 * @param len           The size of the buffer
292 * @return The amount of bytes read, 0 if EOF is reached, -1 if an error occurs
293 */
294off_t wandio_peek(io_t *io, void *buffer, off_t len);
295
296/** Destroys a libtrace IO reader, closing the file and freeing the reader
297 * structure.
298 *
299 * @param io            The IO reader to destroy
300 */
301void wandio_destroy(io_t *io);
302
303/** Creates a new libtrace IO writer and opens the provided file for writing.
304 *
305 * @param filename              The name of the file to open
306 * @param compression_type      Compression type
307 * @param compression_level     The compression level to use when writing
308 * @param flags                 Flags to apply when opening the file, e.g.
309 *                              O_CREATE
310 * @return A pointer to the new libtrace IO writer, or NULL if an error occurs
311 */
312iow_t *wandio_wcreate(const char *filename, int compression_type, int compression_level, int flags);
313
314/** Writes the contents of a buffer using a libtrace IO writer.
315 *
316 * @param iow           The IO writer to write the data with
317 * @param buffer        The buffer to write out
318 * @param len           The amount of writable data in the buffer
319 * @return The amount of data written, or -1 if an error occurs
320 */
321off_t wandio_wwrite(iow_t *iow, const void *buffer, off_t len);
322
323/** Destroys a libtrace IO writer, closing the file and freeing the writer
324 * structure.
325 *
326 * @param iow           The IO writer to destroy
327 */
328void wandio_wdestroy(iow_t *iow);
329
330/** @} */
331
332/** @name libtraceio options
333 * @{ */
334extern int force_directio_read;
335extern int force_directio_write;
336extern uint64_t write_waits;
337extern uint64_t read_waits;
338extern unsigned int use_threads;
339extern unsigned int max_buffers;
340/* @} */
341
342#endif
Note: See TracBrowser for help on using the repository browser.