2 This file is part of GNUnet.
3 Copyright (C) 2009 GNUnet e.V.
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your option) any later version.
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Affero General Public License for more details.
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
18 SPDX-License-Identifier: AGPL3.0-or-later
22 * @author Christian Grothoff
27 * @defgroup bio BIO library
28 * Buffered binary disk IO (with endianess conversion)
32 #ifndef GNUNET_BIO_LIB_H
33 #define GNUNET_BIO_LIB_H
35 #include "gnunet_container_lib.h"
40 #if 0 /* keep Emacsens' auto-indent happy */
46 * Handle for buffered reading.
48 struct GNUNET_BIO_ReadHandle;
52 * Open a file for reading.
54 * @param fn file name to be opened
55 * @return IO handle on success, NULL on error
57 struct GNUNET_BIO_ReadHandle *
58 GNUNET_BIO_read_open (const char *fn);
62 * Close an open file. Reports if any errors reading
63 * from the file were encountered.
65 * @param h file handle
66 * @param emsg set to the error message
67 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
70 GNUNET_BIO_read_close (struct GNUNET_BIO_ReadHandle *h, char **emsg);
74 * Read the contents of a binary file into a buffer.
76 * @param h handle to an open file
77 * @param what describes what is being read (for error message creation)
78 * @param result the buffer to write the result to
79 * @param len the number of bytes to read
80 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
83 GNUNET_BIO_read (struct GNUNET_BIO_ReadHandle *h, const char *what,
84 void *result, size_t len);
88 * Read the contents of a binary file into a buffer.
90 * @param h handle to an open file
91 * @param file name of the source file
92 * @param line line number in the source file
93 * @param result the buffer to write the result to
94 * @param len the number of bytes to read
95 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
98 GNUNET_BIO_read_fn (struct GNUNET_BIO_ReadHandle *h,
99 const char *file, int line,
100 void *result, size_t len);
103 * Read 0-terminated string from a file.
105 * @param h handle to an open file
106 * @param what describes what is being read (for error message creation)
107 * @param result the buffer to store a pointer to the (allocated) string to
108 * (note that *result could be set to NULL as well)
109 * @param max_length maximum allowed length for the string
110 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
113 GNUNET_BIO_read_string (struct GNUNET_BIO_ReadHandle *h, const char *what,
114 char **result, size_t max_length);
118 * Read metadata container from a file.
120 * @param h handle to an open file
121 * @param what describes what is being read (for error message creation)
122 * @param result the buffer to store a pointer to the (allocated) metadata
123 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
126 GNUNET_BIO_read_meta_data (struct GNUNET_BIO_ReadHandle *h, const char *what,
127 struct GNUNET_CONTAINER_MetaData **result);
133 * @param h hande to open file
134 * @param f address of float to read
136 #define GNUNET_BIO_read_float(h, f) (GNUNET_BIO_read_fn (h, __FILE__, __LINE__, f, sizeof(float)))
143 * @param h hande to open file
144 * @param f address of double to read
146 #define GNUNET_BIO_read_double(h, f) (GNUNET_BIO_read_fn (h, __FILE__, __LINE__, f, sizeof(double)))
150 * Read an (u)int32_t.
152 * @param h hande to open file
153 * @param file name of the source file
154 * @param line line number in the code
155 * @param i address of 32-bit integer to read
156 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
159 GNUNET_BIO_read_int32__ (struct GNUNET_BIO_ReadHandle *h, const char *file,
160 int line, int32_t * i);
164 * Read an (u)int32_t.
166 * @param h hande to open file
167 * @param i address of 32-bit integer to read
169 #define GNUNET_BIO_read_int32(h, i) GNUNET_BIO_read_int32__ (h, __FILE__, __LINE__, (int32_t*) i)
173 * Read an (u)int64_t.
175 * @param h hande to open file
176 * @param file name of the source file
177 * @param line line number in the code
178 * @param i address of 64-bit integer to read
179 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
182 GNUNET_BIO_read_int64__ (struct GNUNET_BIO_ReadHandle *h, const char *file,
183 int line, int64_t * i);
187 * Read an (u)int64_t.
189 * @param h hande to open file
190 * @param i address of 64-bit integer to read
192 #define GNUNET_BIO_read_int64(h, i) GNUNET_BIO_read_int64__ (h, __FILE__, __LINE__, (int64_t*) i)
196 * Handle for buffered writing.
198 struct GNUNET_BIO_WriteHandle;
201 * Open a file for writing.
203 * @param fn file name to be opened
204 * @return IO handle on success, NULL on error
206 struct GNUNET_BIO_WriteHandle *
207 GNUNET_BIO_write_open (const char *fn);
211 * Close an open file for writing.
213 * @param h file handle
214 * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
217 GNUNET_BIO_write_close (struct GNUNET_BIO_WriteHandle *h);
221 * Write a buffer to a file.
223 * @param h handle to open file
224 * @param buffer the data to write
225 * @param n number of bytes to write
226 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
229 GNUNET_BIO_write (struct GNUNET_BIO_WriteHandle *h, const void *buffer,
234 * Force a buffered writer to flush its buffer
236 * @param h the writer handle
237 * @return #GNUNET_OK upon success. Upon failure #GNUNET_SYSERR is returned and
241 GNUNET_BIO_flush (struct GNUNET_BIO_WriteHandle *h);
245 * Write a string to a file.
247 * @param h handle to open file
248 * @param s string to write (can be NULL)
249 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
252 GNUNET_BIO_write_string (struct GNUNET_BIO_WriteHandle *h, const char *s);
256 * Write metadata container to a file.
258 * @param h handle to open file
259 * @param m metadata to write
260 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
263 GNUNET_BIO_write_meta_data (struct GNUNET_BIO_WriteHandle *h,
264 const struct GNUNET_CONTAINER_MetaData *m);
271 * @param h hande to open file
272 * @param f float to write (must be a variable)
274 #define GNUNET_BIO_write_float(h, f) GNUNET_BIO_write (h, &f, sizeof(float))
281 * @param h hande to open file
282 * @param f double to write (must be a variable)
284 #define GNUNET_BIO_write_double(h, f) GNUNET_BIO_write (h, &f, sizeof(double))
288 * Write an (u)int32_t.
290 * @param h hande to open file
291 * @param i 32-bit integer to write
292 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
295 GNUNET_BIO_write_int32 (struct GNUNET_BIO_WriteHandle *h, int32_t i);
299 * Write an (u)int64_t.
301 * @param h hande to open file
302 * @param i 64-bit integer to write
303 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
306 GNUNET_BIO_write_int64 (struct GNUNET_BIO_WriteHandle *h, int64_t i);
309 #if 0 /* keep Emacsens' auto-indent happy */
316 /* ifndef GNUNET_BIO_LIB_H */
319 /** @} */ /* end of group bio */
321 /* end of gnunet_bio_lib.h */