2 This file is part of GNUnet.
3 (C) 2009 Christian Grothoff (and other contributing authors)
5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 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 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
22 * @file include/gnunet_bio_lib.h
23 * @brief buffered IO API
24 * @author Christian Grothoff
25 * @defgroup bio Buffered binary disk IO (with endianess conversion)
29 #ifndef GNUNET_BIO_LIB_H
30 #define GNUNET_BIO_LIB_H
32 #include "gnunet_container_lib.h"
37 #if 0 /* keep Emacsens' auto-indent happy */
44 * Handle for buffered reading.
46 struct GNUNET_BIO_ReadHandle;
50 * Open a file for reading.
52 * @param fn file name to be opened
53 * @return IO handle on success, NULL on error
55 struct GNUNET_BIO_ReadHandle *
56 GNUNET_BIO_read_open (const char *fn);
60 * Close an open file. Reports if any errors reading
61 * from the file were encountered.
63 * @param h file handle
64 * @param emsg set to the error message
65 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
68 GNUNET_BIO_read_close (struct GNUNET_BIO_ReadHandle *h, char **emsg);
72 * Read the contents of a binary file into a buffer.
74 * @param h handle to an open file
75 * @param what describes what is being read (for error message creation)
76 * @param result the buffer to write the result to
77 * @param len the number of bytes to read
78 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
81 GNUNET_BIO_read (struct GNUNET_BIO_ReadHandle *h, const char *what,
82 void *result, size_t len);
86 * Read the contents of a binary file into a buffer.
88 * @param h handle to an open file
89 * @param file name of the source file
90 * @param line line number in the source file
91 * @param result the buffer to write the result to
92 * @param len the number of bytes to read
93 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
96 GNUNET_BIO_read_fn (struct GNUNET_BIO_ReadHandle *h,
97 const char *file, int line,
98 void *result, size_t len);
101 * Read 0-terminated string from a file.
103 * @param h handle to an open file
104 * @param what describes what is being read (for error message creation)
105 * @param result the buffer to store a pointer to the (allocated) string to
106 * (note that *result could be set to NULL as well)
107 * @param max_length maximum allowed length for the string
108 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
111 GNUNET_BIO_read_string (struct GNUNET_BIO_ReadHandle *h, const char *what,
112 char **result, size_t max_length);
116 * Read metadata container from a file.
118 * @param h handle to an open file
119 * @param what describes what is being read (for error message creation)
120 * @param result the buffer to store a pointer to the (allocated) metadata
121 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
124 GNUNET_BIO_read_meta_data (struct GNUNET_BIO_ReadHandle *h, const char *what,
125 struct GNUNET_CONTAINER_MetaData **result);
131 * @param h hande to open file
132 * @param f address of float to read
134 #define GNUNET_BIO_read_float(h, f) (GNUNET_BIO_read_fn (h, __FILE__, __LINE__, f, sizeof(float)))
141 * @param h hande to open file
142 * @param f address of double to read
144 #define GNUNET_BIO_read_double(h, f) (GNUNET_BIO_read_fn (h, __FILE__, __LINE__, f, sizeof(double)))
148 * Read an (u)int32_t.
150 * @param h hande to open file
151 * @param file name of the source file
152 * @param line line number in the code
153 * @param i address of 32-bit integer to read
154 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
157 GNUNET_BIO_read_int32__ (struct GNUNET_BIO_ReadHandle *h, const char *file,
158 int line, int32_t * i);
162 * Read an (u)int32_t.
164 * @param h hande to open file
165 * @param i address of 32-bit integer to read
167 #define GNUNET_BIO_read_int32(h, i) GNUNET_BIO_read_int32__ (h, __FILE__, __LINE__, (int32_t*) i)
171 * Read an (u)int64_t.
173 * @param h hande to open file
174 * @param file name of the source file
175 * @param line line number in the code
176 * @param i address of 64-bit integer to read
177 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
180 GNUNET_BIO_read_int64__ (struct GNUNET_BIO_ReadHandle *h, const char *file,
181 int line, int64_t * i);
185 * Read an (u)int64_t.
187 * @param h hande to open file
188 * @param i address of 64-bit integer to read
190 #define GNUNET_BIO_read_int64(h, i) GNUNET_BIO_read_int64__ (h, __FILE__, __LINE__, (int64_t*) i)
194 * Handle for buffered writing.
196 struct GNUNET_BIO_WriteHandle;
199 * Open a file for writing.
201 * @param fn file name to be opened
202 * @return IO handle on success, NULL on error
204 struct GNUNET_BIO_WriteHandle *
205 GNUNET_BIO_write_open (const char *fn);
209 * Close an open file for writing.
211 * @param h file handle
212 * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
215 GNUNET_BIO_write_close (struct GNUNET_BIO_WriteHandle *h);
219 * Write a buffer to a file.
221 * @param h handle to open file
222 * @param buffer the data to write
223 * @param n number of bytes to write
224 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
227 GNUNET_BIO_write (struct GNUNET_BIO_WriteHandle *h, const void *buffer,
232 * Force a buffered writer to flush its buffer
234 * @param h the writer handle
235 * @return #GNUNET_OK upon success. Upon failure #GNUNET_SYSERR is returned and
239 GNUNET_BIO_flush (struct GNUNET_BIO_WriteHandle *h);
243 * Write a string to a file.
245 * @param h handle to open file
246 * @param s string to write (can be NULL)
247 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
250 GNUNET_BIO_write_string (struct GNUNET_BIO_WriteHandle *h, const char *s);
254 * Write metadata container to a file.
256 * @param h handle to open file
257 * @param m metadata to write
258 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
261 GNUNET_BIO_write_meta_data (struct GNUNET_BIO_WriteHandle *h,
262 const struct GNUNET_CONTAINER_MetaData *m);
269 * @param h hande to open file
270 * @param f float to write (must be a variable)
272 #define GNUNET_BIO_write_float(h, f) GNUNET_BIO_write (h, &f, sizeof(float))
279 * @param h hande to open file
280 * @param f double to write (must be a variable)
282 #define GNUNET_BIO_write_double(h, f) GNUNET_BIO_write (h, &f, sizeof(double))
286 * Write an (u)int32_t.
288 * @param h hande to open file
289 * @param i 32-bit integer to write
290 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
293 GNUNET_BIO_write_int32 (struct GNUNET_BIO_WriteHandle *h, int32_t i);
297 * Write an (u)int64_t.
299 * @param h hande to open file
300 * @param i 64-bit integer to write
301 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
304 GNUNET_BIO_write_int64 (struct GNUNET_BIO_WriteHandle *h, int64_t i);
307 #if 0 /* keep Emacsens' auto-indent happy */
314 /** @} */ /* end of group bio */
316 /* ifndef GNUNET_BIO_LIB_H */
318 /* end of gnunet_bio_lib.h */