source: libwandio/wandio.h @ bd37451

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since bd37451 was bd37451, checked in by Shane Alcock <salcock@…>, 9 years ago
  • Fixed build error due to iow-lzo.c requiring libtrace.h
  • Property mode set to 100644
File size: 9.6 KB
RevLine 
[81c0b9e]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
[6a5b8a4]34#ifndef IO_H
35#define IO_H 1 /**< Guard Define */
[948ed9a]36#include "config.h"
[c66068d]37#include <sys/types.h>
38#include <stdio.h>
[29d4438]39#include <inttypes.h>
[6f8745b]40#include <stdbool.h>
[c66068d]41
[bd6576d]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
[bd37451]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
[bd6576d]68
69
[81c0b9e]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
[6a5b8a4]80typedef struct io_t io_t; /**< Opaque IO handle structure for reading */
81typedef struct iow_t iow_t; /**< Opaque IO handle structure for writing */
[c66068d]82
[81c0b9e]83/** Structure defining a supported compression method */
[c66068d]84struct compression_type {
[81c0b9e]85        /** Name of the compression method */
[c66068d]86        const char *name;
[81c0b9e]87        /** Extension to add to the filename of files written using this
88         *  method */
[c66068d]89        const char *ext;
[81c0b9e]90        /** Internal type identifying the compression method */
[baef9df]91        int compress_type;
[c66068d]92};
[81c0b9e]93
94/** The list of supported compression methods */
[c66068d]95extern struct compression_type compression_type[];
96
[81c0b9e]97/** Structure defining a libtrace IO reader module */
[c66068d]98typedef struct {
[81c0b9e]99        /** Module name */
[c66068d]100        const char *name;
[81c0b9e]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         */
[c66068d]110        off_t (*read)(io_t *io, void *buffer, off_t len);
[81c0b9e]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         */
[c66068d]121        off_t (*peek)(io_t *io, void *buffer, off_t len);
[81c0b9e]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         */
[c66068d]128        off_t (*tell)(io_t *io);
[81c0b9e]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         */
[c66068d]140        off_t (*seek)(io_t *io, off_t offset, int whence);
[81c0b9e]141       
142        /** Closes an IO reader. This function should free the IO reader.
143         *
144         * @param io            The IO reader to close
145         */
[c66068d]146        void (*close)(io_t *io);
147} io_source_t;
148
[81c0b9e]149/** Structure defining a libtrace IO writer module */
[c66068d]150typedef struct {
[81c0b9e]151        /** The name of the module */
[c66068d]152        const char *name;
[81c0b9e]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         */
[c66068d]161        off_t (*write)(iow_t *iow, const char *buffer, off_t len);
[81c0b9e]162
163        /** Closes an IO writer. This function should free the IO writer.
164         *
165         * @param iow           The IO writer to close
166         */
[c66068d]167        void (*close)(iow_t *iow);
168} iow_source_t;
169
[81c0b9e]170/** A libtrace IO reader */
[c66068d]171struct io_t {
[81c0b9e]172        /** The IO module that is used by the reader */
[c66068d]173        io_source_t *source;
[81c0b9e]174        /** Generic pointer to data required by the IO module */
[c66068d]175        void *data;
176};
177
[81c0b9e]178/** A libtrace IO writer */
[c66068d]179struct iow_t {
[81c0b9e]180        /** The IO module that is used by the writer */
[c66068d]181        iow_source_t *source;
[81c0b9e]182        /** Generic pointer to data required by the IO module */
[c66068d]183        void *data;
184};
185
[81c0b9e]186/** Enumeration of all supported compression methods */
[c66068d]187enum {
[81c0b9e]188        /** No compression */
[c66068d]189        WANDIO_COMPRESS_NONE    = 0,
[81c0b9e]190        /** Zlib compression */
[c66068d]191        WANDIO_COMPRESS_ZLIB    = 1,
[81c0b9e]192        /** Bzip compression */
[c66068d]193        WANDIO_COMPRESS_BZ2     = 2,
[5e26f1d]194        /** LZO compression */
195        WANDIO_COMPRESS_LZO     = 3,
[81c0b9e]196        /** All supported methods - used as a bitmask */
[29d4438]197        WANDIO_COMPRESS_MASK    = 7
[c66068d]198};
199
[81c0b9e]200/** @name IO open functions
201 *
202 * These functions deal with creating and initialising a new IO reader or
203 * writer.
204 *
205 * @{
206 */
[c66068d]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);
[5e26f1d]216iow_t *lzo_wopen(iow_t *child, int compress_level);
[c66068d]217iow_t *thread_wopen(iow_t *child);
[baef9df]218iow_t *stdio_wopen(const char *filename, int fileflags);
[c66068d]219
[81c0b9e]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 * This function will attempt to detect the compression format used for the
236 * given file (if any), provided that libtrace was built with the appropriate
237 * libraries.
238 */
[c66068d]239io_t *wandio_create(const char *filename);
[81c0b9e]240
241/** Returns the current offset of the read pointer for a libtrace IO reader.
242 *
243 * @param io            The IO reader to get the read offset for
244 * @return The offset of the read pointer, or -1 if an error occurs
245 */
[c66068d]246off_t wandio_tell(io_t *io);
[81c0b9e]247
248/** Changes the read pointer offset to the specified value for a libtrace IO
249 * reader.
250 *
251 * @param io            The IO reader to adjust the read pointer for
252 * @param offset        The new offset for the read pointer
253 * @param whence        Indicates where to set the read pointer from. Can be
254 *                      one of SEEK_SET, SEEK_CUR or SEEK_END.
255 * @return The new value for the read pointer, or -1 if an error occurs
256 *
257 * The arguments for this function are the same as those for lseek(2). See the
258 * lseek(2) manpage for more details.
259 */
[c66068d]260off_t wandio_seek(io_t *io, off_t offset, int whence);
[81c0b9e]261
262/** Reads from a libtrace IO reader into the provided buffer.
263 *
264 * @param io            The IO reader to read from
265 * @param buffer        The buffer to read into
266 * @param len           The size of the buffer
267 * @return The amount of bytes read, 0 if EOF is reached, -1 if an error occurs
268 */
[c66068d]269off_t wandio_read(io_t *io, void *buffer, off_t len);
[81c0b9e]270
271/** Reads from a libtrace IO reader into the provided buffer, but does not
272 * update the read pointer.
273 *
274 * @param io            The IO reader to read from
275 * @param buffer        The buffer to read into
276 * @param len           The size of the buffer
277 * @return The amount of bytes read, 0 if EOF is reached, -1 if an error occurs
278 */
[c66068d]279off_t wandio_peek(io_t *io, void *buffer, off_t len);
[81c0b9e]280
281/** Destroys a libtrace IO reader, closing the file and freeing the reader
282 * structure.
283 *
284 * @param io            The IO reader to destroy
285 */
[c66068d]286void wandio_destroy(io_t *io);
287
[81c0b9e]288/** Creates a new libtrace IO writer and opens the provided file for writing.
289 *
290 * @param filename              The name of the file to open
[b5af22c]291 * @param compression_type      Compression type
[81c0b9e]292 * @param compression_level     The compression level to use when writing
293 * @param flags                 Flags to apply when opening the file, e.g.
294 *                              O_CREATE
295 * @return A pointer to the new libtrace IO writer, or NULL if an error occurs
296 */
[b5af22c]297iow_t *wandio_wcreate(const char *filename, int compression_type, int compression_level, int flags);
[81c0b9e]298
299/** Writes the contents of a buffer using a libtrace IO writer.
300 *
301 * @param iow           The IO writer to write the data with
302 * @param buffer        The buffer to write out
303 * @param len           The amount of writable data in the buffer
304 * @return The amount of data written, or -1 if an error occurs
305 */
[c66068d]306off_t wandio_wwrite(iow_t *iow, const void *buffer, off_t len);
[81c0b9e]307
308/** Destroys a libtrace IO writer, closing the file and freeing the writer
309 * structure.
310 *
311 * @param iow           The IO writer to destroy
312 */
[c66068d]313void wandio_wdestroy(iow_t *iow);
314
[81c0b9e]315/** @} */
[29d4438]316
317/** @name libtraceio options
318 * @{ */
319extern int force_directio_read;
320extern int force_directio_write;
321extern uint64_t write_waits;
322extern uint64_t read_waits;
[6f8745b]323extern unsigned int use_threads;
[f258932]324extern unsigned int max_buffers;
[29d4438]325/* @} */
326
[c66068d]327#endif
Note: See TracBrowser for help on using the repository browser.