source: libwandio/wandio.h @ 10f924c

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 10f924c was 10f924c, checked in by Shane Alcock <salcock@…>, 7 years ago

Fixed broken -fvisibility check in configure

  • Added a m4 script that does this properly rather than our hax gcc version check.
  • Tidied up CFLAGS in configure so we aren't adding the same sets of flags multiple times
  • Created a wandio_internal.h file for storing global variables that shouldn't be made public

Thanks to Alistair King, whose patch to try and make this work for
non-gcc systems brought my attention to just how broken this was :)

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