1 #ifndef INCLUDED_READ_H
2 #define INCLUDED_READ_H
3 /* vim: set ts=8 sts=4 sw=4 tw=80 noet: */
4 /*======================================================================
5 Copyright (C) 2004,2005,2009 Walter Doekes <walter+tthsum@wjd.nu>
6 This file is part of tthsum.
7 
8 tthsum is free software: you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation, either version 3 of the License, or
11 (at your option) any later version.
12 
13 tthsum is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 GNU General Public License for more details.
17 
18 You should have received a copy of the GNU General Public License
19 along with tthsum.  If not, see <http://www.gnu.org/licenses/>.
20 ======================================================================*/
21 
22 /**
23  * Functions to read streams of data, usually from files. It exposes
24  * an opaque rofile struct that you can pass around without having to
25  * worry about what type of thing it is you're reading. Features: the
26  * read operations guarantee to return multiples of 1024 bytes, except
27  * for the last read (at EOF).
28  */
29 
30 #include "types.h"
31 
32 #ifdef __cplusplus
33 extern "C" {
34 #endif /* __cplusplus */
35 
36 /**
37  * The read-only file stream object, forward declaration of opaque object.
38  */
39 struct rofile;
40 
41 /**
42  * Construct a rofile object from in-memory data.
43  */
44 struct rofile* rofopen_mem(const char* data, unsigned length);
45 
46 /**
47  * Construct a rofile object from a file. The reads will use native memory
48  * map functions.
49  */
50 struct rofile* rofopen_mmap(const char* filename);
51 
52 /**
53  * Construct a rofile object from an open file descriptor. The reads will use
54  * the read(2) syscall.
55  */
56 struct rofile* rofopen_sysfd(int fd);
57 
58 /**
59  * A shortcut to rofopen_sysfd which opens stdin.
60  */
61 struct rofile* rofopen_sysfd_stdin();
62 
63 /**
64  * Construct a rofile object from a file. The reads will use the read(2)
65  * syscall.
66  */
67 struct rofile* rofopen_sysfile(const char* filename);
68 
69 /**
70  * Get info from the rofile struct. The blocksize specifies the sizes you'll
71  * get with rofread, except for the last read.
72  */
73 void rofinfo(unsigned* blocksize, uint64_t* filesize, struct rofile* stream);
74 
75 /**
76  * Get the next block of data. Returns 1 when there is data, 0 when there is
77  * not and -1 if an error occurred. rofread will _always_ return blocksize
78  * data, unless the file reaches EOF.
79  */
80 int rofread(const char** next, unsigned* size, struct rofile* stream);
81 
82 /**
83  * Close the file opened with one of the rofopen functions.
84  */
85 void rofclose(struct rofile* stream);
86 
87 /**
88  * Read the entire contents of the rofile and close it afterwards. Returns the
89  * contents as a malloc'ed string or NULL on failure. It will accept a NULL as
90  * argument so you can safely use one of the rofopen functions as argument.
91  */
92 char* rof_readall(struct rofile* stream, unsigned* length);
93 
94 #ifdef __cplusplus
95 } /* extern "C" */
96 #endif /* __cplusplus */
97 
98 #endif /* INCLUDED_READ_H */
99