source: lib/wandio.h @ 81c0b9e

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